期間・領域・解析条件¶

このページは、期間と領域の指定方法、それらを束ねるView、作業場所のProject、名前付きの条件Caseの仕様をまとめます。流れを先に掴みたい場合は解析条件を残すを読んでください。

期間は半開区間で指定する¶

SOPRANの期間（TimeRange）は開始を含み、終了を含みません。日ごとのシャードをつなげても、境界のサンプルを二重に数えないためです。

spn.period("2008-02-01T03:00", "2008-02-01T04:00")
spn.day("2008-02-01")      # 2008-02-01 00:00 から 2008-02-02 00:00 まで
spn.month("2008-02")
spn.year("2008")

ISO 8601の文字列とdatetimeを受け付けます。タイムゾーンのない時刻はUTCとして扱います。 TimeRangeはstart、stop（UTCのdatetime）と、文字列のstart_iso、stop_isoを持ちます。

領域は経度の定義域と一緒に持つ¶

region = spn.Region(lon=(350, 10), lat=(-5, 5), body="moon")

region.crosses_lon_boundary        # True（0/360度をまたぐ）
region.contains(355, 0)            # True
region.to_lon_domain("-180_180")   # 経度を -180〜180 で表した Region

経度の既定は東経正・0〜360度、緯度は惑星中心緯度です。lon_domain、lon_direction、lat_typeで変えられます。月面マップでの座標の扱いは月面マップにあります。

View¶

Viewは期間・領域と処理条件を束ねた、変更不可のオブジェクトです。

view = spn.view(
    time=spn.day("2008-02-01"),
    region=spn.Region(lon=(120, 160), lat=(-45, -10), body="moon"),
    frame="SSE",
    download="never",
)

種類	引数	効果
選択	`time`（または`start`と`stop`）	エンドポイントの既定の期間になる
選択	`region`	月面マップの既定の領域になる
選択	`mission`、`instrument`、`product`、`quality`	解析条件として記録する
処理	`download`	ミッションのダウンロード方針になる
処理	`spice_kernels`、`time_scale`、`backend`	`view.frame_context()`が作る`FrameContext`に入る
処理	`frame`、`cache`	解析条件として記録する

view.kaguya、view.artemis、view.omni、view.moonは、それぞれspn.Kaguyaなどの実体です。メソッドで期間を省くとview.timeを使います。登録済みのデータ源はview.source("kaguya")でも取り出せます。

条件を変えるときは新しいViewを作ります。

view.with_time("2008-02-01T03:00", "2008-02-01T04:00")
view.with_region(None)
view.with_context(frame="GSE", download="missing")

spn.view(...)は、カレントディレクトリから親へたどって最初に見つかったsopran.tomlを Projectの設定として使います。spn.kaguyaなどの短い入口も同じです。

Project¶

Projectは解析テーマの作業ディレクトリです。

project = spn.Project("projects/lunar_wake")
project = spn.Project("projects/lunar_wake", store=spn.Store("/path/to/sopran_data"))

項目	内容
`project.root`	作業ディレクトリ。`sopran.toml`を置く
`project.store`	使うStore。省略時は設定の優先順位で決まる
`project.artifact_root`	`project.save()`の保存先
`project.view(...)`	このProjectの既定値を使う`View`
`project.kaguya`など	期間を持たないミッションの実体

Case¶

Caseはsopran.tomlに名前付きで保存した解析条件です。

[defaults]
frame = "SSE"

[defaults.region]           # 領域を持たないCaseの既定
body = "moon"
lon = [120, 160]
lat = [-45, -10]

[cases.wake_20080201]
start = "2008-02-01T00:00:00"
stop = "2008-02-02T00:00:00"

[cases.wake_20080201.context]   # frame, cache, download, quality, time_scale
download = "never"

[cases.wake_20080201.region]
body = "moon"
lon = [130, 150]
lat = [-30, -20]

case = project.case("wake_20080201")
case.kaguya.esa1.counts.load()
case.with_time("2008-02-01T03:00", "2008-02-01T04:00")   # View を返す
case.view                                                # Case と同じ条件の View

各キーは、Caseの値、セッション設定、Projectの[defaults]、ユーザー設定の順に解決します。ただしdownloadだけは、セッション設定と環境変数（SOPRAN_OFFLINEなど）がCaseの値より優先します（設定）。 project.case(name, start=..., stop=...)は、sopran.tomlに書かずにその場でCaseを作ります。

project.save_case(name, view)はViewの期間・領域・処理条件をsopran.tomlへ追記し、同じ内容をcases/<name>.jsonにも書きます。同名のCaseがあると止まります。上書きは未実装なので、変えたいときはsopran.tomlを編集してください。

来歴を記録する¶

context=は、図・成果物・データセットに解析条件を書き込む共通の引数です。

呼び出し	記録先
`plot(..., context=case)`、`quicklook(..., context=case)`	図のJSON
`project.save(array, "interim/name", context=case)`	NetCDFと同名のJSON
`write_parquet(..., context=case)`、`write_dataset(..., context=case)`	Storeのマニフェスト

contextにはCase、View、metadata()かto_metadata()を持つオブジェクト、JSONにできる辞書を渡せます。 CaseならCase名・Projectの場所・Storeの場所・期間・領域・既定値が入ります。

project.save(value, name)は、to_xarray()を持つ値をNetCDFとしてartifact_rootの下に保存し、期間・出典・相対パスをJSONに記録します。Projectの中に置くのは一時的な成果物です。複数の解析で再利用するデータはStoreに保存してください。