Documentation for Dataset

def define_hierarchies(self, clsses: List[str]):
    """
    Define hierarchical label groupings from ontology relationships.

    Uses Bionty to retrieve parent-child relationships for ontology terms,
    then builds groupings mapping parent terms to their descendants.
    Updates encoders to include parent terms and reorders labels so that
    leaf terms (directly predictable) come first.

    Args:
        clsses (List[str]): List of ontology column names to process.

    Raises:
        ValueError: If a class name is not in the supported ontology types.

    Note:
        Modifies self.labels_groupings, self.class_topred, and
        self.mapped_dataset.encoders in place.
    """
    # TODO: use all possible hierarchies instead of just the ones for which we have a sample annotated with
    self.labels_groupings = {}
    self.class_topred = {}
    for clss in clsses:
        if clss not in [
            "cell_type_ontology_term_id",
            "tissue_ontology_term_id",
            "disease_ontology_term_id",
            "development_stage_ontology_term_id",
            "simplified_dev_stage",
            "age_group",
            "assay_ontology_term_id",
            "self_reported_ethnicity_ontology_term_id",
        ]:
            raise ValueError(
                "class {} not in accepted classes, for now only supported from bionty sources".format(
                    clss
                )
            )
        elif clss == "cell_type_ontology_term_id":
            parentdf = (
                bt.CellType.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )
        elif clss == "tissue_ontology_term_id":
            parentdf = (
                bt.Tissue.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )
        elif clss == "disease_ontology_term_id":
            parentdf = (
                bt.Disease.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )
        elif clss in [
            "development_stage_ontology_term_id",
            "simplified_dev_stage",
            "age_group",
        ]:
            parentdf = (
                bt.DevelopmentalStage.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )
        elif clss == "assay_ontology_term_id":
            parentdf = (
                bt.ExperimentalFactor.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )
        elif clss == "self_reported_ethnicity_ontology_term_id":
            parentdf = (
                bt.Ethnicity.filter()
                .df(include=["parents__ontology_id", "ontology_id"])
                .set_index("ontology_id")
            )

        else:
            raise ValueError(
                "class {} not in accepted classes, for now only supported from bionty sources".format(
                    clss
                )
            )
        cats = set(self.mapped_dataset.encoders[clss].keys())
        groupings, _, leaf_labels = get_ancestry_mapping(cats, parentdf)
        groupings.pop(None, None)
        for i, j in groupings.items():
            if len(j) == 0:
                # that should not happen
                import pdb

                pdb.set_trace()
                groupings.pop(i)

        self.labels_groupings[clss] = groupings
        if clss in self.clss_to_predict:
            # if we have added new clss, we need to update the encoder with them too.
            mlength = len(self.mapped_dataset.encoders[clss])

            mlength -= (
                1
                if self.mapped_dataset.unknown_label
                in self.mapped_dataset.encoders[clss].keys()
                else 0
            )

            for i, v in enumerate(
                set(groupings.keys())
                - set(self.mapped_dataset.encoders[clss].keys())
            ):
                self.mapped_dataset.encoders[clss].update({v: mlength + i})

            # we need to change the ordering so that the things that can't be predicted appear afterward
            self.class_topred[clss] = leaf_labels
            c = 0
            update = {}
            mlength = len(leaf_labels)
            mlength -= (
                1
                if self.mapped_dataset.unknown_label
                in self.mapped_dataset.encoders[clss].keys()
                else 0
            )
            for k, v in self.mapped_dataset.encoders[clss].items():
                if k in self.labels_groupings[clss].keys():
                    update.update({k: mlength + c})
                    c += 1
                elif k == self.mapped_dataset.unknown_label:
                    update.update({k: v})
                    self.class_topred[clss] -= set([k])
                else:
                    update.update({k: v - c})
            self.mapped_dataset.encoders[clss] = update

def get_label_cats(
    self,
    obs_keys: Union[str, List[str]],
) -> np.ndarray:
    """
    Get combined categorical codes for one or more label columns.

    Retrieves labels from the mapped dataset and combines them into a single
    categorical encoding. Useful for creating compound class labels for
    stratified sampling.

    Args:
        obs_keys (str | List[str]): Column name(s) to retrieve and combine.

    Returns:
        np.ndarray: Integer codes representing the (combined) categories.
            Shape: (n_samples,).
    """
    if isinstance(obs_keys, str):
        obs_keys = [obs_keys]
    labels = None
    for label_key in obs_keys:
        labels_to_str = self.mapped_dataset.get_merged_labels(label_key)
        if labels is None:
            labels = labels_to_str
        else:
            labels = concat_categorical_codes([labels, labels_to_str])
    return np.array(labels.codes)

def get_unseen_mapped_dataset_elements(self, idx: int) -> list[str]:
    """
    Get genes marked as unseen for a specific sample.

    Retrieves the list of genes that were not observed (expression = 0 or
    marked as unseen) for the sample at the given index.

    Args:
        idx (int): Sample index in the dataset.

    Returns:
        List[str]: List of unseen gene identifiers.
    """
    return [str(i)[2:-1] for i in self.mapped_dataset.uns(idx, "unseen_genes")]