本コンペティションで配布されるデータと応募用ファイルの作成方法について説明する.
配布されるデータは以下の通り.
本ファイル(readme.md)で, 配布用データの説明と応募用ファイルの作成方法を説明したドキュメント. マークダウン形式で, プレビューモードで見ることを推奨する.
学習用データは"train.zip"で, 解凍すると以下のようなディレクトリ構造のデータが作成される.
train
├─ rainfall
│ ├── data.csv
│ └── stations.csv
├─ tidelevel
│ ├── data.csv
│ └── stations.csv
├─ waterlevel
│ ├── data.csv
│ └── stations.csv
└─ dam.csv内容は以下の通り.
train/rainfall以下に格納されている. 内容は以下の通り.
- 実績データ(data.csv, encodingはutf-8.)
- 観測局データ(stations.csv, encodingはutf-8.)
実績データは, "data.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | date | int | 日にちを表す. ある時点を0として, 1日経過するごとに+1される. |
| 2 | station | str | 観測局の名称. |
| 3 | city | str | 観測局の市町名. |
| 4 | 00:00:00 | str | その日の00:00:00時の雨量. 単位は[mm]. |
| ... | ... | str | ... |
| 27 | 23:00:00 | str | その日の23:00:00時の雨量. 単位は[mm]. |
- 観測局の名称はある日にちを境に変わる場合がある. ただし, 予測時には変わることはない.
- 値には"*", "-", "M"等の欠測, あるいは閉局によりデータ取得ができなかった時間がある.
観測局データは, "stations.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | 観測所名称 | str | 観測局の名称. |
| 2 | フリガナ | str | 観測局の名称(フリガナ). |
| 3 | 市町 | str | 観測局が存在する市町名. |
| 4 | 水系名 | str | 河川名(大分類). 1本の川(本川)に集まる全ての川をまとめて"水系"と呼称する. |
| 5 | 河川名 | str | 河川名(小分類). |
| 6 | データ所管 | str | 本データを管轄している団体名. |
| 7 | 住所 | str | 当該観測局の住所. |
| 8 | 緯度 | float | 当該観測局の緯度(10進法表記). |
| 9 | 経度 | float | 当該観測局の経度(10進法表記). |
| 10 | 事務所 | str | 管理している事務所名. |
| 11 | 入力時使用 | int | 予測する際に入力する情報として使えるか否か. 使える場合は1, そうでない場合は0. |
- 実績データの中には名称が変わったり, 使用されなくなったことで観測局データには含まれない観測局が存在する.
- "入力時使用"は応募用ファイルの投稿時にプログラムが実行される際に入力として与えられるか否かを表し, 1の場合は与えられ, 0の場合は与えられない.
なお, 雨量データは予測対象となる水位を予測するための情報として利用される想定である.
train/tidelevel以下に格納されている. 内容は以下の通り.
- 実績データ(data.csv, encodingはutf-8.)
- 観測局データ(stations.csv, encodingはutf-8.)
実績データは, "data.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | date | int | 日にちを表す. ある時点を0として, 1日経過するごとに+1される. |
| 2 | station | str | 観測局の名称. |
| 3 | city | str | 観測局の市町名. |
| 4 | 00:00:00 | str | その日の00:00:00時の潮位. 単位は[m]. |
| ... | ... | str | ... |
| 27 | 23:00:00 | str | その日の23:00:00時の潮位. 単位は[m]. |
- 観測局の名称はある日にちを境に変わる場合がある. ただし, 予測時には変わることはない.
- 値には"*", "-", "M"等の欠測, あるいは閉局によりデータ取得ができなかった時間がある.
観測局データは, "stations.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | 観測所名 | str | 観測局の名称. |
| 2 | ふりがな | str | 観測局の名称(ふりがな). |
| 3 | 水系名 | str | 河川名(大分類). 1本の川(本川)に集まる全ての川をまとめて"水系"と呼称する. |
| 4 | 河川名 | str | 河川名(小分類). |
| 5 | 事務所 | str | 管理している事務所名. |
| 6 | 所管 | str | 本データを管轄している団体名. |
| 7 | 住所 | str | 当該観測局の住所. |
| 8 | 緯度 | float | 当該観測局の緯度(10進法表記). |
| 9 | 経度 | float | 当該観測局の経度(10進法表記). |
| 10 | 入力時使用 | int | 予測する際に入力する情報として使えるか否か. 使える場合は1, そうでない場合は0. |
- 実績データの中には名称が変わったり, 使用されなくなったことで観測局データには含まれない観測局が存在する.
- "入力時使用"は応募用ファイルの投稿時にプログラムが実行される際に入力として与えられるか否かを表し, 1の場合は与えられ, 0の場合は与えられない.
なお, 潮位データは予測対象となる水位を予測するための情報として利用される想定である.
train/waterlevel以下に格納されている. 内容は以下の通り.
- 実績データ(data.csv, encodingはutf-8.)
- 観測局データ(stations.csv, encodingはutf-8.)
実績データは, "data.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | date | int | 日にちを表す. ある時点を0として, 1日経過するごとに+1される. |
| 2 | station | str | 観測局の名称. |
| 3 | river | str | 当該観測局が担当する河川名. |
| 4 | 00:00:00 | str | その日の00:00:00時の水位. 単位は[m]. |
| ... | ... | str | ... |
| 27 | 23:00:00 | str | その日の23:00:00時の水位. 単位は[m]. |
- 観測局の名称はある日にちを境に変わる場合がある. ただし, 予測時には変わることはない.
- 値には"*", "-", "M"等の欠測, あるいは閉局によりデータ取得ができなかった時間がある.
観測局データは, "stations.csv"という名前のヘッダーありcsvファイル. カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | 観測所名称 | str | 観測局の名称. |
| 2 | フリガナ | str | 観測局の名称(フリガナ). |
| 3 | 市町 | str | 観測局が存在する市町名. |
| 4 | 水系名 | str | 河川名(大分類). 1本の川(本川)に集まる全ての川をまとめて"水系"と呼称する. |
| 5 | 河川名 | str | 河川名(小分類). |
| 6 | データ所管 | str | 本データを管轄している団体名. |
| 7 | 住所 | str | 当該観測局の住所. |
| 8 | 緯度 | float | 当該観測局の緯度(10進法表記). |
| 9 | 経度 | float | 当該観測局の経度(10進法表記). |
| 10 | 事務所 | str | 管理している事務所名. |
| 11 | 入力時使用 | int | 予測する際に入力する情報として使えるか否か. 使える場合は1, そうでない場合は0. |
| 12 | 評価対象 | int | 予測する際に評価対象となるか否か. なる場合は1, そうでない場合は0. |
- 実績データの中には名称が変わったり, 使用されなくなったことで観測局データには含まれない観測局が存在する.
- "入力時使用"は応募用ファイルの投稿時にプログラムが実行される際に入力として与えられるか否かを表し, 1の場合は与えられ, 0の場合は与えられない.
- "評価対象"は応募用ファイルの投稿時にプログラムが実行される際に評価対象となるか否かを表し, 1の場合はなり, 0の場合はならない.
なお, 水位データは予測対象であると同時に予測する際に使用する想定の情報である. すなわち, 次の日の水位を予測するとき, 当日の水位の情報を利用する想定である.
河川に通じる場所にあるダムに関する諸情報. "dam.csv"という名前のヘッダーありcsvファイル. encodingはutf-8.カラム一覧を以下に示す.
| No | 名前 | 型 | 説明 |
|---|---|---|---|
| 1 | ダムｺｰﾄﾞ | int | ダムのコード番号. |
| 2 | 建設(支)局ｺｰﾄﾞ | int | 建設支局のコード番号. |
| 3 | 分類 | str | 施設の分類名称. |
| 4 | 水系名 | str | 河川名(大分類). 1本の川(本川)に集まる全ての川をまとめて"水系"と呼称する. |
| 5 | 河川名 | str | 河川名(小分類). |
| 6 | 施設区分 | str | 施設の区分. |
| 7 | ダム名 | str | ダムの名称. |
| 8 | 管理者 | str | 管理担当. |
| 9 | 都道府県 | str | 当該ダムの住所(都道府県). |
| 10 | 位置 | str | 当該ダムの住所(市町名). |
| 11 | 緯度 | float | 当該ダムの緯度(10進法表記). |
| 12 | 経度 | float | 当該ダムの経度(10進法表記). |
| 13 | 完成年月 | str | ダムの完成した年月(S,H,R表記). |
| 14 | 集水面積_km2 | float | ダムの集水面積[km^2]. |
| 15 | 堤体積_千m3 | int | ダムの堤の体積[千m^3]. |
| 16 | 総貯水容量_千m3 | int | ダムの総貯水容量[千m^3]. |
| 17 | 有効貯水容量_千m3 | int | ダムの有効貯水容量[千m^3]. |
| 18 | 型式 | str | ダムの型式名称. |
| 19 | 堤高_m | float | ダムの堤高[m]. |
| 20 | 堤頂長_m | float | ダムの堤頂長[m]. |
| 21 | 診断結果 | str | ダムの状態の診断結果. |
予測を行うプログラムの動作を確認するためのプログラム. "run_test.zip"が本体で, 解凍すると, 以下のようなディレクトリ構造のデータが作成される.
run_test
└─ run.py使用方法等については応募用ファイルの作成方法を参照すること.
応募用のサンプルファイル. 実体は"sample_submit.zip"で, 解凍すると以下のようなディレクトリ構造のデータが作成される.
sample_submit
├── model
│ └── ...
├── src
│ └── predictor.py
└── requirements.txtsample_submit/modelは空のディレクトリとなる. sample_submit/requirements.txtには何も書いていない. 詳細や作成方法については応募用ファイルの作成方法を参照すること.
学習済みモデルを含めた, 予測を実行するためのソースコード一式をzipファイルでまとめたものとする.
以下のようなディレクトリ構造となっていることを想定している.
.
├── model 必須: 学習済モデルを置くディレクトリ
│ └── ...
├── src 必須: Pythonのプログラムを置くディレクトリ
│ ├── predictor.py 必須: 最初のプログラムが呼び出すファイル
│ └── ... その他のファイル (ディレクトリ作成可能)
└── requirements.txt 任意: 追加で必要なライブラリ一覧- 学習済みモデルの格納場所は"model"ディレクトリを想定している.
- 学習済みモデルを使用しない場合でも空のディレクトリを作成する必要がある.
- 名前は必ず"model"とすること.
- Pythonのプログラムの格納場所は"src"ディレクトリを想定している.
- 学習済みモデル等を読み込んで推論するためのメインのソースコードは"predictor.py"を想定している.
- ファイル名は必ず"predictor.py"とすること.
- その他予測を実行するために必要なファイルがあれば作成可能である.
- ディレクトリ名は必ず"src"とすること.
- 学習済みモデル等を読み込んで推論するためのメインのソースコードは"predictor.py"を想定している.
- 実行するために追加で必要なライブラリがあれば, その一覧を"requirements.txt"に記載することで, 評価システム上でも実行可能となる.
- インストール可能で実行可能かどうか予めローカル環境で試しておくこと.
- 評価システムの実行環境については, こちらを参照すること.
以下のクラスとメソッドを実装すること.
予測実行のためのクラス. 以下のメソッドを実装すること.
モデルを取得するメソッド. 以下の条件を満たす必要がある.
- クラスメソッドであること.
- 引数model_path(str型)を指定すること.
- 学習済みモデルが格納されているディレクトリのパスが渡される.
- 学習済みモデルの読み込みに成功した場合はTrueを返す.
- モデル自体は任意の名前(例えば"model")で保存しておく.
予測を実行するメソッド. 以下の条件を満たす必要がある.
-
クラスメソッドであること.
-
引数input(dict型)を指定すること.
- 当日の日にち, 予測対象の観測局, 水位, 雨量, 潮位の情報がdict型で渡される.
get_modelメソッドで読み込んだ学習済みモデルを用いて翌日の水位の予測を行う想定である.- フォーマットは以下.
{ "date": date, "stations": { station_1, station_2, ... }, "waterlevel": [ { "hour": hour, "station": station, "river": river, "value": value }, { "hour": hour, "station": station, "river": river, "value": value }, ... ], "rainfall": [ { "hour": hour, "station": station, "city": city, "value": value }, { "hour": hour, "station": station, "city": city, "value": value }, ... ], "tidelevel": [ { "hour": hour, "station": station, "city": city, "value": value }, { "hour": hour, "station": station, "city": city, "value": value }, ... ] }- "date"は当日の日にち(int型). 学習データと同様に, ある時点を0として, 1日経過ごとに+1される.
- "stations"は次の日の水位の予測(評価)対象となる観測局の名称一覧(set型で各要素はstr型).
- "waterlevel"は当日の水位の情報(list型). 以下の情報をkeyとするdict型のデータを要素とする.
- "hour"は時間(int型). 0~23までの値をとる.
- "station"は観測局の名称(str型).
- "river"は河川名(str型).
- "value"は水位の値[m] (str型). 学習データと同様に"*", "-", "M"などの欠損値等が存在する.
- "rainfall"は当日の雨量の情報(list型). 以下の情報をkeyとするdict型のデータを要素とする.
- "hour"は時間(int型). 0~23までの値をとる.
- "station"は観測局の名称(str型).
- "city"は市町名(str型).
- "value"は雨量の値[mm] (str型). 学習データと同様に"*", "-", "M"などの欠損値等が存在する.
- "tidelevel"は当日の潮位の情報(list型). 以下の情報をkeyとするdict型のデータを要素とする.
- "hour"は時間(int型). 0~23までの値をとる.
- "station"は観測局の名称(str型).
- "city"は市町名(str型).
- "value"は潮位の値[m] (str型). 学習データと同様に"*", "-", "M"などの欠損値等が存在する.
以下のフォーマットで予測結果をlist型で返す.
[
{
"hour": hour,
"station": station,
"value": value
},
{
"hour": hour,
"station": station,
"value": value
},
...
]- 各要素は以下を満たすdict型.
- "hour"には時間を記載する. 一日分に相当する, 0~23のint型.
- "station"には観測局の名称を記載する. str型. 入力として渡される"stations"に含まれるすべての観測局を含めること.
- "value"には対応する観測局, 時間における水位をfloat型, またはint型で記載する.
以下は実装例. 当日の水位をそのまま翌日の水位の予測とする単純な処理である. pandasがインストールされていることが前提.
import pandas as pd
class ScoringService(object):
@classmethod
def get_model(cls, model_path):
"""Get model method
Args:
model_path (str): Path to the trained model directory.
Returns:
bool: The return value. True for success.
"""
cls.model = None
return True
@classmethod
def predict(cls, input):
"""Predict method
Args:
input: Data of the sample you want to make inference from (dict)
Returns:
list: Inference for the given input.
"""
stations = input['stations'] # 評価対象の観測局
waterlevel = input['waterlevel'] # 当日の水位情報
merged = pd.merge(pd.DataFrame(stations, columns=['station']), pd.DataFrame(waterlevel)) # 評価対象のみに絞る
merged['value'] = merged['value'].replace({'M':0.0, '*':0.0, '-':0.0, '--': 0.0, '**': 0.0}) # 欠損値を0.0に入れ替える
merged['value'] = merged['value'].fillna(0.0) # その他の欠損値を0.0に入れ替える
merged['value'] = merged['value'].astype(float) # float型に変換する
prediction = merged[['hour', 'station', 'value']].to_dict('records') # DataFrameをlist型に変換する
return prediction応募用サンプルファイル"sample_submit.zip"も参照すること.
予測を行うプログラムが実装できたら, 正常に動作するか確認する.
評価システムと同じ環境を用意する.
配布データを用いてモデル学習などを行い, 動作確認用のプログラムを用いて検証用のデータを作成し, 予測を実行する. 最後に精度(RMSE)を確認する.
$ cd /path/run_test
$ python run.py --exec-path /path/to/submit/src --data-dir /path/to/train --start-date start_date --end-date end_date
...- 引数"--exec-path"には実装した予測プログラム("predictor.py")が存在するパス名を指定する.
- 引数"--data-dir"には配布された学習用データ"train"のパス名を指定する.
- 引数"--start-date"には検証用データを作成するときの最初の日にちを0以上の整数値を指定する.
- 引数"--end-date"には検証用データを作成するときの最後の日にちを0以上の整数値を指定する.
- "--start-date"で指定した値よりも大きい値を設定すること.
"run.py"の実行に成功すると, 検証用のデータを作成し, 実装したプログラムによる予測が行われ, 最後に精度が出力される. プログラム上のエラーがない場合でも, モデルの読み込みに失敗したときや, 予測結果のフォーマットが正しくないときは途中でエラーのメッセージが返され, 止まる. 具体的には, get_modelメソッドを呼んだときにTrueを返さない, 予測結果がlist型ではない, keyが'hour', 'station', 'value'を含んでいない, 'value'のデータ型がfloatまたはintになっていない場合.
投稿する前にエラーが出ずに実行が成功することを確認すること.
上記のディレクトリ構造となっていることを確認して, zipファイルとして圧縮する.