statistics visualize : ドキュメントの更新 (#1302)

* サンプルを追加

* 不具合修正

* ドキュメントの修正

* update doc

annofabcli/input_data/list_all_input_data_merged_task.py

@@ -130,7 +130,7 @@ def match_parent_task_list_of_input_data_with(input_data: Dict[str, Any], *, is_
 class ListInputDataMergedTask(CommandLine):
     @staticmethod
     def validate(args: argparse.Namespace) -> bool:
-        COMMON_MESSAGE = "annofabcli input_data list_merged_task: error:"  # noqa: N806
+        COMMON_MESSAGE = "annofabcli input_data list_all_merged_task: error:"  # noqa: N806
         if args.project_id is None and (args.input_data_json is None or args.task_json is None):
             print(  # noqa: T201
                 f"{COMMON_MESSAGE} '--project_id' か、'--task_json'/'--input_data_json'ペアのいずれかを指定する必要があります。",

annofabcli/task/list_all_tasks_added_task_history.py

@@ -140,7 +140,7 @@ class ListAllTasksAddedTaskHistory(CommandLine):
 
     @staticmethod
     def validate(args: argparse.Namespace) -> bool:
-        COMMON_MESSAGE = "annofabcli task list_merged_task_history: error:"  # noqa: N806
+        COMMON_MESSAGE = "annofabcli task list_all_added_task_history: error:"  # noqa: N806
         if (args.task_json is None and args.task_history_json is not None) or (args.task_json is not None and args.task_history_json is None):
             print(  # noqa: T201
                 f"{COMMON_MESSAGE} '--task_json'と'--task_history_json'の両方を指定する必要があります。",

docs/command_reference/statistics/visualize.rst

@@ -251,11 +251,13 @@ CSVには以下の列が存在している必要があります。
    visualize_output_rst/教師付開始日毎の生産量と生産性_csv.rst
    visualize_output_rst/全体の生産性と品質_csv.rst
    visualize_output_rst/ユーザ_日付list-作業時間_csv.rst
+   visualize_output_rst/task-worktime-list-by-user-phase_csv
 
    visualize_output_rst/折れ線-横軸_日-全体_html.rst
    visualize_output_rst/累積折れ線-横軸_日-全体_html.rst
    visualize_output_rst/折れ線-横軸_教師付開始日-全体_html.rst
    visualize_output_rst/累積折れ線-横軸_アノテーション数-phase者用_html.rst
+   visualize_output_rst/折れ線-横軸_教師付開始日-縦軸_アノテーション単位の指標-phase用.html
    visualize_output_rst/累積折れ線-横軸_日-縦軸_作業時間_html.rst
 
    visualize_output_rst/散布図-アノテーションあたり作業時間と品質の関係-教師付者用_html.rst

docs/command_reference/statistics/visualize/out_dir/task-worktime-by-user-phase.csv

@@ -0,0 +1,6 @@
+project_id,task_id,status,phase,phase_stage,account_id,user_id,username,biography,worktime_hour,task_count,input_data_count,annotation_count,pointed_out_inspection_comment_count,rejected_count,started_datetime
+prj1,task1,complete,annotation,1,alice,alice,Alice,USA,2,1,2,100,5,1,2024-10-25T11:00:00.000+09:00
+prj1,task1,complete,inspection,1,bob,bob,Bob,USA,0.5,0.5,1,50,0,0,2024-10-26T11:00:00.000+09:00
+prj1,task2,complete,annotation,1,bob,bob,Bob,USA,2,1,4,200,6,1,2024-10-27T11:00:00.000+09:00
+prj1,task2,complete,inspection,1,alice,alice,Alice,USA,0.5,0.5,2,100,0,0,2024-10-28T11:00:00.000+09:00
+prj1,task2,complete,acceptance,1,alice,alice,Alice,USA,0.1,1,4,200,0,0,2024-10-29T11:00:00.000+09:00

docs/command_reference/statistics/visualize_output_rst/task-worktime-list-by-user-phase_csv.rst

@@ -0,0 +1,11 @@
+===============================================================
+task-worktime-list-by-user-phase.csv
+===============================================================
+
+タスク、フェーズ、ユーザーごとの作業時間と生産量が記載されています。
+
+このCSVファイルは、他のCSVファイルやグラフの作成に利用するための中間ファイルです。
+ユーザーが直接確認することを想定していません。
+
+
+`タスクlist.csvのサンプル <https://github.com/kurusugawa-computer/annofab-cli/blob/main/docs/command_reference/statistics/visualize/out_dir/task-worktime-list-by-user-phase.csv>`_

docs/command_reference/statistics/visualize_output_rst/メンバごとの生産性と品質_csv.rst

@@ -45,7 +45,7 @@
 
 .. note::
 
-    あるタスクの教師付フェーズを複数人で作業した場合、ユーザーごとの計測作業時間（ ``monitored_worktime_hour`` ）で按分した値を生産量として算出します。
+    複数人で同じタスクの同じフェーズを作業した場合、ユーザーごとの計測作業時間（ ``monitored_worktime_hour`` ）で按分した値を生産量として算出します。
     たとえば、task1の教師付フェーズの作業にユーザーAが45分、ユーザーBが15分かかったとします。その場合、「ユーザーAはtask1を0.75個、ユーザーBはtask1を0.25個のタスクを作業した」とみなします。
 
     上記の生産量は本来整数ですが、ユーザーごとの計測作業時間で按分しているため、小数点表記になる場合があります。

docs/command_reference/statistics/visualize_output_rst/折れ線-横軸_教師付開始日-縦軸_アノテーション単位の指標-phase用.html.rst

@@ -0,0 +1,24 @@
+====================================================================================
+line-graph/{phase}/折れ線-横軸_教師付開始日-縦軸_アノテーション単位の指標-{phase}用.html
+====================================================================================
+
+横軸がフェーズの開始日、縦軸がアノテーション単位の指標（作業時間、指摘数など）の折れ線グラフです。ユーザーごとにプロットされます。
+
+フェーズごとにhtmlファイルは出力されます。
+
+グラフのデータは :doc:`task-worktime-list-by-user-phase_csv` を参照しています。
+
+
+
+
+.. image:: ../visualize/img/教師付開始日ごとのアノテーションあたり計測作業時間.png
+
+`累積折れ線-横軸_アノテーション数-教師付者用.htmlのサンプル <https://kurusugawa-computer.github.io/annofab-cli/command_reference/statistics/visualize/out_dir/line-graph/折れ線-横軸_教師付開始日-縦軸_アノテーション単位の指標-教師付者用.html>`_
+
+
+.. note::
+
+    複数人で同じあタスクの同じフェーズを作業した場合、ユーザーごとの作業時間で按分した値を生産量や指摘数として算出します。
+    たとえば、task1の教師付フェーズの作業にユーザーAが45分、ユーザーBが15分かかったとします。その場合、「ユーザーAはtask1を0.75個、ユーザーBはtask1を0.25個のタスクを作業した」とみなします。
+
+

docs/command_reference/statistics/visualize_output_rst/累積折れ線-横軸_アノテーション数-phase者用_html.rst

@@ -3,14 +3,27 @@ line-graph/{phase}/累積折れ線-横軸_アノテーション数-{phase}者用
 ====================================================================================
 
 作業したタスクに含まれているアノテーション数の累積値と、作業時間などの累積値をタスクごとにプロットした折れ線グラフです。
-グラフのデータは :doc:`タスクlist_csv` を参照しています。
+フェーズごとにhtmlファイルは出力されます。
+
+グラフのデータは :doc:`task-worktime-list-by-user-phase_csv` を参照しています。
 
 このグラフでは、ユーザーごとの生産性と品質の習熟傾向を確認できます。
 
 
 `累積折れ線-横軸_アノテーション数-教師付者用.htmlのサンプル <https://kurusugawa-computer.github.io/annofab-cli/command_reference/statistics/visualize/out_dir/line-graph/%E7%B4%AF%E7%A9%8D%E6%8A%98%E3%82%8C%E7%B7%9A-%E6%A8%AA%E8%BB%B8_%E3%82%A2%E3%83%8E%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E6%95%B0-%E6%95%99%E5%B8%AB%E4%BB%98%E8%80%85%E7%94%A8.html>`_
 
 
+.. note::
+
+    複数人で同じあタスクの同じフェーズを作業した場合、ユーザーごとの作業時間で按分した値を生産量や指摘数として算出します。
+    たとえば、task1の教師付フェーズの作業にユーザーAが45分、ユーザーBが15分かかったとします。その場合、「ユーザーAはtask1を0.75個、ユーザーBはtask1を0.25個のタスクを作業した」とみなします。
+
+
+
+生産性の習熟傾向を表すグラフ
+====================================================================================
+
+
 以下のグラフは、作業したタスクに含まれているアノテーション数の累積値と、教師付作業時間の累積値をプロットした折れ線グラフです。
 折れ線の傾きは生産性を表しています。
 生産性が高いほど、グラフの傾きは小さくなります。
@@ -19,17 +32,13 @@ line-graph/{phase}/累積折れ線-横軸_アノテーション数-{phase}者用
 
 
 
-.. note::
-
-    あるタスクを作業したユーザは「最初に作業したユーザ」とみなして、プロットしています。
-    たとえば、task1の教師付の作業にユーザAが45分、ユーザBが15分かかったとします。その場合、「ユーザAはtask1を60分作業した、ユーザBはtask1を作業していない」とみなします。
-    したがって、1個のタスクを複数人で均等に作業する場合は、生産性を正しく表現できない恐れがあります。
 
 
+品質の習熟傾向を表すグラフ
+====================================================================================
 
-以下のグラフは、作業したタスクに含まれているアノテーション数の累積値と、検査コメント数の累積値をプロットした折れ線グラフで、教師付の品質を評価できます。
-検査コメント数とは指摘を受けたコメントの数です。
-
+以下のグラフは、作業したタスクに含まれているアノテーション数の累積値と、検査コメント数（指摘を受けたコメントの数）の累積値をプロットした折れ線グラフです。
+教師付フェーズの作業の品質を評価できます。
 教師付の品質が高いほど、グラフの傾きは小さくなる傾向にあります。
 
 .. image:: ../visualize/img/アノテーション数と検査コメント数の累積グラフ.png
@@ -41,10 +50,3 @@ line-graph/{phase}/累積折れ線-横軸_アノテーション数-{phase}者用
     また軽微な指摘も重大な指摘も「同じレベルの指摘」として扱っているため、正しく品質を評価するには、指摘の中身まで確認した方が良い場合もあります。
 
 
-
-受入作業した場合は、`累積折れ線-横軸_アノテーション数-受入者用.html <https://kurusugawa-computer.github.io/annofab-cli/command_reference/statistics/visualize/out_dir/line-graph/%E7%B4%AF%E7%A9%8D%E6%8A%98%E3%82%8C%E7%B7%9A-%E6%A8%AA%E8%BB%B8_%E3%82%A2%E3%83%8E%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E6%95%B0-%E5%8F%97%E5%85%A5%E8%80%85%E7%94%A8.html>`_ も出力します。
-
-.. warning::
-
-    一般的に検査/受入作業は、複数人で作業します。したがって、検査/受入の生産性は正しく表現できていない恐れがあります。
-

tests/test_input_data.py

@@ -222,7 +222,7 @@ def test_list_input_data_merged_task(self):
         main(
             [
                 "input_data",
-                "list_merged_task",
+                "list_all_merged_task",
                 "--project_id",
                 project_id,
                 "--output",

tests/test_job.py

@@ -67,18 +67,6 @@ def test_list_last_job(self):
             ]
         )
 
-    def test_list_task_creation_history(self):
-        main(
-            [
-                "job",
-                "list_task_creation_history",
-                "--project_id",
-                project_id,
-                "--output",
-                str(out_dir / "list_task_creation_history-out.csv"),
-            ]
-        )
-
     def test_wait(self):
         main(
             [