annotation_zip sum_annotation_duration_by_attribute_value#

Description#

属性値ごとに区間アノテーションの長さを合計し、動画長とともに秒単位で出力します。

デフォルトは選択肢系の属性(ドロップダウン、ラジオボタン、チェックボックス)を集計します。 --additional_attribute_name は指定属性を追加し、 --attribute_name は指定属性だけを対象にします。両者は排他です。 --label_name と併用すると、ラベルと属性の両方に一致する属性値を対象にします。 詳細は annotation_zip count_annotation_by_attribute_value を参照してください。

属性値CSVはラベル名・属性名・属性値の3行ヘッダーです。 同じ区間が複数の属性に計上されるため、属性値集計では総合計の annotation_duration_second を出力しません。

Examples#

$ annofabcli annotation_zip sum_annotation_duration_by_attribute_value --project_id prj1 --output out.csv
out.csv#

project_id

task_id

task_phase

task_phase_stage

task_status

input_data_id

input_data_name

updated_datetime

video_duration_second

speech

speech

speaker

speaker

male

female

prj1

task1

annotation

1

complete

video1

video1.mp4

2026-10-06T12:00:00+09:00

60.0

12.0

8.0

$ annofabcli annotation_zip sum_annotation_duration_by_attribute_value --project_id prj1 --format pretty_json --output out.json
[
  {
    "project_id": "prj1",
    "task_id": "task1",
    "task_phase": "annotation",
    "task_phase_stage": 1,
    "task_status": "complete",
    "input_data_id": "video1",
    "input_data_name": "video1.mp4",
    "updated_datetime": "2026-10-06T12:00:00+09:00",
    "video_duration_second": 60.0,
    "annotation_duration_second_by_attribute_value": {
      "speech": {"speaker": {"male": 12.0, "female": 8.0}}
    }
  }
]
$ annofabcli annotation_zip sum_annotation_duration_by_attribute_value --project_id prj1 \
  --annotation annotation.zip --output by_task.csv
$ annofabcli annotation_zip sum_annotation_duration_by_attribute_value --project_id prj1 \
  --group_by task_phase task_status --output summary.csv

集計の仕様#

対象は動画プロジェクトの区間アノテーション(Range)です。動画以外のプロジェクトはエラーになります。 区間長は (end - begin) / 1000 の合計です。重なった区間もそれぞれ加算するため、合計が動画長を超える場合があります。

video_duration_second は集計対象の動画長の合計です。区間や対象ラベルがない入力データも動画長に含めます。 同じ動画が複数のタスクに含まれる場合はタスクごとに数えます。 対象はアノテーションZIPに含まれる入力データに限り、入力データ全件ファイルだけにある動画は含めません。 動画長が取得できない入力データを1件でも含む集計結果では、JSONは null、CSVは空欄とし、警告を出力します。

アノテーション仕様に定義された対象ラベル・選択肢は、未出現でも0秒を出力します。 CSVの出力件数が0件の場合もヘッダーを出力します。単位は秒に固定しています。

--project_id は必須です。 --annotation を指定しても、動画長・タスク情報・アノテーション仕様はAnnofabから取得します。

デフォルトはタスク単位です。動画タスクには入力データが1個しか含まれないため、 タスク単位の出力に input_data_id、 input_data_name、 updated_datetime を含めます。 常に1となる input_data_count と frame_no はタスク単位では出力しません。

--group_by には task_id、 project_id、 task_phase、 task_phase_stage、 task_status、 task_metadata.<key> を指定できます。 input_data_id は指定できません。 task_id と project_id は単独で指定し、それ以外のキーは複数指定できます。 サマリーには集計キー、 task_count、 input_data_count を出力します。 メタデータのキーが存在しないタスクは、値が空のグループに集計されます。

タスクメタデータを出力する#

--with_task_metadata を指定すると、タスクのメタデータをすべて出力します。

CSVでは task_id の直後に、対象タスクのいずれかに存在するキーを task_metadata.<key> 形式の列として出力します。キーがタスクに存在しない場合、そのセルは空になります。

JSONでは、タスクのメタデータ全体を task_metadata オブジェクトに出力します。

旧コマンドからの移行#

statistics list_annotation_duration --type label は sum_annotation_duration_by_label、 --type attribute は sum_annotation_duration_by_attribute_value に対応します。 旧コマンドと同じ集計単位は、デフォルトのタスク単位です。集計単位の指定は不要です。 新コマンドは属性値JSONキーを annotation_duration_second_by_attribute_value に統一しています。

Usage Details#

属性値ごとに区間アノテーションの長さ(秒)を合計して出力します。

usage: annofabcli annotation_zip sum_annotation_duration_by_attribute_value
       [-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
       [--annotation ANNOTATION] [--group_by GROUP_BY [GROUP_BY ...]]
       [-f {csv,json,pretty_json}] [-o OUTPUT] [-t TASK_ID [TASK_ID ...]]
       [--task_query TASK_QUERY] [--latest] [--temp_dir TEMP_DIR]
       [--with_task_metadata] [--use_japanese_name]
       [--additional_attribute_name ADDITIONAL_ATTRIBUTE_NAME [ADDITIONAL_ATTRIBUTE_NAME ...] |
       --attribute_name ATTRIBUTE_NAME [ATTRIBUTE_NAME ...]]
       [--label_name LABEL_NAME [LABEL_NAME ...]]

Named Arguments#

-p, --project_id

対象のプロジェクトのproject_idを指定します。

--annotation

アノテーションZIPまたは展開済みディレクトリ。省略するとダウンロードします。

--group_by

集計単位。task_id, project_id, task_phase, task_phase_stage, task_status, task_metadata.<key>を指定できます。

Default: ['task_id']

-f, --format

Possible choices: csv, json, pretty_json

出力フォーマットを指定します。

Default: 'csv'

-o, --output

出力先のファイルパスを指定します。未指定の場合は、標準出力に出力されます。

-t, --task_id

対象のタスクのtask_idを指定します。 file:// を先頭に付けると、task_idの一覧が記載されたファイルを指定できます。ファイルを読み込む場合は、ファイル指定を1個だけ渡してください。直接指定するIDや別のファイル指定とは併用できません。

--task_query, -tq

対象タスクの条件をJSONで指定します。キーはtask_id, status, phase, phase_stageです。file://でファイルを指定できます。

--latest

最新のアノテーションZIP、入力データ、タスク情報を取得します。数分待つ場合があります。

Default: False

--temp_dir

ダウンロード先ディレクトリ。

--with_task_metadata

タスク単位の出力にタスクメタデータを追加します。

Default: False

--use_japanese_name

ラベル名、属性名、選択肢名をアノテーション仕様に登録されている日本語名で出力します。日本語名がない場合は英語名を出力します。

Default: False

--additional_attribute_name

デフォルトで集計される選択肢系の属性(ドロップダウン、ラジオボタン、チェックボックス)に加えて、集計したい属性の英語名を指定します。ラベル名に関係なく、デフォルト属性と指定した属性名を持つ属性が集計対象になります。 file:// を先頭に付けると、属性名が記載されたファイルを指定できます。 ファイルを読み込む場合は、ファイル指定を1個だけ渡してください。直接指定する値や別のファイル指定とは併用できません。

--label_name

集計対象とするラベルの英語名を指定します。指定したラベルに属する属性値のみが集計対象になります。 file:// を先頭に付けると、ラベル名が記載されたファイルを指定できます。 ファイルを読み込む場合は、ファイル指定を1個だけ渡してください。直接指定する値や別のファイル指定とは併用できません。

--attribute_name

集計対象とする属性の英語名を指定します。指定した属性名のみが集計対象になります(デフォルトの選択肢系属性は含まれません)。ラベル名に関係なく、指定した属性名を持つ属性のみが集計対象になります。 file:// を先頭に付けると、属性名が記載されたファイルを指定できます。 ファイルを読み込む場合は、ファイル指定を1個だけ渡してください。直接指定する値や別のファイル指定とは併用できません。

common options (after the subcommand)#

--yes

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

Default: False

--endpoint_url

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

--annofab_user_id

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

--annofab_password

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

--annofab_pat

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

--logdir

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

Default: .log

--disable_log

ログを無効にします。

Default: False

--debug

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

Default: False

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