Source: https://docs.nygen.io/CyteArc/api/mapping.html Revision: fccee7b6e0c167e47ce605c8d292fba5b567ebfe Mapping API reference ********************* A mapping workflow retains every boundary explicitly: reference_ref = reference_ds.mapping.build_reference(neighbors_ref) reference = reference_ds.mapping.load_reference(reference_ref) query_cells = query_ds.snapshot_cell_selection("I") result_ref = query_ds.mapping.run(reference, query_cells) result = query_ds.mapping.load_result(result_ref, reference=reference) transfer_ref = query_ds.mapping.transfer_labels( result_ref, reference=reference, reference_labels="cell_type", ) transfer = query_ds.mapping.load_label_transfer(transfer_ref) "MappingReference" pins the exact feature selection and reference model. Query overlap is another feature-selection artifact. "mapping.run" returns only the projection ref; loaders, label transfer, score readers, and score plots require that ref plus the explicit reference. There is no named mapping registry, live "cell_key" routing, omitted-result lookup, or reference fallback. A handle is validated against its store in full when "mapping.load_reference" loads it. Every later operation that takes the handle checks the stored artifact record and its attributes against the handle, validates the cell selection against the current ordered cell IDs, and recomputes the digest of the handle’s arrays. Repeated label transfer and score calls avoid reading the reference model payload, index and neighbours. Each operation also compares the prepared dataset fingerprint stored on the reference assay with the fingerprint the handle carries; an unprepared or different reference dataset is rejected. Reading reference cell metadata also validates the stored selection against the current ordered cell IDs. A handle whose arrays or references changed is rejected with "does not match its stored artifact"; reload it with "mapping.load_reference". A query projection records the prepared dataset fingerprint of the query assay and reuses a complete projection only for the same query dataset, cells, overlap, reference, and options. A query cell is uninformative when its raw counts are zero in every reference feature that the query measured. Such a cell keeps its projection row but is flagged in "uninformative"; it receives no transferred label, adds no mapping score, and does not enter Symphony query-batch statistics or "queryScaledDispersion". "diagnostics["uninformativeCellCount"]" counts these cells. "queryScaledDispersion" averages the squared reference-scaled deviation of informative cells over the measured reference features only, so it does not depend on "missing_feature_policy". Projections written before this contract are rejected with an instruction to re-run "mapping.run". Label transfer ============== "mapping.transfer_labels" saves a label transfer as two query-owned artifacts. It first reads "reference_labels", a cell-metadata column of the reference datastore or a cell-label artifact in it such as "cluster_labels", "cluster_cut", or "clusters.relabel_by_overlap", and freezes those labels into the query datastore as a datastore-scoped "reference_labels" artifact. That artifact holds the reference classes and one class code per selected reference cell. Its identity records the mapping reference, the source column or the source artifact as an "ExternalArtifactRef", and a fingerprint of the labels, so unchanged labels reuse one frozen copy and changed labels create another. A missing, blank, or masked reference label never votes. It then saves a "label_transfer" artifact in the projection’s assay. Its inputs are the projection, the frozen reference labels, and the projection’s query cell selection; its parameters are "threshold_fraction", "max_distance", and the vote algorithm version. Each query cell takes the label with the largest share of its neighbours’ inverse-distance weight. A cell abstains when it is uninformative, has no labelled neighbour, ties between labels, falls below "threshold_fraction", or has its nearest reference neighbour beyond "max_distance". Abstention is stored as the linked missing mask of the "labels" array, never as a placeholder string, so a reference class named ""NA"" stays a class. The artifact also stores the reference classes, each cell’s neighbour votes, and the evidence below, and a payload fingerprint that loading verifies. A complete transfer with the same projection, frozen labels, and decision rule is reused. A read-only query datastore raises "PermissionError" before anything is computed or written when no match exists. "mapping.load_label_transfer" reads only the query datastore, so a saved transfer loads without the reference and never changes when the reference annotations change. Because "label_transfer" is a cell- label artifact, it can colour an embedding, group statistical tests and plots, and seed "select_cells" like a clustering; consumers that need a label for every cell reject it while it contains abstentions. "DataStore.artifacts.lineage(transfer_ref, references=reference)" follows the transfer into the reference datastore. "LabelTransferResult.evidence" has one row per projected query cell, in the order of "cell_selection", with these columns: +----------------------------------------------------+----------------------------------------------------+ | Column | Meaning | |====================================================|====================================================| | "label" | Transferred label, missing where the cell | | | abstained | +----------------------------------------------------+----------------------------------------------------+ | "candidateLabel" | Label the vote favoured before the threshold and | | | distance rules | +----------------------------------------------------+----------------------------------------------------+ | "voteFraction" | Share of neighbour weight that supports the | | | winning label | +----------------------------------------------------+----------------------------------------------------+ | "topTwoMargin" | Winning share minus the runner-up share | +----------------------------------------------------+----------------------------------------------------+ | "voteEntropy" | Entropy of the vote among labelled neighbours | +----------------------------------------------------+----------------------------------------------------+ | "nearestDistance" | Distance to the nearest reference neighbour | +----------------------------------------------------+----------------------------------------------------+ | "referenceDistancePercentile" | Percentile of that distance among reference | | | nearest-neighbour distances | +----------------------------------------------------+----------------------------------------------------+ | "abstained" | Whether the cell received no label | +----------------------------------------------------+----------------------------------------------------+ | "abstentionReason" | "uninformative_cell", "no_labeled_neighbors", | | | "tied_vote", "below_threshold", or | | | "beyond_max_distance" | +----------------------------------------------------+----------------------------------------------------+ Vote metrics are NaN for uninformative cells. Projection-level diagnostics such as "featureCoverage" and "queryScaledDispersion" stay in "mapping.load_result(...).diagnostics". "label_vote_shares(labels)" returns each cell’s vote share for given labels, and "prediction_sets(calibration_nonconformity, alpha)" forms split-conformal prediction sets from the saved votes, calibrated with one minus those shares on held-out cells. Both need the per-neighbour vote matrices, which hold one column per saved neighbour, so "mapping.load_label_transfer" loads them only with "load_votes=True". Each array that a load reads is checked against the digest recorded when the transfer was written. class cytearc.MappingReference(datastore, ref, assay_name, reduction, ann_index, neighbors, cell_selection, feature_selection, batch_correction, dataset_fingerprint, selected_cell_count, model, symphony_state, feature_ids, metadata, reference_distance_quantiles, reference_distance_values, payload_fingerprint, model_digest) An immutable scaled-PCA reference loaded from a CyteArc Zarr store. "payload_fingerprint" is the stored payload fingerprint the handle was loaded against and "model_digest" the digest of the arrays it was given; "validate_mapping_reference_binding" compares both with the store and with the handle instead of re-reading the payload. current_model_digest() Recompute the digest of the arrays this handle holds. Return type: "str" fetch_cell_column(column) Fetch one reference cell column through the stored cell selection. Return type: "ndarray" validate_dataset_fingerprint() Check the reference assay against the fingerprint the handle carries. Return type: "None" validate_frozen_axes() Validate the exact stored cell and feature axes used by the reference. Return type: "None" class cytearc.MappingResult(ref, n_cells, correction_method, diagnostics, reference, indices=None, distances=None, uninformative=None) One loaded query projection and its optional neighbor arrays. "uninformative" marks query cells whose raw counts are zero in every reference feature that the query measured. Their neighbor rows are stored but carry no query evidence, so label transfer and mapping scores skip them. property cell_selection: ArtifactRef Exact frozen query-row selection for this loaded projection. property feature_selection: ArtifactRef Exact frozen query-feature selection for this loaded projection. class cytearc.LabelTransferResult(ref, projection, reference_labels, reference_label_source, cell_selection, cell_idx, threshold_fraction, max_distance, categories, evidence, vote_class_codes=None, vote_class_fractions=None) One loaded label transfer: transferred query labels and their evidence. "evidence" has one row per projected query cell, in the order of "cell_selection"; "cell_idx" gives the matching query cell rows. "label" is the transferred label and is missing where the cell abstained. "abstentionReason" says why a cell abstained: "uninformative_cell" (no counts in any measured reference feature), "no_labeled_neighbors", "tied_vote", "below_threshold" ("voteFraction" below "threshold_fraction"), or "beyond_max_distance" ("nearestDistance" above "max_distance"). "candidateLabel" is the label that the vote favored before the threshold and distance rules, so other thresholds can be compared without a new transfer. "reference_labels" is the frozen copy of the reference labels in the query datastore, and "reference_label_source" names where they were read: a reference cell-metadata column, or a reference label artifact. "vote_class_codes" and "vote_class_fractions" hold, for each cell, the reference classes that its neighbors voted for, as positions in "categories", padded with -1, and each class’s share of the neighbor weight. These matrices hold one column per saved neighbor, so they are loaded only when requested, with "mapping.load_label_transfer(transfer, load_votes=True)"; "label_vote_shares()" and "prediction_sets()" need them. label_vote_shares(labels) Return each cell’s share of neighbor vote weight for a given label. "labels" holds one label per projected query cell, such as the known labels of held-out calibration cells. A label that is not a reference class has a share of zero. Missing labels and uninformative cells give NaN. One minus these shares is the nonconformity that "prediction_sets()" calibrates with. Return type: "ndarray" property labels: Series Transferred labels, missing where a cell abstained. property n_cells: int Number of projected query cells. prediction_sets(calibration_nonconformity, alpha=0.1) Return split-conformal prediction sets from the stored votes. "calibration_nonconformity" holds one minus the vote share of the true label for held-out calibration cells, which must be exchangeable with these query cells; "label_vote_shares()" computes those shares. A class joins a cell’s set when its nonconformity is not exceeded by more than a fraction "alpha" of the calibration cells. Cells without labeled votes get an empty set. Return type: "Series" DataStore methods ================= +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Package a scaled-PCA neighbor chain as an immutable artifact. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.buil | | | d_referenc | | | e" | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Load one mapping reference from an explicit artifact. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.load | | | _reference | | | " | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Map selected query cells into an immutable prepared reference. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.run" | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Load one complete query-owned mapping projection. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.load | | | _result" | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Yield reference-sized mapping scores for each requested query group. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.comp | | | ute_scores | | | " | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Transfer reference labels to projected query cells and save the result. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.tran | | | sfer_label | | | s" | | +------------+--------------------------------------------------------------------------------------------+ | "cytearc.d | Load one complete label transfer from this query datastore. | | atastore.n | | | amespaces. | | | MappingAcc | | | essor.load | | | _label_tra | | | nsfer" | | +------------+--------------------------------------------------------------------------------------------+ MappingAccessor.build_reference(neighbors, *, invalidate_cache=False) Package a scaled-PCA neighbor chain as an immutable artifact. Return type: "ArtifactRef" MappingAccessor.load_reference(reference) Load one mapping reference from an explicit artifact. Return type: "MappingReference" MappingAccessor.run(reference, cell_selection, *, query_assay=None, save_k=3, missing_feature_policy='reference_mean', query_batches=None, invalidate_cache=False) Map selected query cells into an immutable prepared reference. A query cell whose raw counts are zero in every reference feature that the query measured is recorded as uninformative. It keeps a projection row but is excluded from label transfer, mapping scores, Symphony query-batch statistics, and "queryScaledDispersion". Raises: **UnmeasuredCellsError** – If the query assay did not measure a selected cell. Return type: "ArtifactRef" MappingAccessor.load_result(result, *, reference, load_arrays=False) Load one complete query-owned mapping projection. Return type: "MappingResult" MappingAccessor.compute_scores(result, target_groups=None, *, reference, log_transform=True, multiplier=1000, weighted=True, fixed_weight=0.1) Yield reference-sized mapping scores for each requested query group. Return type: "Generator"["tuple"["Any", "ndarray"], "None", "None"] MappingAccessor.transfer_labels(projection, *, reference, reference_labels, threshold_fraction=0.5, max_distance=None, invalidate_cache=False) Transfer reference labels to projected query cells and save the result. The reference labels are first frozen into this query datastore as a "reference_labels" artifact, so a later change to the reference cannot change a saved transfer. Each query cell then takes the label with the largest share of its neighbors’ inverse-distance weight. A cell abstains, and its label is missing, when it is uninformative, no neighbor has a usable label, two labels tie, the winning share is below "threshold_fraction", or its nearest reference neighbor is farther than "max_distance". A high vote share means that the neighbors agree; it is not a calibrated probability. A complete transfer with the same projection, reference labels, and decision rule is reused. Parameters: * **projection** ("ArtifactRef") – Query projection returned by "run()". * **reference** ("MappingReference") – The mapping reference that the projection used. * **reference_labels** ("str" | "ArtifactRef") – A cell-metadata column of the reference datastore, or a cell-label artifact in it, such as "cluster_labels", "cluster_cut", or "smart_label". * **threshold_fraction** ("float") – Smallest winning vote share that assigns a label. * **max_distance** ("float" | "None") – Largest distance to the nearest reference neighbor that assigns a label. "None" sets no distance limit. * **invalidate_cache** ("bool") – Compute a new transfer even when a matching one exists. Frozen reference labels with the same fingerprint are still reused, because they are an exact copy. Return type: "ArtifactRef" Returns: Reference to the immutable "label_transfer" artifact. Load it with "load_label_transfer()", or use it wherever a cell-label artifact is accepted, such as "color_by" of an embedding plot. Raises: **PermissionError** – If no matching transfer exists and the query datastore is not opened with "zarr_mode='r+'". MappingAccessor.load_label_transfer(transfer, *, load_votes=False) Load one complete label transfer from this query datastore. Loading reads only this datastore, so the reference datastore is not needed and later changes to it do not change the result. Parameters: * **transfer** ("ArtifactRef") – Label transfer returned by "transfer_labels()". * **load_votes** ("bool") – Also load each cell’s neighbor votes, which "label_vote_shares" and "prediction_sets" need. The vote matrices hold one column per saved neighbor, so they are skipped by default. Return type: "LabelTransferResult" Returns: The transferred labels, their evidence, and the exact inputs. Mapping diagnostics are documented in the Plotting API reference API reference.