xolars

xolars の公開 API

xolars は、1 つの小さな不変コンテナーです。xarray.Dataset と、次元ごとに 1 つの Polars フレームを保持し、選択操作やディスクへの書き込み・読み込みを通じて、Dataset の座標順に合わせて整列させます。

公開範囲

import xolars で公開される名前は 1 つだけです。

• xolars.Xolars — コンテナー

from xolars import Xolars を使ってください。xolars._core 以下は内部実装です。

Xolars は attrs による不変クラスで、F = pl.DataFrame | pl.LazyFrame とする Generic[F] です。つまり、次元ごとのすべてのフレームは同じ型です。不変のため、isel／sel／collect は新しいインスタンスを返し、元のインスタンスを変更しません。

構築

from xolars import Xolars

xo = Xolars(ds=dataset, df={"sample": sample_frame, "gene": gene_frame})
# positional also works: Xolars(dataset, {"sample": sample_frame})

• ds: xr.Dataset
• df: Mapping[Hashable, pl.DataFrame | pl.LazyFrame] — 次元名をキーとする辞書です。メタデータが必要な次元ごとにフレームを 1 つ指定します（すべての次元を指定する必要はありません）。単一のフレームでもリストでもありません。

構築時に適用される不変条件（いずれかに違反すると ValueError が発生します）

各 dim -> frame について：

1. dim は ds の実際の次元である必要があります。
2. frame には名前が正確に dim である列（結合キー）が必要です。
3. その列の値は、ds[dim] の座標と集合として一致する必要があります。長さと要素の両方が一致しなければなりません。ID が不足または余分にある場合はエラーになり、一部だけが重複する場合もエラーになります。

行の順序は問いません。次元列を使った右結合により、フレームは Dataset の座標順に自動で並べ替えられます。事前に並べ替える必要はありません。

選択 — isel / sel

xarray.Dataset.isel／.sel と同じシグネチャです（インデクサーの辞書またはキーワード引数、drop、missing_dims。sel では method／tolerance も指定できます）。

xo.isel(sample=slice(0, 10))      # positional
xo.sel(sample=["S1", "S2"])       # label-based

どちらのメソッドも Dataset をサブセット化し、インデックス指定された次元に対応するすべてのフレームもフィルタリングして、整列を維持します。スカラーのインデクサーによって次元が削除される場合、その次元のフレームも削除されます。インデックス指定されていない次元のフレームは変更されません。

メタデータ（例：age > 50）でフィルタリングする場合は、フレームを自分でフィルタリングして対象の ID を取得し、それを sel に渡してください。Xolars にはメタデータ述語で選択するメソッドはありません。

frame = xo.df["sample"]                       # may be DataFrame or LazyFrame
ids = frame.filter(pl.col("age") > 50).select("sample")
ids = ids.collect() if isinstance(ids, pl.LazyFrame) else ids
xo2 = xo.sel(sample=ids["sample"].to_list())

データの追加 — assign / merge

どちらも関数型で、新しい Xolars を返します。1 次元データは対応する次元の Polars フレームに格納され、N 次元データは Dataset に格納されます。

# assign one or more named variables (xarray.Dataset.assign idiom)
xo2 = xo.assign(gc=("gene_id", gc_array))                 # 1-D -> gene_id frame
xo2 = xo.assign(counts=(("gene_id", "sample_id"), mat))   # 2-D -> Dataset
xo2 = xo.assign(score=some_named_dataarray)               # aligned by label
# passing an xarray.Dataset value is an error -> use merge()

# merge whole objects; 1-D vars in xarray objects move to Polars
xo2 = xo.merge(other_dataset, gene_frame)                 # bare frame: dim inferred
xo2 = xo.merge(frames={"gene_id": [f1, f2]})              # explicit, aligned to gene_id

名前が競合する場合は、警告なしで上書きされます。Polars／xarray の入力は、固定された座標に対して左揃えされます（サブセットの場合は null が追加され、スーパーセットの場合は余分な要素が削除されます）。既存の ds の座標集合が拡張されることはありません（ただし、2 次元以上の変数によって新しい次元が追加される場合があります）。

ディスクへの書き込み・読み込み — write / open

xo.write(path, mode="w")          # mode is REQUIRED (a zarr write mode)
reopened = Xolars.open(path)      # classmethod -> Xolars[pl.LazyFrame]

• write(path, mode) は path/ を作成し、その中に dataset.zarr/ と、各フレームの {dim}.parquet を 1 つずつ保存します。mode にデフォルト値はありません。"w"（上書き）、"w-"、"a" などを指定してください（xarray の ZarrWriteModes）。
• open(path) は dataset.zarr を読み込み、その隣にあるすべての *.parquet を scan_parquet で読み込みます。フレームは遅延評価され、pl.LazyFrame として返されます。
• どちらの path 引数も型は pathlib.Path です。文字列ではなく Path を渡してください。

即時評価と遅延評価 — collect

open は LazyFrame を返します。すべてのフレームを pl.DataFrame に実体化するには、次のようにします。

eager = reopened.collect()        # -> Xolars[pl.DataFrame]

構築、検証、選択はいずれの型でも動作するため、即時評価のフレームが必要な場合にのみ collect() を呼び出してください。

よくある間違い

間違い	修正方法
Xolars(dataset, metadata=df)	Xolars(ds=dataset, df={dim: frame})
df に単一のフレームやリストをそのまま渡す	df は次元名をキーとする辞書です
フレームに次元名と同じ名前の列がない	名前が正確に dim の列を追加してください。これが結合キーです
フレームの ID が ds[dim] と一部しか一致しない	集合として一致する必要があります（長さと要素の両方）。一致しない場合はエラーになります
座標に合わせてフレームの行を事前に並べ替える	不要です。構築時に自動で並べ替えられます
xo.to_zarr(...)／Xolars.open_zarr(...)	xo.write(path, mode)／Xolars.open(path)
xo.write(path)	mode が必要です。例：mode="w"
open 後のフレームが即時評価済みだと想定する	フレームは LazyFrame です。.collect() を呼び出してください