Source: https://docs.nygen.io/CyteArc/api/cytebase.html Revision: fccee7b6e0c167e47ce605c8d292fba5b567ebfe CyteBase API reference ********************** The CyteBase SDK connects directly to cloud-hosted CyteArc DataStores for exploration and analysis without downloading a complete dataset first. Search the catalog, open a shared store read-only, or mount it for writable analysis with remote counts. Install the "cytebase" extra described in Installation and follow Explore CyteBase for an executable walkthrough, and CyteBase case study: COVID-19 blood for a longer use case. Use the same SDK from a local notebook or cloud compute. Operations read metadata and count blocks over the network and run in your Python environment; the SDK does not provision compute. Configure a catalog =================== from cytearc.cytebase import Catalog catalog = Catalog() "Catalog()" defaults to the latest public release, currently "Nygen/cytebase-2610". Public readers do not need credentials, and dataset stores are opened read-only. Each release has its own bucket named by year and month ("YYMM"); a later release in the same month adds a patch number ("YYMM.N"). Select another release with "Catalog(version="2610.1")", which opens "Nygen/cytebase-2610.1". "releases()" lists every public release, newest first, with its bucket, release month, notes, and changelog. The release marked "latest" is the one "Catalog()" opens by default. from cytearc import cytebase for release in cytebase.releases(): print(release.version, release.bucket, release.latest, release.notes) cytearc.cytebase.releases() Return every public CyteBase release, newest first. Each release names its "version", its "bucket", the "released" month, "notes", and a "changelog". "latest" marks the release that "Catalog()" opens when neither a bucket nor a version is given; open another with "Catalog(version=...)". Return type: "tuple"["Release", "..."] class cytearc.cytebase.Release(version, released, notes, changelog=()) One public CyteBase release and the bucket that holds it. "version" is "YYMM" or "YYMM.N", "released" is the "YYYY-MM" month of release, "notes" summarizes the release, and "changelog" lists its changes. property bucket: str Return the "namespace/name" of this release’s bucket. property latest: bool Return whether "Catalog()" opens this release by default. To use any other bucket, pass "Catalog(bucket=...)" or set "CYTEBASE_BUCKET". Accepted forms are "namespace/name" and "hf://buckets/namespace/name". Resolution order is "bucket=", then "version=", then "CYTEBASE_BUCKET", then the latest release; passing both "bucket=" and "version=" raises an error. The default "token=None" uses Hugging Face credentials when available and anonymous access otherwise; "token=False" explicitly selects anonymous access. This SDK default does not apply to the ingestion pipeline. Its writes go to the bucket that "CYTEBASE_BUCKET" names in the deployment’s "cytearc-env" secret, or to the release bucket that "python -m cytearc.cytebase.pipeline.deploy --bucket-version 2610.1" selects. Construction downloads or reuses a verified local DuckDB catalog. Each new query checks its published SHA-256 checksum and refreshes the local copy when needed. Queries therefore require network access even when a cached catalog exists. Counts remain remote until an operation reads them. "connect_catalog()" exposes a read-only DuckDB connection; close it after use, for example with a "with" block. Discover datasets ================= "search(text)" matches every whitespace-separated search word, ignoring case, across dataset IDs, titles, citations, first authors, and facet labels. Its default result limit is 50; "limit=None" removes that limit. "find_datasets(**facets)" matches exact labels, combining different facets with AND and values within a list with OR. Use "list_terms(facet)" to discover the available labels before filtering. Supported facets are "tissue", "organ", "disease", "assay", "organism", "cell_type", "sex", "development_stage", and "suspension_type". Both search methods default to "ready_only=True", which selects datasets with a ready store for their latest registered version. Pass "ready_only=False" to include other registered datasets. Results are ordered by descending cell count, then CyteBase ID. "list_terms()" summarizes terms across the registered catalog, including datasets that are not ready. catalog.list_terms("tissue") matches = catalog.find_datasets(organism="Homo sapiens", tissue=["lung", "blood"]) catalog.search("lung", limit=10) "query(sql, parameters=None)" supports parameterized SQL over the local catalog. The "datasets" table holds dataset rows, and "dataset_terms" holds facet labels and ontology IDs. class cytearc.cytebase.Catalog(bucket=None, token=None, *, version=None) Discover dataset entries and open their verified CyteArc DataStores. "bucket" accepts "namespace/name" or an HF bucket URI. "version" selects a public release bucket by year and month, "YYMM" or "YYMM.N" for a later release in the same month, such as ""2610.1"" for "Nygen/cytebase-2610.1". Without either, "CYTEBASE_BUCKET" applies, and otherwise the release that "cytearc.cytebase.releases()" marks as latest. "token=None" uses standard Hugging Face authentication when available; "token=False" explicitly selects anonymous access. Construction prepares a verified local catalog. Each new catalog query checks the published checksum again and opens a verified local snapshot read-only. connect_catalog() Open a verified local snapshot; callers must close the connection. Return type: "DuckDBPyConnection" dataset(cytebase_id) Return descriptive dataset metadata without opening a DataStore. Return type: "DatasetEntry" find_datasets(*, ready_only=True, max_cell_chars=100, **facets) Match exact labels: every facet must match, with OR within label lists. Discovery includes all registered datasets unless "ready_only=True". Row dictionaries retain every catalog column, including "zarr_uri". Set "max_cell_chars=None" to display full cell values. Return type: "CatalogResults" list_terms(facet=None, *, max_cell_chars=100) List naturally sorted terms; "max_cell_chars=None" shows full values. Return type: "CatalogResults" mount_datastore(cytebase_id, at, **datastore_options) Create or reopen a writable local DataStore with verified remote counts. Return type: cytearc.datastore.datastore.DataStore open_datastore(cytebase_id, **datastore_options) Return a new read-only DataStore after checking current provenance. Keep the returned DataStore for repeated reads and plots. Catalog entries never cache or implicitly open DataStores. Return type: cytearc.datastore.datastore.DataStore query(sql, parameters=None, *, max_cell_chars=100) Query the local catalog; "max_cell_chars=None" shows full cell values. Return type: "CatalogResults" search(text, *, ready_only=True, limit=50, max_cell_chars=100) Find datasets whose text matches every word in "text", ignoring case. Words are matched against the ID, title, citation, first author, and all facet labels. Use "find_datasets()" for exact ontology labels. Set "max_cell_chars=None" to display full cell values. Return type: "CatalogResults" Inspect a catalog entry ======================= "catalog.dataset(cytebase_id)" returns a "DatasetEntry" containing metadata about a scientific dataset. Its "row" dictionary contains the complete catalog row; "id", "title", "citation", and "cell_count" provide convenient access to common fields. Displaying the entry in a notebook renders "describe()", a Markdown summary that can fetch the published dataset record. Entries are metadata-only: they do not open a datastore, read cell arrays, mount an analysis, or plot. "record()" fetches the published "dataset.json" and caches it on the entry. "source_embeddings()" lists the source H5AD’s embedding keys recorded in that JSON. The source list describes what was inspected and may include keys whose coordinates were not imported. class cytearc.cytebase.DatasetEntry(catalog, row) Describe a registered dataset without opening its Zarr hierarchy. Catalog fields and source provenance belong to this entry. Open or mount a DataStore through the catalog to read cells, assays, and analysis artifacts. property cell_count: int | None property citation: str | None describe() Summarize the dataset as Markdown without opening its Zarr store. Return type: "str" property id: str record() Return the published "dataset.json" record, cached after the first read. Return type: "dict" source_embeddings() List every "obsm" key in the source H5AD, imported or not. Return type: "list"["str"] property title: str | None Open a datastore ================ from cytearc import cytebase entry = catalog.dataset(matches[0]["cytebase_id"]) ds = catalog.open_datastore(entry.id) umap_ref = cytebase.embedding(ds, "X_umap") ds.plots.embedding(layout=umap_ref, color_by="cell_type", figsize=(10, 6)) "open_datastore(cytebase_id, **datastore_options)" checks the current published provenance and returns a read-only "DataStore". Each call opens and validates a datastore; retain the returned "ds" for subsequent operations. Published cell annotations and imported embeddings are source results, so displaying them does not recompute an analysis. Read cell metadata through "ds.cells.to_pandas_dataframe(columns, key="I")". This returns a pandas DataFrame for the cells selected by "I". Select the needed columns to limit metadata reads. Plot through "ds.plots.embedding(layout=ref, ...)", using an exact embedding artifact reference. See Plotting API reference for its controls and returned "PlotResult". "mount_datastore(cytebase_id, at, **datastore_options)" creates or reopens a writable local "DataStore" with remote counts pinned to one verified source build. The destination must be a local path. Keep its adjacent ".cytebase.json" receipt with the mount; a changed source build requires a new destination. Mounting keeps counts remote and requires network access for subsequent reads. See Remote stores and mounted analysis targets for working with remote matrices and local results. A mount copies cell and feature metadata and resolves the published source artifacts, such as imported embeddings, read only. The embedding helpers and plots therefore work on the mount as on the read-only datastore. New analysis artifacts are written to the mount. Resolve imported embeddings =========================== "cytebase.embeddings(ds, *, assay="RNA")" maps imported source embedding keys to exact "ArtifactRef" values in the open datastore. "cytebase.embedding(ds, key="X_umap", *, assay="RNA")" selects one of these references. These helpers inspect the imported artifacts the datastore resolves, which on a mount include its source’s. "cytebase.embedding_coordinates(ds, ref)" returns a DataFrame of the complete referenced embedding, indexed by cell ID. Row alignment follows the artifact’s frozen cell selection, including when the live "I" column has changed. Join coordinates to metadata by cell ID for custom plotting. Metadata tables and coordinate exports materialize the requested columns or coordinates in memory; they do not materialize the complete count matrix. cytearc.cytebase.embeddings(ds, *, assay='RNA') Map imported source keys to complete embedding artifacts in "assay". Discovery uses the DataStore’s artifact provenance and needs no catalog connection. A mount also finds the embeddings imported into its source, which it resolves read only. Multiple imports of the same key, including one in the source and one in the mount, are ambiguous and require choosing an explicit artifact reference. Return type: "dict"["str", "ArtifactRef"] cytearc.cytebase.embedding(ds, key='X_umap', *, assay='RNA') Return the unique imported embedding for "key", or report missing data. Return type: "ArtifactRef" cytearc.cytebase.embedding_coordinates(ds, ref) Read coordinates indexed by the embedding’s frozen cell IDs. "ref" must identify an embedding artifact. Its saved cell selection determines row alignment, independently of the DataStore’s current filter. Return type: "DataFrame" Prerelease API change ===================== This prerelease replaces "CytebaseDataset" with the metadata-only "DatasetEntry". "Catalog.open_datastore" and "Catalog.mount_datastore" replace "Catalog.open_dataset" and "Catalog.mount_dataset". The former dataset-handle methods for opening, mounting, metadata, embeddings, and plotting are removed. These names and methods have no compatibility aliases. Update existing notebooks to keep the catalog entry in "entry", open a "DataStore" as "ds", and use the datastore and module-level helpers shown above. Work with result tables ======================= Catalog discovery and SQL methods return "CatalogResults", a list- compatible collection of complete row dictionaries. Indexing and iteration expose full values; slicing produces a plain list. Notebook output displays at most 20 rows and shortens cells to 100 characters by default. These display limits do not remove rows or shorten values in the underlying dictionaries. matches[0]["cytebase_id"] matches.to_markdown(columns=["cytebase_id", "title"], max_rows=None, max_cell_chars=None) Pass "max_cell_chars=None" to a catalog query to show complete cell values in its default notebook representation. Use "to_markdown()" to choose displayed columns and row limits. class cytearc.cytebase.display.CatalogResults(rows=(), *, columns=(), max_cell_chars=100) List-compatible rows with a compact Markdown representation. Indexing and iteration expose the original complete row dictionaries. As with a normal list, slicing returns a list. "list(results)" gives a plain list for callers that require the exact built-in type. Display truncation never modifies records or changes the query’s ordering. "max_cell_chars" sets the notebook and text representation limit; "None" shows full values. to_markdown(columns=None, max_rows=20, max_cell_chars=100) Render selected columns, using "max_rows=None" to display every row. Long cell values are shortened to "max_cell_chars" characters. Set "max_cell_chars=None" to display full label lists, identifiers, and URIs. Return type: "str" Public example repositories =========================== The repository interface lists and downloads CyteArc’s public example files. It uses repository and dataset directory names, while "Catalog" discovers catalog datasets by CyteBase ID. The examples in other tutorials use "connect("cytearc_docs")" and "Repository.download_dataset(..., zarr=True)" to download and extract prepared CyteArc stores. cytearc.cytebase.list_repositories() Return the top-level repositories in CyteBase. Return type: "list"["str"] cytearc.cytebase.connect(repository) Connect to a public CyteBase repository. Return type: "Repository" class cytearc.cytebase.Repository(name) Read files from one top-level CyteBase repository. download(path, destination='.') Download a file or directory while preserving its repository path. Return type: "list"["Path"] download_dataset(name, destination='.', *, zarr=False) Download one dataset, optionally selecting its Zarr archive. Return type: "Path" list_datasets() Return immediate dataset directories in this repository. Return type: "list"["str"]