Query

Lazy and eager query builders for transform pipelines and deferred execution.

radiobject.query.LazyQuery

Lazy filter builder for VolumeCollection with deferred transforms.

Use .lazy() to enter lazy mode, then chain .filter(), .head(), .map(), and .write() to build and execute a transform pipeline.

Example

Filter and write high-resolution volumes:

high_res = (
    radi.T1w.lazy()
    .filter("voxel_spacing == '1.0x1.0x1.0'")
    .head(100)
    .map(normalize)
    .write("./output")
)

__len__()

Number of volumes matching the query.

count()

Count volumes matching the query.

filter(expr)

Filter volumes using TileDB QueryCondition on obs.

filter_subjects(ids)

Filter to volumes belonging to specific subject IDs.

head(n=5)

Filter to first n volumes.

iloc(key)

Filter volumes by integer position(s).

iter_volumes()

Iterate over volumes matching the query.

loc(key)

Filter volumes by obs_id(s).

map(fn)

Apply transform to each volume during write.

Multiple map() calls compose: query.map(f1).map(f2) applies f1 then f2. Transform receives (volume, obs_row) and can return volume or (volume, obs_updates).

sample(n=5, seed=None)

Filter to n randomly sampled volumes.

tail(n=5)

Filter to last n volumes.

to_numpy_stack()

Load all matching volumes as stacked numpy array (N, X, Y, Z).

to_obs()

Return filtered obs DataFrame.

write(uri=None, name=None, ctx=None)

Write query results as a new VolumeCollection.

Applies queued transforms and persists in a single pass. Transforms receive (volume, obs_row) and can return volume or (volume, obs_updates).

radiobject.query.EagerQuery

Bases: Generic[T]

Computed query results with pipeline methods.

Holds materialized results paired with obs metadata and accumulated obs_updates, enabling chained transforms via .map(), persistence via .write(), and tabular display via .to_dataframe() / _repr_html_().

Transforms can return either just a value, or (value, obs_updates_dict) to annotate obs metadata. Updates accumulate across chained .map() calls and are merged into obs rows on .write().

map(fn)

Chain another transform, applying fn(result, obs_row) immediately.

If fn returns (value, obs_updates_dict), the updates are accumulated and merged into the obs_row for subsequent transforms and on .write().

to_dataframe(columns=None)

Summarize results as a DataFrame with obs metadata and result column.

to_list()

Extract results paired with merged obs rows.

write(uri, name=None, ctx=None)

Persist results to a new VolumeCollection (results must be np.ndarray).