Downstream

Tools

mc_astra.down.run_ulm_per_view(view_dict: dict[str, pd.DataFrame], net: pd.DataFrame, **kwargs) -> dict[str, dict[str, pd.DataFrame]]

Run ULM (univariate linear modeling) separately for each view.

Parameters:

Name	Type	Description	Default
view_dict	dict[str, DataFrame]	Dictionary mapping view names to expression matrices (e.g., archetypes × genes).	required
net	DataFrame	Prior knowledge network in a decoupler-compatible format.	required
**kwargs	dict	Additional keyword arguments passed to decoupler.mt.ulm.	{}

Returns:

Type	Description
dict[str, dict[str, DataFrame]]	Dictionary mapping view names to result dictionaries containing pathway activities (pw_acts) and adjusted p-values (pw_padj).

mc_astra.down.get_associations(adata, test_variable, test_type=None, random_effect=None)

Test associations between model features and an observation-level covariate.

Using: - For continuous covariates with no random_effect: Pearson correlation. - For categorical covariates with no random_effect: one-way ANOVA (F-test). - If random_effect is given: likelihood-ratio test on linear mixed models.

Parameters:

Name	Type	Description	Default
adata	AnnData	Annotated data matrix with features in .X and covariates in .obs.	required
test_variable	str	Column in adata.obs to test for association.	required
test_type	``continuous``, ``categorical``	Type of the test variable. If None, inferred from data type.	``continuous``
random_effect	str or None	Column in adata.obs specifying grouping for a random intercept.	None

Returns:

Type	Description
DataFrame	DataFrame with columns feature, p_value, and adj_p_value.

mc_astra.down.calc_total_variance(adata, associations_df, pval_thrs=0.05)

Compute the total explained variance per view for statistically significant features.

This function aggregates the R² values stored in adata.var by summing them across features that pass a significance threshold in the associations table. Variance is computed separately for each view/group as defined by split_by_view.

Parameters:

Name	Type	Description	Default
adata	AnnData	Model AnnData object containing explained variance (R²) values in adata.var.	required
associations_df	DataFrame	Output from get_associations containing feature-level p-values and adjusted p-values. Must include columns ['feature', 'adj_p_value'].	required
pval_thrs	float, ``optional``	Adjusted p-value threshold used to select significant features. Default is 0.05.	0.05

Returns:

Type	Description
dict[str, Series]	Dictionary mapping each view/group name to a Series containing the summed explained variance per factor across significant features.

mc_astra.down.get_pval_matrix(adata, covars)

Compute adjusted p-value associations for multiple covariates in a model AnnData.

For each covariate, this function calls down.get_associations to test its association with model factors and collects the adjusted p-values into a DataFrame (p_df). Each column corresponds to a covariate and each row to a factor (adata.var index).

Parameters:

Name	Type	Description	Default
adata	AnnData	AnnData object containing model factors in .var and covariates in .obs.	required
covars	list[str]	Covariate names in adata.obs to test.	required

Returns:

Type	Description
DataFrame	Matrix of adjusted p-values with factors as rows and covariates as columns.

mc_astra.down.get_loading_gset(col, source_base: str, percentile: float = 0.85) -> pd.DataFrame

Extract a gene set from a vector of loadings using a percentile threshold.

Parameters:

Name	Type	Description	Default
col	Series or DataFrame	Loadings for a single factor. Index corresponds to target/features.	required
source_base	str	Base name for the gene set (e.g., "Cardiomyocytes").	required
percentile	float	Quantile in [0, 1] computed separately for positive and negative loadings. Default is 0.85.	0.85

Returns:

Type	Description
DataFrame	DataFrame containing the selected gene set.

mc_astra.down.build_info_networks(multicell_scores: pd.DataFrame, random_effect: pd.Series | pd.Index | pd.Categorical | np.ndarray | None = None, standardize: bool = False, drop_na: bool = True, verbose: bool = True) -> pd.DataFrame

Fit pairwise linear models to infer directed information networks.

Parameters:

Name	Type	Description	Default
multicell_scores	DataFrame	Enriched scores with shape (samples × features).	required
random_effect	``array-like`` or None	Optional grouping vector defining random intercepts. Length must match the number of rows.	None
standardize	bool	If True, z-score each feature before fitting.	False
drop_na	bool	If True, drop rows containing missing values.	True
verbose	bool	If True, emit warnings for skipped model fits.	True

Returns:

Type	Description
DataFrame	Table with columns: target, predictor, coef, R2, cor_estimate, n_samples, model_type.

mc_astra.down.get_multicell_net(test_model: ad.AnnData, sel_factor: str, views: str | list[str] | None = None, random_effect: pd.Series | pd.Index | pd.Categorical | np.ndarray | None = None, standardize: bool = False, drop_na: bool = True, verbose: bool = True, percentile: float = 0.85) -> dict[str, pd.DataFrame]

Given a factor of interest within a model, we reconstruct multicellular information networks by: 1) Extracting top genes associated with the factor in each view. 2) Enriching these gene sets in the pseudobulk data to get factor-associated scores. 3) Fitting pairwise linear models among the scores to infer directed networks.

The linear models can be controled with random effects, standardization, and NA handling options. The final output is a dictionary containing separate inferred networks for positive and negative associations.

Parameters:

Name	Type	Description	Default
test_model	AnnData	AnnData object containing factor scores and associated metadata.	required
sel_factor	str	Name of the factor to extract (e.g., "Factor1").	required
views	str, sequence of str, or None	Views to include when reconstructing the multicellular network. If None or "all", all views in the model are used. If a string or list of strings is provided, only those views are used.	None
random_effect	``array-like`` or None	Optional grouping vector defining random intercepts.	None
standardize	bool	If True, z-score features prior to model fitting.	False
drop_na	bool	If True, drop rows containing missing values.	True
verbose	bool	If True, warn when models are skipped.	True
percentile	float	Percentile threshold in [0, 1] for selecting top genes per view.	0.85

Returns:

Type	Description
dict[str, DataFrame]	Dictionary mapping interaction direction to inferred network tables.

mc_astra.down.multiview_to_wide(views: dict[str, AnnData], sample_key: str | None = None, *, prefix_features: bool = True, return_dataframe: bool = True) -> tuple[pd.DataFrame | np.ndarray, pd.Index, list[str]]

Build a dense wide matrix (samples × features) from a dict of per-view AnnData.

Uses the UNION of samples in first-seen order; rows missing in a view are zero-filled.

Parameters:

Name	Type	Description	Default
views	dict[str, AnnData]	Dictionary mapping view names to AnnData objects containing the data.	required
sample_key	str or None	Optional column in .obs to use as sample IDs. If None, uses .obs_names.	None
prefix_features	bool	If True, prefix feature names with view name (e.g., "view1:geneA"). Default is True.	True
return_dataframe	bool	If True, return a pandas DataFrame with sample IDs and feature names. If False, return a NumPy array with separate index and column lists.	True

Returns:

Name	Type	Description
wide	DataFrame or ndarray	Wide matrix containing all view features.
sample_index	Index	Union of sample identifiers. Returned only when return_dataframe is False.
colnames	list[str]	Wide-matrix feature names. Returned only when return_dataframe is False.

mc_astra.down.project_wide_to_factors(wide: pd.DataFrame | np.ndarray, W: np.ndarray, model_cols: Iterable[str], factor_names: Iterable[str] | None = None, rcond: float | None = None, center: bool = False, sample_annotations: pd.DataFrame | None = None) -> ad.AnnData

Project a samples × features matrix into latent factor space.

Parameters:

Name	Type	Description	Default
wide	DataFrame or ndarray	Matrix with shape (n_samples × n_features_in_wide).	required
W	ndarray	Loadings matrix with shape (n_factors × n_features_total).	required
model_cols	Iterable[str]	Feature names defining the column order of W.	required
factor_names	Iterable[str] or None	Names for output factors. If None, default names are used.	None
rcond	float or None	Cutoff for small singular values passed to np.linalg.pinv.	None
center	bool	If True, center columns before projection.	False
sample_annotations	DataFrame or None	Optional sample-level metadata to add to .obs.	None

Returns:

Type	Description
AnnData	AnnData object with projected factor scores in .X.

mc_astra.down.lr_usage(gene_loadings, resource, network_df, sel_factor, weight_col='cor_estimate', abs_cutoff=0.2, keep_negative=False, loading_type='positive', n_top=None)

Recover ligand-receptor interactions constrained by a coordination network and coherent loading signs.

This means that the ligand and receptor must both have loadings of the same sign (positive or negative) in their respective source and target cell types.

Parameters:

Name	Type	Description	Default
gene_loadings	dict[str, DataFrame]	Dictionary where keys are cell types and values are loading dataframes. Each dataframe is expected to have factors as rows and genes as columns.	required
resource	DataFrame	Ligand-receptor resource with at least columns: - ligand - receptor	required
network_df	DataFrame	Source-target network with at least columns: - target - predictor - weight_col	required
sel_factor	str	Factor to extract from each cell-type loading dataframe.	required
weight_col	str	Column in network_df used to filter allowed source-target pairs.	'cor_estimate'
abs_cutoff	float	Minimum absolute network weight.	0.2
keep_negative	bool	If False, only positive source-target network weights are kept.	False
loading_type	('positive', 'negative', 'both')	Which coherent ligand-receptor loading signs to retain.	"positive"
n_top	int or None	Number of top unique ligand-receptor interactions to retain. If None, all interactions are retained.	None

Returns:

Name	Type	Description
ligand_receptor_usage	DataFrame	Dataframe ready to pass to plot_lr_tiles.

mc_astra.down.calculate_pat_archs(amodel, sel_factors, plotting_factors, min_archs=2, max_archs=9, n_bootstraps=50)

Calculate archetypes for a given set of factors in an AnnData model using ParTIpy.

This function wraps all functions needed to evaluate and calculate archetypes.

Parameters:

Name	Type	Description	Default
amodel	AnnData	mc-ASTRA model output AnnData object containing factor scores in amodel.X.	required
sel_factors	list[str] or 'all'	List of factor names to use for archetype calculation. If "all", all factors in amodel.var_names are used.	required
plotting_factors	list[str]	List of length 2 with factor names to use for plotting archetypes. Must be a subset of sel_factors.	required
min_archs	int	Minimum number of archetypes to evaluate. Default is 2.	2
max_archs	int	Maximum number of archetypes to evaluate. Default is 9.	9
n_bootstraps	int	Number of bootstrap samples to use for variance estimation. Default is 50.	50

Returns:

Name	Type	Description
amodel	AnnData	Updated AnnData object with archetype results stored in amodel.obsm and amodel.uns.
sel_factors_ix	list[int]	List of integer indices corresponding to the selected factors in sel_factors.
plotting_factors_ix	list[int]	List of integer indices corresponding to the plotting factors in plotting_factors.

mc_astra.down.get_arch_pats_values(amodel, n_archetypes, sel_factors_ix)

Calculate the features that define each archetype for each view used in the model. This is calculated by multiplying the archetype locations in latent space by the loadings for the selected factors.

Parameters:

Name	Type	Description	Default
amodel	AnnData	mc-ASTRA model output AnnData object containing factor scores in amodel.X.	required
n_archetypes	float	Number of archetypes to use for the calculation. This should be the number of archetypes that you have selected based on the evaluation metrics.	required
sel_factors_ix	list[str]	List of integer indices corresponding to the selected factors in sel_factors. Output from calculate_pat_archs function.	required

Returns:

Name	Type	Description
arch_gex	DataFrame	DataFrame containing the reconstructed archetype feature values for each archetype. Rows are archetypes, columns are genes, and values are the reconstructed expression levels.

Utils

mc_astra.down.model_to_anndata(anndata_dict: dict[str, ad.AnnData], metadata: pd.DataFrame, model) -> ad.AnnData

Combine a factor model and multiple pseudobulk views into a single AnnData object.

Parameters:

Name	Type	Description	Default
anndata_dict	dict[str, AnnData]	Dictionary of pseudobulk AnnData views. Keys are used to name entries in .obsm.	required
metadata	DataFrame	Sample-level metadata indexed by sample ID.	required
model	object	Trained factor model exposing get_factors, get_r2, and get_weights methods.	required

Returns:

Type	Description
AnnData	AnnData object containing factor scores, metadata, gene loadings, and aligned pseudobulk matrices.

mc_astra.down.split_by_view(arch_gex: pd.DataFrame) -> dict[str, pd.DataFrame]

Split a wide DataFrame into view-specific DataFrames.

Column names are expected to follow the format "view:feature".

Parameters:

Name	Type	Description	Default
arch_gex	DataFrame	DataFrame with columns encoded as view:feature.	required

Returns:

Type	Description
dict[str, DataFrame]	Dictionary mapping view names to DataFrames containing only features from that view.

mc_astra.down.restore_anns_factor(factor_names, annotation_source, *, strict=True)

Replace long guided factor names with their original annotation names.

Assumes each annotation source maps to at most one factor name by suffix match.

Parameters:

Name	Type	Description	Default
factor_names	array - like	Iterable of current factor names, e.g. model.factor_names.	required
annotation_source	array - like	Series/list/array with original annotation names, e.g. annotation.source.	required
strict	bool	If True, raise an error when one annotation source matches multiple factors.	True

Returns:

Name	Type	Description
restored	ndarray	Factor names with matched long names replaced.

mc_astra.down.identify_outliers(amodel, threshold=10)

Identify outlier samples for each factor in an AnnData object based on standard deviation thresholding.

Parameters:

Name	Type	Description	Default
amodel	AnnData	mc-ASTRA model output AnnData object containing factor scores in amodel.X.	required
threshold	float	Number of standard deviations from the mean to consider a sample an outlier. Default is 10.	10

Returns:

Type	Description
dict[str, list[str]]	Dictionary providing outliers for each factor. Keys are factor names, and values are lists of sample IDs that are considered outliers for that factor.