statistics visualize#

Description#

生産量や生産性に関するCSVファイルやグラフを出力します。

出力結果から主に以下のことが分かります。

  • 生産量や生産性の日ごとの推移

  • ユーザごとの生産性と品質

Examples#

基本的な使い方#

出力対象のプロジェクトのproject_idを指定してください。複数のプロジェクトを指定することも可能です。

$ annofabcli statistics visualize --project_id prj1 --output_dir out_dir

集計期間も指定できます。--start_date は、指定した日付以降に教師付を開始したタスクを集計します。--end_date は、指定した日付以前に更新されたタスクを集計します。

$ annofabcli statistics visualize --project_id prj1 --output_dir out_dir \
--start_date 2020-04-01

タスクの完了条件を指定する#

--task_completion_criteria で、集計対象のタスクの完了条件を指定できます。

acceptance_completed#

acceptance_completed を指定すると、受入フェーズで完了状態のタスクを「生産したタスク（作業が完了したタスク）」とみなして、受入フェーズ完了状態のタスクを集計対象にします。 デフォルトはこの値です。

acceptance_reached#

acceptance_reached を指定すると、受入フェーズに到達したタスクを「生産したタスク（作業が完了したタスク）」とみなして、受入フェーズのタスクを集計対象にします。 受入フェーズをアノテーションチーム以外（たとえばアノテーションを利用するAI開発者など）が作業するときなどに、利用します。

また、以下のCSVとグラフでは、受入フェーズの作業時間と生産量は0になります。 受入フェーズに到達したタスクを「生産したタスク（作業が完了したタスク）」とする場合、受入フェーズの作業は生産量に影響しないためです。

inspection_reached#

inspection_reached を指定すると、検査フェーズに到達したタスクを「生産したタスク（作業が完了したタスク）」とみなして、検査フェーズと受入フェーズのタスクを集計対象にします。 受入フェーズに到達したタスクが少ないため、暫定的に検査フェーズに到達したタスクから生産性を算出するときなどに有用なオプションです。

acceptance_reached と同様な理由で、検査フェーズと受入フェーズの作業時間と生産量は0になります。

annotation_started#

annotation_started を指定すると、教師付フェーズが着手されたタスクを「生産したタスク（作業が完了したタスク）」とみなして、教師付フェーズが着手されたタスクを集計対象にします。 このオプションは、未完了のタスクが多いときに有用です。たとえば以下のようなケースです。

  • アノテーションルールに不明瞭な部分があるため、タスクを提出することができず、教師付フェーズ保留状態のタスクが大量にある。これらのタスクは未完了だがほとんど完了しているため、生産性の評価対象タスクに加えたい。

  • アノテーション作業の終盤でアノテーションルールが変わったため、大量の受入フェーズ完了状態のタスクを教師付フェーズに差し戻した。これらのタスクは未完了だがほとんど完了しているため、生産性の評価対象タスクに加えたい。

acceptance_reached や inspection_reached とは異なり、 annotation_started では検査/受入フェーズの生産量と作業時間は0になりません。 annotation_started を指定するときは、「検査/受入フェーズをアノテーションチーム以外が作業する」とは限らないためです。

実績作業時間情報から生産性を算出する#

デフォルトではアノテーションエディタ画面を触っていた作業時間（以下、「計測作業時間」と呼ぶ）を元に、生産性を算出します。 計測作業時間はコミュニケーションしている時間やアノテーションルールを読んでいる時間を含みません。 したがって、計測作業時間から算出した生産性を元にアノテーションの生産量を見積もると、見積もりから大きく外れる恐れがあります。

アノテーションの生産量を見積もる場合は、アノテーションエディタ以外の作業も含めた作業時間（以下、「実績作業時間」と呼ぶ）で生産性を算出することを推奨します。 実績作業時間から算出した生産性を出力するには、実績作業時間が記載されたCSVを --labor_csv に渡してください。

$ annofabcli input_data put --project_id prj1 --labor_csv labor.csv \
--output out_dir/

以下、実績作業時間が記載されたCSV( labor.csv )のサンプルです。

date

account_id

actual_worktime_hour

project_id

2021-04-01

12345678-abcd-1234-abcd-1234abcd5678

8

prj1

2021-04-02

12345678-abcd-1234-abcd-1234abcd5678

6.5

prj1

複数のプロジェクトをマージする#

--project_id に複数のproject_idを指定したときに --merge を指定すると、指定したプロジェクトをマージしたディレクトリも出力します。ディレクトリ名は merge です。

$ annofabcli input_data put --project_id prj1 prj2 --output out_dir/
--merge

並列処理#

--project_id に複数のproject_idを指定したときは、並列実行が可能です。

$ annofabcli input_data put --project_id file://project_id.txt --output out_dir/
--parallelism 4

生産量のカスタマイズ#

アノテーション数を変更する#

デフォルトでは、アノテーションZIPからアノテーション数を算出します。 しかし、プリアノテーションを用いたプロジェクトなどでは、実際に生産していないプリアノテーションも「アノテーション数」に含まれてしまい、正しい生産性が算出できない場合があります。

--annotation_count_csv に実際に生産したアノテーションの個数が記載CSVファイルを指定することで、正しい生産量と生産性を算出できます。

以下はCSVファイルのサンプルです。

annotation_count.csv#
project_id,task_id,annotation_count
prj1,task1,10
prj1,task2,20

CSVには以下の列が存在している必要があります。

  • project_id

  • task_id

  • annotation_count

入力データ数を変更する#

タスクに作業しない参照用のフレームが含まれている場合に有用なオプションです。

--input_data_count_csv に実際に作業したフレーム数（入力データ数）が記載されたCSVファイルを指定します。

以下はCSVファイルのサンプルです。

annotation_count.csv#
project_id,task_id,input_data_count
prj1,task1,5
prj1,task2,6

CSVには以下の列が存在している必要があります。

  • project_id

  • task_id

  • input_data_count

独自の生産量を指定する#

デフォルトでは、入力データ数とアノテーション数を生産量としています。しかし、この生産量はプロジェクトによっては適切でない場合があります。 たとえば、動画プロジェクトでは動画時間が生産量として適切かもしれません。また、セマンティックセグメンテーションプロジェクトでは塗りつぶしの面積や輪郭線の方が生産量として適切かもしれません。

--custom_production_volume に以下のようなJSON文字列を指定することで、入力データ数とアノテーション数以外の生産量を指定することができます。

{
  "csv_path": "custom_production_volume.csv", // 生産量が記載されたCSVファイルのパス
  "column_list":[  // 生産量の情報
    {
      "value": "video_duration_minute",  // CSVの列名
      "name": "動画長さ"  // CSVの列名を補足する内容。出力されるグラフなどに用いられる。
    }
  ]
}

以下は、 csv_path キーに指定するCSVファイルのサンプルです。

custom_production_volume.csv#
project_id,task_id,video_duration_minute
prj1,task1,10
prj1,task2,20

CSVには以下の列が存在している必要があります。

  • project_id

  • task_id

  • column_list[].value で指定した列名

注釈

動画プロジェクトでは、以下の生産量が追加されます。

  • annotation_duration_minute ： 区間アノテーションの長さ（分）

  • video_duration_minute ： 動画の長さ（分）

生産量の集計対象に含めるラベルや除外するラベルを指定する#

--production_volume_include_label または --production_volume_exclude_label にラベル名を指定することで、以下の生産量の集計対象に含めるラベルや除外するラベルを指定できます。

  • annotation_count

  • annotation_duration_minute （動画プロジェクトの場合のみ）

出力結果#

1個のプロジェクトを指定した場合#

$ annofabcli statistics visualize --project_id prj1 --output_dir out_dir --minimal

out_dir

out_dir
├── histogram
│   ├── ヒストグラム-作業時間.html
│   └── ヒストグラム.html
├── project_info.json
├── line-graph
│   ├── 教師付者用
│   │   └── 累積折れ線-横軸_生産量-教師付者用.html
│   ├── 受入者用
│   │   └── 累積折れ線-横軸_生産量-受入者用.html
│   ├── 折れ線-横軸_教師付開始日-全体.html
│   ├── 折れ線-横軸_日-全体.html
│   ├── 累積折れ線-横軸_日-縦軸_作業時間.html
│   └── 累積折れ線-横軸_日-全体.html
├── scatter
│   ├── 散布図-生産量あたり作業時間と品質の関係-教師付者用.html
│   ├── 散布図-生産量あたり作業時間と累計作業時間の関係.html
│   └── 散布図-教師付者の品質と作業量の関係.html
├── タスクlist.csv
├── メンバごとの生産性と品質.csv
├── ユーザ_日付list-作業時間.csv
├── 教師付開始日毎の生産量と生産性.csv
├── 全体の生産性と品質.csv
└── 日毎の生産量と生産性.csv

複数のプロジェクトを指定した場合#

$ annofabcli statistics visualize --project_id prj1 prj2 --output_dir out_dir --minimal

プロジェクトごとにディレクトリが生成されます。ディレクトリ名は project_id です。

out_dir/
├── project_id1/
│   ├── タスクlist.csv
│   ├── メンバごとの生産性と品質.csv
│   └── ...
├── project_id2/
│   ├── タスクlist.csv
│   ├── メンバごとの生産性と品質.csv
│   └── ...

--merge を指定した場合#

$ annofabcli statistics visualize --project_id prj1 prj2 --output_dir out_dir --minimal \
--merge

prj1とprj2の出力結果をマージしたファイルが、merge ディレクトリに出力されます。

out_dir/
├── project_id1/
│   ├── タスクlist.csv
│   ├── メンバごとの生産性と品質.csv
│   └── ...
├── project_id2/
│   ├── タスクlist.csv
│   ├── メンバごとの生産性と品質.csv
│   └── ...
├── merge
│   ├── タスクlist.csv
│   ├── メンバごとの生産性と品質.csv
│   └── ...

Usage Details#

生産性に関するCSVファイルやグラフを出力します。

usage: annofabcli statistics visualize [-h] [--yes]
                                       [--endpoint_url ENDPOINT_URL]
                                       [--annofab_user_id ANNOFAB_USER_ID]
                                       [--annofab_password ANNOFAB_PASSWORD]
                                       [--annofab_pat ANNOFAB_PAT]
                                       [--logdir LOGDIR] [--disable_log]
                                       [--debug] -p PROJECT_ID
                                       [PROJECT_ID ...]
                                       [--task_completion_criteria {acceptance_completed,acceptance_reached,inspection_reached,annotation_started}]
                                       [--ignored_task_id IGNORED_TASK_ID [IGNORED_TASK_ID ...]]
                                       -o OUTPUT_DIR
                                       [-u USER_ID [USER_ID ...]]
                                       [-tq TASK_QUERY]
                                       [--start_date START_DATE]
                                       [--end_date END_DATE] [--latest]
                                       [--get_task_histories_one_of_each]
                                       [--labor_csv LABOR_CSV]
                                       [--annotation_count_csv ANNOTATION_COUNT_CSV]
                                       [--input_data_count_csv INPUT_DATA_COUNT_CSV]
                                       [--custom_production_volume CUSTOM_PRODUCTION_VOLUME]
                                       [--minimal] [--output_only_text]
                                       [--temp_dir TEMP_DIR] [--not_download]
                                       [--parallelism {2,3,4}]
                                       [--production_volume_include_label PRODUCTION_VOLUME_INCLUDE_LABEL [PRODUCTION_VOLUME_INCLUDE_LABEL ...]
                                       | --production_volume_exclude_label
                                       PRODUCTION_VOLUME_EXCLUDE_LABEL
                                       [PRODUCTION_VOLUME_EXCLUDE_LABEL ...]]

Named Arguments#

-p, --project_id

対象のプロジェクトのproject_idを指定してください。複数指定した場合、プロジェクトごとに統計情報が出力されます。 file:// を先頭に付けると、project_idが記載されたファイルを指定できます。

--task_completion_criteria

Possible choices: acceptance_completed, acceptance_reached, inspection_reached, annotation_started

タスクの完了条件を指定します。 * acceptance_completed: タスクが受入フェーズの完了状態であれば「タスクの完了」とみなす * acceptance_reached: タスクが受入フェーズに到達したら「タスクの完了」とみなす * inspection_reached: タスクが検査フェーズに到達したら「タスクの完了」とみなす * annotation_started: 教師付フェーズが着手されたら「タスクの完了」とみなす

Default: 'acceptance_completed'

--ignored_task_id

集計対象タスクから除外するタスクのtask_idを指定します。 file:// を先頭に付けると、一覧が記載されたファイルを指定できます。

-o, --output_dir

出力先ディレクトリのパスを指定してください。

-u, --user_id

メンバごとの統計グラフに表示するユーザのuser_idを指定してください。指定しない場合は、上位20人が表示されます。 file:// を先頭に付けると、一覧が記載されたファイルを指定できます。

-tq, --task_query

[DEPRECATED] タスクの検索クエリをJSON形式で指定します。指定しない場合は '--task_completion_criteria' から決まった値になります。 file:// を先頭に付けると、JSON形式のファイルを指定できます。クエリのキーは、task_id , phase , phase_stage , status のみです。 '--task_query' は非推奨です。代わりに '--task_completion_criteria' を指定してください。

--start_date

指定した日付（ YYYY-MM-DD ）以降に教師付を開始したタスクから生産性を算出します。

--end_date

指定した日付（ YYYY-MM-DD ）以前に教師付を開始したタスクから生産性を算出します。

--latest

統計情報の元になるファイル（アノテーションzipなど）の最新版を参照します。このオプションを指定すると、各ファイルを更新するのに5分以上待ちます。 ただしWebAPIの都合上、'タスク履歴全件ファイル'は最新版を参照できません。タスク履歴の最新版を参照する場合は --get_task_histories_one_of_each を指定してください。

--get_task_histories_one_of_each

タスク履歴を1個ずつ取得して、タスク履歴の最新版を参照します。タスクの数だけWebAPIを実行するので、処理時間が長くなります。

--labor_csv

実績作業時間情報が格納されたCSVを指定してください。指定しない場合は、実績作業時間は0とみなします。列名は以下の通りです。

  • date

  • account_id

  • actual_worktime_hour

  • project_id

--annotation_count_csv

指定されたCSVに記載されているアノテーション数を参照して、生産量や生産性を算出します。未指定の場合はアノテーションZIPからアノテーション数をカウントします。CSVには以下の列が必要です。

  • project_id

  • task_id

  • annotation_count

--input_data_count_csv

指定されたCSVに記載されている入力データ数を参照して、生産量や生産性を算出します。未指定の場合はタスクに含まれている入力データ数から算出します。タスクに、作業しない参照用のフレームが含まれている場合に有用なオプションです。CSVには以下の列が必要です。

  • project_id

  • task_id

  • input_data_count

--custom_production_volume

プロジェクト独自の生産量をJSON形式で指定します。(例) {"csv_path": "custom_production_volume.csv", "column_list": [{"value": "video_duration_minute", "name": "動画長さ"}]} 詳細は https://annofab-cli.readthedocs.io/ja/latest/command_reference/statistics/visualize.html#custom-project-volume を参照してください。

--minimal

必要最小限のファイルを出力します。

--output_only_text

テキストファイルのみ出力します。グラフが掲載されているHTMLファイルは出力しません。

--temp_dir

指定したディレクトリに、アノテーションZIPなど可視化に必要なファイルを出力します。

--not_download

指定した場合、アノテーションZIPなどのファイルをダウンロードせずに、--temp_dir`で指定したディレクトリ内のファイルを読み込みます。--temp_dir`は必須です。

--parallelism

Possible choices: 2, 3, 4

並列度。 --project_id に複数のproject_idを指定したときのみ有効なオプションです。指定しない場合は、逐次的に処理します。

--production_volume_include_label

生産量（'annotation_count'など）の集計対象に含めるラベル名（英語）を指定します。複数指定可能です。

--production_volume_exclude_label

生産量（'annotation_count'など）の集計対象から除外するラベル名（英語）を指定します。複数指定可能です。

global optional arguments#

--yes

処理中に現れる問い合わせに対して、常に yes と回答します。

--endpoint_url

Annofab WebAPIのエンドポイントを指定します。

Default: 'https://annofab.com'

--annofab_user_id

Annofabにログインする際のユーザーID

--annofab_password

Annofabにログインする際のパスワード

--annofab_pat

Annofabにログインする際のパーソナルアクセストークン

--logdir

ログファイルを保存するディレクトリを指定します。

Default: .log

--disable_log

ログを無効にします。

--debug

HTTPリクエストの内容やレスポンスのステータスコードなど、デバッグ用のログが出力されます。

アノテーションユーザまたはオーナロールを持つユーザで実行してください。