sddb.Catalog#

class sddb.Catalog(url: str | None = None, *, cache_dir: str | Path | None = None, version: str | None = None, refresh: bool = False)#

The dataset catalog: fetched, cached and validated on construction.

Attributes table#

`features`	Cross-dataset multi-modal feature index bound to this catalog (loaded lazily).
`generated_at`	Generation timestamp from the parquet metadata, if present.
`genes`	Cross-dataset gene index bound to this catalog (loaded lazily).

Methods table#

`cohort`(*[, uids, study_ids])	Build a cohort from an explicit set of `uids` or `study_ids` (exactly one).
`collection`(slug)	The members of one collection as a cohort, by its slug (the last part of its web page URL).
`dataset`(uid)	The catalog row for one dataset, by full `uid`, its 16-character stem or its `canonical_key`.
`facets`([name])	List the facet columns, or the values of one facet.
`from_file`(path, *[, cache_dir])	Load a catalog from a local `catalog.parquet` (absolute or relative path, or `file://` URL).
`query`(*[, validation, license_set, ...])	Filter the catalog.
`search`(text)	Deterministic text search over facet values.
`to_df`()	Return the full catalog as a DataFrame copy.

Attributes#

property features: FeatureIndex#: Cross-dataset multi-modal feature index bound to this catalog (loaded lazily).

property generated_at: str | None#: Generation timestamp from the parquet metadata, if present.

property genes: GeneIndex#: Cross-dataset gene index bound to this catalog (loaded lazily).

Methods#

cohort(*, uids: list[str] | None = None, study_ids: list[str] | None = None) → SpatialDataCohort#

Build a cohort from an explicit set of uids or study_ids (exactly one).

Raises KeyError naming any id not in the catalog; a valid but empty result warns.

collection(slug: str) → SpatialDataCohort#

The members of one collection as a cohort, by its slug (the last part of its web page URL).

Members are the catalog rows listing slug in their collections column, in catalog order. Raises KeyError if no row lists it.

dataset(uid: str) → Dataset#

The catalog row for one dataset, by full uid, its 16-character stem or its canonical_key.

A uid pins one version. A stem resolves to the latest version. A canonical_key such as "geo:GSM9778330" is unique where it is set and usually survives a re-version of the dataset; datasets without one (null in the column) cannot be looked up this way. Raises KeyError if absent or ambiguous.

facets(name: str | None = None) → list[str]#

List the facet columns, or the values of one facet.

These are the names and values that query() accepts, and the list that the "did you mean" hint of an unknown value points to. It is the same list as sddb-cli facets and the MCP facets tool.

Parameters:

name: A facet column such as "organism". None lists the facet columns in this catalog.

Returns:

list[str] The facet columns, or the sorted distinct non-null values of name. A list-valued facet (modalities) gives each element once.

Raises:

ValueError -- If name is not a facet of this catalog.

classmethod from_file(path: str | Path, *, cache_dir: str | Path | None = None) → Catalog#

Load a catalog from a local catalog.parquet (absolute or relative path, or file:// URL).

Parameters:

path: Local parquet path; validated against the catalog schema like any other catalog.
cache_dir: Cache directory override.

Filter the catalog.

To start from known uids or study ids, use Catalog.cohort().

Parameters:

validation: Keep rows with this validation_status (default "pass"); None disables. In the current catalog every dataset passes validation, so this filter changes nothing yet. Filter on tier (silver, bronze) for quality.
license_set: If True, keep only rows with a known license (license_unknown is False); False behaves like None.
noncommercial: If False, keep only data cleared for commercial use: license_noncommercial is False and the license is known (license_unknown is False), the same set the website counts as "Commercial use OK". Rows with an unknown license are excluded because their terms are not known. If True, keep only NonCommercial data; None disables.
redistributable: If True, keep only data whose license allows redistribution: license_redistributable is True and the license is known (license_unknown is False). If False, keep the rest, which includes every row with an unknown license. None disables. Every dataset is served. The default None applies no license filter, so rows with an unknown license stay in the result; check the license before you reuse data.
search: Free text, as in search(); the result is intersected with the other filters and carries the matched facet values. With validation=None (or "all"), search still imposes its own validation_status == "pass" filter unless validation_status was itself matched, so failed rows do not survive a search.
expressing: Gene symbol or Ensembl id, or a list of them; keep datasets where they are expressed (see genes.where_expressed). The first use downloads the gene index (~900 MB, cached).
mode: With several expressing genes: "all" (default, AND) or "any" (union).
min_fraction: Minimum fraction of expressing cells for expressing; requires expressing.
**facets: Facet column -> value (equality) or list/tuple/set of values (isin). license and license_noncommercial are facets, so you can also filter by exact license id. String facets compare a value against that column of the whole catalog first. A value that is not there resolves through aliases: case, spaces, hyphens and underscores are ignored, and a technology value may be an assay display value (technology="10x Xenium" keeps "Xenium"). A value that still does not resolve raises ValueError with a "did you mean" hint. A known value that matches nothing after the other filters gives an empty cohort. hne_image and if_image take True or False. Null means unknown and matches neither. source is derived on load as the lowercased study_id prefix before ":"; rows without a study_id have a null source. In the 2026-10-28 catalog (6087 rows) it is geo 4113, hest 1070, 10x 175, abc 115, bia 4, metaspace 3, bruker 3, doi 2, figshare 2, and null 600. <col>__gte / __gt / __lte / __lt apply a numeric range on a column in RANGE_COLUMNS (e.g. n_obs__gte=50_000); missing values never match.

Raises:

ValueError -- If a keyword is not a facet or range column, a facet column is absent from the loaded catalog, a facet value is not in the catalog and has no alias, a boolean facet gets a non-bool value, a range value is not numeric, or min_fraction is given without expressing.

search(text: str) → SpatialDataCohort#

Deterministic text search over facet values.

Each token is fuzzy/substring-matched against the distinct values of each facet. A row matches a token when any of its facet values matches it, in any facet, so "liver" finds rows whose tissue is liver as well as rows whose study_id contains "liver". Tokens are AND-ed: "breast xenium" keeps rows that match both. A token that matches no facet value is ignored, with one warning that names it; if no token matches anything, the result is an empty SpatialDataCohort with a warning. matched maps each facet to the values that matched any token. Rows that failed validation are excluded unless validation_status itself was matched.

to_df() → DataFrame#: Return the full catalog as a DataFrame copy.