Skip to content
This repository was archived by the owner on Apr 12, 2023. It is now read-only.

EN v2のパラメータ設計の経緯を残すドキュメント #1051

Merged
merged 2 commits into from
Aug 23, 2022
Merged

EN v2のパラメータ設計の経緯を残すドキュメント #1051

merged 2 commits into from
Aug 23, 2022

Conversation

daisuke-nogami
Copy link
Collaborator

開発チーム内検討資料のpptをドキュメントに起こしたもの

Issue 番号 / Issue ID

目的 / Purpose

  • EN v2で大きく変更した電波強度に関するパラメータ設計の経緯をドキュメントに残す

変更内容 / Changes

  • 開発チーム内検討資料のpptをもとにドキュメント化し、技術説明に追加する

破壊的変更をもたらしますか / Does this introduce a breaking change?

[ ] Yes
[x] No

Pull Request の種類 / Pull Request type

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[x] Documentation content changes
[ ] Other... Please describe:

確認事項 / What to check

  • ドキュメントとしての読みやすさを改善する(単純なスライドからの移し替えで読みにくいため)
  • exposure_data.jsonを読み解くためにこの文書を読む人を意識した加筆修正をする

その他 / Other information

Internal IDs:

@daisuke-nogami
Create design_for_upgrading_to_env2.md
cc56440 
開発チーム内検討資料のpptをドキュメントに起こしたもの
@daisuke-nogami
add figure files
6f81999
@daisuke-nogami daisuke-nogami self-assigned this Jun 21, 2022
@daisuke-nogami daisuke-nogami mentioned this pull request Jun 21, 2022
Closed
@keiji keiji self-requested a review June 21, 2022 03:19
daisuke-nogami
daisuke-nogami commented Jul 28, 2022
View reviewed changes
Copy link
Collaborator Author

@daisuke-nogami daisuke-nogami left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

大きく修正すべきポイントをまずはメモ

documents/content/docs/appendix/design_for_upgrading_to_env2.md

- リスク「スコア」という名前からは、なにか「リスクの大きさに比例する」ものを想像しがちであり、距離・時間と比例する関係にさせないといけないと考えがちである
- 例：「距離が半分ならスコアは2倍になる」「距離が10分の1ならばスコアは10倍」など
- しかし、COCOAは、濃厚接触の可能性の「有無」だけを判断するものであり、その目的を踏まえると、距離が1m以内であれば、どのような距離でも15分間接触しなければ閾値を超えないようにスコアを設計しなければならない
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

この前提に「リスクの大きさに精密に比例させることは、技術的制約（距離と時間のみの把握であること・距離を精密に測定できないこと）より実現出来ない」という制約があることを書かないといけない。

～～という制約がある⇒考えて見ればCOCOAは注意喚起をする/しないだけを判断できればよいわけだ⇒なので閾値を上回る・上回らないことだけ分かれば良い

という論理展開に更新する

documents/content/docs/appendix/design_for_upgrading_to_env2.md

なお、当初はv2.0.0では、ENv2の機能を活用した新しい機能も実装する予定だったが、v2.1.0以降に先送りとなってしまったため本文書では取り扱わない。
検討の経緯は、github discussions [EN v2を搭載するCOCOAで実現したい機能について #532](https://github.com/cocoa-mhlw/cocoa/discussions/532) を参照のこと。

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

いわゆる今来産業的な分かりやすいサマリーが必要

documents/content/docs/appendix/design_for_upgrading_to_env2.md
- 1.0m以上の場合は、これより低いウエイトの結果が多数入ることでこの閾値を下回るようになる
- 1.5m/2.0m/3.0mのいずれかを取り得る距離は、更に約半分にしたウエイト（60%）とすることで、リスクスコアや接触時間の合計の情報と合わせ、将来的に接触通知を出す距離を2.0mまで伸ばしたときの影響範囲を把握出来るようにする
- 閾値は、900秒(=15分)に130%をかけ、1170とした。

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

最も電波が弱いセグメントの係数を0としていない理由と、0としなかったことによる誤検知の可能性をどのように回避しているかを書く

documents/content/docs/appendix/design_for_upgrading_to_env2.md

![パラメータ値(Attenuation, Weight, 閾値)修正後](/cocoa/appendix/upgrading_v2_fig11.png)

※補足…最終的に設定したパラメータで近距離のウエイトを100%としたことについて
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

最後に慌てて加筆したのがそのままの状態になっているので表現がこなれていない。
適切な表現に直しつつ、手前の箇条書きとマージさせる

@daisuke-nogami
Copy link
Collaborator Author

画像入りの形で本文のプレビューができないという指摘があったのでgist化。
https://gist.github.com/daisuke-nogami/808dfc8935cf4649e4272eddc13cdaf9

このpull-requestが取り込まれたらgistは削除する

daisuke-nogami
daisuke-nogami commented Aug 8, 2022
View reviewed changes
Copy link
Collaborator Author

@daisuke-nogami daisuke-nogami left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

文章の大改造が必要。

documents/content/docs/appendix/design_for_upgrading_to_env2.md
前述の正規分布・標準誤差を前提に計算すると、電波強度が取り得る範囲が以下の様に図示できる。
（濃い色は±σなので、約6割の測定結果がこの範囲に入ると考えられる）

![距離別の電波強度の分布](/cocoa/appendix/upgrading_v2_fig5.png)
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

この図をみて「せや！◯◯dBは◯mや！」という文章を読まない反応がみられるので、作業記録ではなく、結論から順番に並べる必要がある。ページを分けるとそこだけ切り出して読まれるので同じページ内の順序を変える。

documents/content/docs/appendix/design_for_upgrading_to_env2.md
type: docs
---

## Exposure Notification API v2へのバージョンアップに関する技術的な検討内容について
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

読み手が分かれるので、読み手別の分かりやすいサマリーにする。

  • 共通で読んで欲しいこと：COCOAが何を目的としているかの大前提を示す
    • 感染症の悪影響を減らすために、「過小評価せず注意してほしいリスクを伝える（＋利他的な行動を促す）」もの
    • 一定の線を越えないリスクは伝えず、一定の線を越えたリスクはありのままを伝える
    • ※読み物的に、過去からの推移も参考で示す
  • 利用者として、判定する仕組みを知りたい
    • ⇒ 何が出来ていて何が出来ていないかを知る
    • 1m以内・15分相当の状態にあった可能性が高いことかどうかが分かる
    • それぞれの瞬間にどのような距離にあったかは分からない
    • 結果として承服しがたい動作をする状態が生まれるのは～～という状況である
  • ツール開発者として、exposure_data.jsonを正しく読むための知識を得たい
    • ⇒ exposure_data.jsonから分かって言い切れることと、断定できずに言い切れないことを伝える
    • ENが出力する情報しか使えないので、時刻・機種・補正前の電波強度などは分からないこと
    • ユーザのニーズとリテラシーに合わせた出力が望ましいこと（詳細を把握すると逆に不安が増えるなど）
  • 付録：電波強度に関する基礎知識
  • 付録：パラメータ検討の経緯

documents/content/docs/appendix/design_for_upgrading_to_env2.md

![パラメータ値(Attenuation, Weight, 閾値)当初案](/cocoa/appendix/upgrading_v2_fig9.png)

#### 実測値による当初案パラメータ検証と修正
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

当初案はどこかに残すべきだが、どのように残すべきか

@daisuke-nogami
Copy link
Collaborator Author

#1121

における質疑も反映させる必要がある

@keiji
Copy link
Collaborator

keiji commented Aug 22, 2022

1回確定（merge）させてから、変更を適宜反映していくのがいいと思いますよ。

パラメーターは一度決めて終わりではなく、必要に応じて外部ファイルを書き換えて調整できる。そういう風に作っているので。

@daisuke-nogami
Copy link
Collaborator Author

あー、そうですね。
「 #1121 における質疑の反映」と書いたのは、パラメータを変えたりする前に、もともとのドキュメントで分かりにくいところがあったら直そう、とも思ったのですが、この調子だと確かに永遠に確定しないですね…

いったん、このpull-requestをdraftではなくするので、「これだけは直しておかないとマージできない」と思われる部分だけ指摘いただけますか…？

@daisuke-nogami daisuke-nogami marked this pull request as ready for review August 22, 2022 11:39
@keiji keiji added the documentation 機能の改善や修正ではなく、ドキュメント類に関連するIssue label Aug 23, 2022
keiji
keiji approved these changes Aug 23, 2022
View reviewed changes
Copy link
Collaborator

@keiji keiji left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@keiji keiji merged commit 8c9f98b into develop Aug 23, 2022
@keiji keiji deleted the documents/draft-en-v2-upgrade-record branch August 23, 2022 16:28
@keiji keiji restored the documents/draft-en-v2-upgrade-record branch August 23, 2022 16:28
@daisuke-nogami daisuke-nogami deleted the documents/draft-en-v2-upgrade-record branch August 24, 2022 00:59
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@keiji keiji keiji approved these changes

Assignees

@daisuke-nogami daisuke-nogami

Labels
documentation 機能の改善や修正ではなく、ドキュメント類に関連するIssue
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

COCOA2(v2.0.0) リリース
2 participants
@daisuke-nogami @keiji