Upstream

Filtering

`mc_astra.up.filter_anndata_by_ncells(anndata_dict, min_cells)`

Filter samples by the number of cells in .obs['psbulk_cells'].

Updates the .var attribute with total counts per gene.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with AnnData objects as values.	required
`min_cells`	`int or dict[str, int]`	If int, the same minimum number of cells is applied to all AnnData objects. If dict, must have the same keys as `anndata_dict`, where each value is the minimum number of cells for that dataset.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.filter_views_by_samples(anndata_dict, min_rows)`

Filter views with fewer samples than the specified threshold.

Also updates the .var attribute to include total counts per gene.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with AnnData objects as values.	required
`min_rows`	`int`	Minimum number of rows required for an AnnData object to remain in the dictionary.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.filter_genes_byexpr(anndata_dict, min_count, min_prop)`

Filter genes by expression count prevalence within each view.

Also updates the .var attribute with total counts per gene.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with cell types as keys and AnnData objects as values.	required
`min_count`	`int`	Minimum count threshold for filtering genes.	required
`min_prop`	`float`	Minimum proportion of samples (rows) where the count is >= min_count.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.filter_views_by_genes(anndata_dict, min_genes_per_view)`

Drop views with fewer genes than the specified threshold.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with cell types as keys and AnnData objects as values.	required
`min_genes_per_view`	`int`	Minimum number of genes (columns) that must remain in an AnnData object for it to be kept.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.filter_samples_by_coverage(anndata_dict, threshold, min_prop)`

Filter samples by the proportion of genes above a coverage threshold.

Updates the dictionary in place and updates the .var attribute with total counts per gene.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with cell types as keys and AnnData objects as values.	required
`threshold`	`float or dict[str, float]`	Count threshold a gene value must exceed to be considered. If a dict, keys must match `anndata_dict`.	required
`min_prop`	`float or dict[str, float]`	Minimum proportion of genes that must exceed the threshold for a sample to be kept. If a dict, keys must match `anndata_dict`.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.filter_genes_by_celltype(anndata_dict, gene_lists)`

Exclude view-specific gene lists from AnnData objects.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with cell types as keys and AnnData objects as values.	required
`gene_lists`	`dict[str, list[str]]`	Dictionary with cell types as keys and lists of genes to exclude.	required

Returns:

Type	Description
`None`	The function modifies the input AnnData objects in place.

`mc_astra.up.filter_smpls_by_nview(anndata_dict, min_views)`

Filter samples that do not appear in enough views.

A sample (identified by its .obs.index) is kept only if it is present in min_views or more AnnData objects (views). The input dictionary is updated in place, with each AnnData object subset to the eligible samples.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with view or cell-type names as keys and AnnData objects as values. Sample identifiers are taken from `adata.obs.index` and must be comparable across views.	required
`min_views`	`int`	Minimum number of views in which a sample must be present to be retained.	required

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.get_hvgs(anndata_dict, groupby=None, ngroups_cut=2)`

Identify genes to exclude for each AnnData object, based on HVG masking.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with view/cell-type keys and AnnData objects as values.	required
`groupby`	`str`	Column name in .obs to group by when identifying HVGs. If None, HVGs are identified without grouping.	`None`
`ngroups_cut`	`int`	Minimum number of groups (batches) in which a gene must be highly variable to be retained. Only applicable if groupby is not None.	`2`

Returns:

Type	Description
`dict[str, list[str]]`	Dictionary with cell types as keys and lists of not variable genes to be excluded.

`mc_astra.up.filter_hvgs(anndata_dict, groupby=None, ngroups_cut=None)`

Identify highly variable genes (HVGs) for each AnnData object and filter out non-HVGs.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with view or cell-type names as keys and AnnData objects as values.	required
`groupby`	`str`	Column name in .obs to group by when identifying HVGs. If None, HVGs are identified without grouping.	`None`
`ngroups_cut`	`int`	Minimum number of groups (batches) in which a gene must be highly variable to be retained. Only applicable if groupby is not None.	`None`

Returns:

Type	Description
`None`	The input AnnData objects are updated in place, with non-HVGs filtered out and HVG-related annotation columns dropped from .var.

Preprocessing

`mc_astra.up.extract_metadata_from_obs(obs: pd.DataFrame, groupby: str, sort: bool = False) -> pd.DataFrame`

Extract group-level metadata from an observation table.

Only columns with a single unique value per group are retained.

Parameters:

Name	Type	Description	Default
`obs`	`DataFrame`	Observation metadata (e.g., `AnnData.obs`).	required
`groupby`	`str`	Column used to define groups.	required
`sort`	`bool`	Whether to apply natural sorting to group identifiers.	`False`

Returns:

Type	Description
`DataFrame`	Group-level metadata table.

`mc_astra.up.split_anndata_by_celltype(pdata, grouping='cell_type')`

Split an AnnData object into multiple AnnData objects by cell type.

Parameters:

Name	Type	Description	Default
`pdata`	`AnnData`	Input AnnData object.	required
`grouping`	`str`	Column in `pdata.obs` defining cell types.	`'cell_type'`

Returns:

Type	Description
`dict[str, AnnData]`	Dictionary mapping cell types to AnnData objects.

`mc_astra.up.norm_log(anndata_dict, target_sum=1000000.0, exclude_highly_expressed=False, max_value=None, center=True)`

Normalize, log-transform, and scale AnnData objects in place.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary of AnnData objects.	required
`target_sum`	`float`	Target total count per sample after normalization.	`1000000.0`
`exclude_highly_expressed`	`bool`	Whether to exclude highly expressed genes during normalization.	`False`
`max_value`	`float or None`	Maximum value after scaling to clip outliers.	`None`
`center`	`bool`	Whether to center features during scaling.	`True`

Returns:

Type	Description
`None`	The input dictionary is modified in place.

`mc_astra.up.norm_zscore(anndata_dict, center=True)`

Z-score transform each feature across observations in AnnData objects.

For each feature, the transformation is:

z = (x - mean) / standard_deviation

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary of AnnData objects. Each object is modified in place.	required
`center`	`bool`	Whether to subtract the feature mean before scaling. If False, features are divided by their standard deviation without centering.	`True`

Returns:

Type	Description
`None`	The input AnnData objects are modified in place.

Notes

Sparse matrices are converted to dense arrays because centering generally destroys sparsity.

Utils

`mc_astra.up.save_raw_counts(anndata_dict, layer_name='raw_counts')`

Store raw count data in a layer for each AnnData object.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary of AnnData objects.	required
`layer_name`	`str`	Name of the layer used to store raw counts.	`'raw_counts'`

Returns:

Type	Description
`None`	The input dictionary is modified in place.

`mc_astra.up.append_view_to_var(anndata_dict, join=':')`

Prefix feature names in each AnnData with its dict key and join separator.

This modifies the AnnData objects in-place. For example, if the key is "CM" and a gene is "gene1", the new var name becomes "CM:gene1" when join=":".

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary mapping views to AnnData objects.	required
`join`	`str`	Separator used between view name and feature name. Default is ":"	`':'`

Returns:

Type	Description
`None`	Updates `.var_names` in place.

`mc_astra.up.merge_adata_views(studies: list[dict[str, AnnData]], study_names: list[str], view_mode: str = 'union', min_view_studies: int = 2, var_mode: str = 'outer', min_var_studies: int = 2) -> dict[str, AnnData]`

Merge multiple study-level AnnData dictionaries into unified views.

Parameters:

Name	Type	Description	Default
`studies`	`list[dict[str, AnnData]]`	List of study dictionaries, each mapping view names to AnnData objects.	required
`study_names`	`list[str]`	Unique identifiers for each study. Must align with `studies`.	required
`view_mode`	``{'union', 'intersection', 'min_n'}``	Strategy for selecting views across studies.	`'union'`
`min_view_studies`	`int`	Minimum number of studies required when `view_mode='min_n'`.	`2`
`var_mode`	``{'inner', 'outer', 'min_n'}``	Strategy for merging variables (features).	`'outer'`
`min_var_studies`	`int`	Minimum number of studies required when `var_mode='min_n'`.	`2`

Assumptions

note:: Observation columns are harmonized across studies. Observation names are unique across studies. Feature names are harmonized across studies. View names are consistent across studies. study_names uniquely identify studies.

Returns:

Name Type Description

merged

dict[str, AnnData]

Dictionary of merged AnnData objects, one per retained view.

Keys Each key corresponds to a view (modality/cell type) retained according to view_mode across the input studies.

Values Each value is an AnnData object resulting from concatenating the corresponding AnnData objects from all studies that contain that view. Guarantees:

- `.obs` columns: only columns present in all contributing studies
  are retained (strict intersection).
- `.obs_names` (row identifiers): all original observation names
  are preserved; duplicates across studies are not allowed.
- `.obs["study"]`: column indicating the study of origin for each
  observation, using the names provided in ``study_names``.
- `.var` columns (features):
    * ``"inner"`` → only variables present in all contributing studies
    * ``"outer"`` → all variables present in at least one contributing study
    * ``"min_n"`` → variables present in at least ``min_var_studies`` studies
- `.uns` and other metadata are merged conservatively with unique keys.
- The resulting AnnData objects are copies; modifying them will
  not affect the original input studies.

`mc_astra.up.convert_views_to_functions(anndata_dict, net, tmin=5)`

Apply decoupler ULM to each AnnData object with the provided network.

Rewrites the input dictionary in place, replacing each AnnData object with the result of the decoupler analysis.

Parameters:

Name	Type	Description	Default
`anndata_dict`	`dict[str, AnnData]`	Dictionary with AnnData objects as values.	required
`net`	`DataFrame`	Long-format (tidy) DataFrame representing a network, where each row defines an interaction between a source and a target. Required columns: - `source`: identifier of the source node - `target`: identifier of the target node Optional columns: - `weight`: numeric value representing interaction strength	required
`tmin`	`int`	Minimum number of targets required per source. Sources with fewer than `tmin` associated targets are filtered out.	`5`

Returns:

Type	Description
`None`	The function modifies the input dictionary in place.

`mc_astra.up.make_membership_matrix(adata, pathways_df, gene_col='genesymbol', pathway_col='pathway')`

Build a boolean gene × pathway membership matrix aligned with adata.var.index.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	AnnData object with genes in .var.index	required
`pathways_df`	`DataFrame`	Long-format DataFrame with at least two columns: gene_col and pathway_col	required
`gene_col`	`str`	Column in pathways_df containing gene names	`'genesymbol'`
`pathway_col`	`str`	Column in pathways_df containing pathway names	`'pathway'`

Returns:

Type	Description
`DataFrame`	Boolean DataFrame (rows=adata.var.index, columns=unique pathways)

`mc_astra.up.get_nhood_enrichment_feats(adata, metadata, sample_key: str = 'biosample_id', cluster_key: str = 'celltype', spatial_key: str = 'spatial', coord_type: str = 'generic', n_perms: int = 1000, diagonal: bool = True, symmetric: bool = True, fillna: float | None = 0.0)`

Build sample-level neighborhood enrichment features.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	AnnData object containing spatial coordinates and observation metadata.	required
`metadata`	`DataFrame`	Sample-level metadata indexed by `sample_key`.	required
`sample_key`	`str`	Column in `adata.obs` defining samples/patients.	`'biosample_id'`
`cluster_key`	`str`	Column in `adata.obs` defining cell types or clusters.	`'celltype'`
`spatial_key`	`str`	Key in `adata.obsm` containing spatial coordinates.	`'spatial'`
`coord_type`	`str`	Coordinate type passed to `squidpy.gr.spatial_neighbors`.	`'generic'`
`n_perms`	`int`	Number of permutations for neighborhood enrichment.	`1000`
`diagonal`	`bool`	Whether to keep same-celltype features, e.g. `T__T`.	`True`
`symmetric`	`bool`	Whether to keep only one triangle of the celltype-pair matrix.	`True`
`fillna`	`float or None`	Value used to replace NaN z-scores. Set to `None` to keep NaNs.	`0.0`

Returns:

Name	Type	Description
`spatial_interaction_adata`	`AnnData`	AnnData object with samples as observations and celltype-pair neighborhood enrichment z-scores as variables.

`mc_astra.up.get_cell_props(adata: AnnData, sample_key: str, cell_type_key: str, metadata: pd.DataFrame) -> AnnData`

Build sample-level center-log-ratio cell type composition features.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	AnnData object with `adata.obs` containing sample and cell type or grouping information.	required
`sample_key`	`str`	Column in `adata.obs` defining samples/patients.	required
`cell_type_key`	`str`	Column in `adata.obs` defining cell types or clusters.	required
`metadata`	`DataFrame`	DataFrame containing metadata for the samples, indexed by `sample_key`.	required

Returns:

Name	Type	Description
`clr_props_adata`	`AnnData`	AnnData object with samples as observations and center-log-ratio transformed cell type proportions as variables.

`mc_astra.up.get_contaminant_genes(pdata, view_group='celltype', min_count=10, min_total_count=20, large_n=10, min_prop=0.4, lfc_threshold=3, p_threshold=0.001)`

Identify contaminant marker genes for each cell type.

This function performs differential expression analysis to find genes that are significantly upregulated in one cell type compared to all others, and then identifies genes that are markers for other cell types as potential contaminants. Simple Wilcoxon tests are performed after cell-type specific filterings and normalization of data.

Parameters:

Name	Type	Description	Default
`pdata`	`AnnData`	The AnnData object containing the pseudobulk expression data and cell type annotations.	required
`view_group`	`str`	The column in `pdata.obs` that contains the cell type annotations. Default is "celltype".	`'celltype'`
`min_count`	`int`	A minimum read count in a minimum number of samples.	`10`
`min_total_count`	`int`	A minimum total read count across all samples.	`20`
`large_n`	`int`	Number of samples per group that is considered to be “large”.	`10`
`min_prop`	`float`	Minimum proportion of samples in the smallest group that express the gene.	`0.4`
`lfc_threshold`	`float`	The log fold change threshold for considering a gene as a marker. Default is 3.	`3`
`p_threshold`	`float`	The adjusted p-value threshold for considering a gene as a marker. Default is 0.001.	`0.001`

Returns:

Name	Type	Description
`contaminants_dict`	`dict`	A dictionary where keys are cell types and values are lists of genes that are considered contaminants for that cell type.