ecotyper.workflows

High-level workflows mirroring the R wrapper scripts.

The *_frame functions take pandas objects, the *_files functions take the R wrappers’ input files and write the R output layout, and the unsuffixed functions take anndata.AnnData and store results in it.

AnnData conventions (key = "ecotyper" by default):

adata.obs[f"{key}_state_{cell_type}"]

assigned cell state (S01…; NaN if the sample’s dominant initial state was filtered out during discovery);

adata.obsm[f"{key}_abundance_{cell_type}"]

cell state abundances (samples x states, columns S01…);

adata.obs[f"{key}_ecotype"], adata.obs[f"{key}_max_ecotype"], adata.obs[f"{key}_ecotype_q"]

ecotype assignment (Unassigned if not significant), most abundant ecotype and its BH-adjusted p-value (bulk/Visium);

adata.obsm[f"{key}_ecotype_abundance"]

ecotype abundances (samples x ecotypes);

adata.uns[key]

run parameters, number of NMF iterations per cell type, and the full per-step result objects under "results".

R starts each per-cell-type script in a fresh process. The R reference runs seed every process with set.seed(seed) (R itself leaves NMFpredict unseeded); the port reseeds RRandom(seed) for every cell type the same way.

Functions

discover_files(input_dir, annotation_path, ...)

File-based discovery from a folder of per-cell-type profiles (CSx HiRes output or presorted profiles) and a sample annotation file.

discover_from_profiles(profiles[, ...])

Cell state + ecotype discovery from per-cell-type expression profiles (EcoTyper_discovery_bulk.R steps 3–6 and 8 with CSx HiRes profiles as input, or EcoTyper_discovery_presorted.R with "no filter").

discover_scrna(adata, *[, layer])

scRNA-seq discovery on AnnData (cells x genes, raw-scale expression; obs with CellType and Sample).

discover_scrna_frame(expr, annotation, *[, ...])

EcoTyper_discovery_scRNA.R on a genes x cells matrix (fread semantics) and a cell annotation with ID, CellType and Sample.

ecotype_abundances_long(eco)

melt(ecotype_data, id.vars = c("ID", "X", "Y", "Sample", "Malignant")).

read_profiles(input_dir[, classes])

Per-cell-type profiles <input_dir>/<cell type>.txt (read.delim(row.names = 1)).

read_visium(matrix_dir)

spatial_load_visium_data.R: 10x Visium folder → (genes x spots counts, spot annotation with ID, X (array row), Y (array col)).

recover_bulk(adata, model, *[, ...])

Recover cell states and ecotypes in bulk samples (adata: samples x genes).

recover_bulk_files(matrix, annotation, ...)

File-based equivalent of Rscript EcoTyper_recovery_bulk.R -m matrix -a annotation.

recover_bulk_frame(expr, model[, ...])

Bulk recovery on a genes x samples DataFrame (values as read by R).

recover_scrna(adata, model, *[, ...])

Recover cell states in single cells (adata: cells x genes, raw-scale expression; obs must have CellType and, for ecotypes, Sample).

recover_scrna_files(matrix, annotation, ...)

File-based equivalent of Rscript EcoTyper_recovery_scRNA.R.

recover_scrna_frame(expr_all, annotation, ...)

scRNA-seq recovery on a genes x cells DataFrame (fread semantics) and a cell annotation with ID, CellType and optionally Sample.

recover_visium_files(visium_dir, ...[, ...])

File-based equivalent of Rscript EcoTyper_recovery_visium.R -c config.yml with precomputed fractions.

recover_visium_frame(expr, spots, model, ...)

Returns (state_results, state_abundances_long, state_abundances, ecotype_abundances).

write_discovery(res, out_dir, name, fractions)

Write the R layout <out_dir>/EcoTyper/<name>/<fractions>/....

write_discovery_scrna(res, out_dir, name[, ...])

Write the R layout of a scRNA discovery run.

Classes

DiscoveryResult

Results of a discovery run (attribute access to the dict keys).
ecotyper.workflows.recover_bulk_frame(expr, model, annotation=None, *, seed=42, n_jobs=1, r_exact=True, kind='bulk', exact=True)[source]

Bulk recovery on a genes x samples DataFrame (values as read by R).

Returns (state_results, ecotype_result). exact=False is the fast mode (BLAS NMF updates, no R text round trips; see the module docstring).

Parameters:
ecotyper.workflows.recover_bulk(adata, model, *, discovery_root=None, layer=None, seed=42, n_jobs=1, r_exact=True, key='ecotyper', exact=True)[source]

Recover cell states and ecotypes in bulk samples (adata: samples x genes).

model is an EcoTyperModel, a path to a model folder, or a discovery name ("Carcinoma", "Lymphoma"…) with discovery_root pointing to the EcoTyper folder.

Parameters:
ecotyper.workflows.recover_bulk_files(matrix, annotation, model, out_dir, *, discovery_root=None, recovery_name=None, seed=42, n_jobs=1, r_exact=True, exact=True)[source]

File-based equivalent of Rscript EcoTyper_recovery_bulk.R -m matrix -a annotation.

Writes the intermediate EcoTyper/<discovery>/<fractions>/{Cell_States,Ecotypes}/recovery tree under out_dir/EcoTyper and the user-facing folder out_dir/RecoveryOutput/<recovery_name>.

Parameters:
ecotyper.workflows.recover_scrna_frame(expr_all, annotation, model, *, seed=42, subsample=-1, n_jobs=1, exact=True)[source]

scRNA-seq recovery on a genes x cells DataFrame (fread semantics) and a cell annotation with ID, CellType and optionally Sample.

subsample caps the number of cells per cell type (R’s -s; values below 50, e.g. the default -1, keep all cells). Returns (state_results, ecotype_result); ecotype_result is None without a Sample column.

Parameters:
ecotyper.workflows.recover_scrna(adata, model, *, discovery_root=None, layer=None, seed=42, subsample=-1, n_jobs=1, key='ecotyper', exact=True)[source]

Recover cell states in single cells (adata: cells x genes, raw-scale expression; obs must have CellType and, for ecotypes, Sample).

Ecotype abundances are per sample, returned (not stored in adata).

Parameters:
ecotyper.workflows.recover_scrna_files(matrix, annotation, model, out_dir, *, discovery_root=None, recovery_name=None, seed=42, subsample=-1, n_jobs=1, exact=True)[source]

File-based equivalent of Rscript EcoTyper_recovery_scRNA.R.

Parameters:
ecotyper.workflows.read_visium(matrix_dir)[source]

spatial_load_visium_data.R: 10x Visium folder → (genes x spots counts, spot annotation with ID, X (array row), Y (array col)).

ecotyper.workflows.recover_visium_frame(expr, spots, model, fractions, *, sample_name, malignant_cell='Epithelial.cells', seed=42, n_jobs=1, r_exact=True, exact=True)[source]

Returns (state_results, state_abundances_long, state_abundances, ecotype_abundances).

Parameters:
ecotyper.workflows.recover_visium_files(visium_dir, fractions_path, model, out_dir, *, recovery_name, discovery_root=None, malignant_cell='Epithelial.cells', seed=42, n_jobs=1, r_exact=True, exact=True)[source]

File-based equivalent of Rscript EcoTyper_recovery_visium.R -c config.yml with precomputed fractions.

Parameters:
ecotyper.workflows.ecotype_abundances_long(eco)[source]

melt(ecotype_data, id.vars = c("ID", "X", "Y", "Sample", "Malignant")).

Parameters:

eco (DataFrame)

Return type:

DataFrame

class ecotyper.workflows.DiscoveryResult[source]

Bases: dict

Results of a discovery run (attribute access to the dict keys).

ecotyper.workflows.discover_from_profiles(profiles, annotation=None, *, scale_column=None, max_states=20, restarts=5, cophenetic_cutoff=0.95, min_states=3, n_jobs=1, r_exact=True, verbose=True, exact=True, nmf_method='brunet')[source]

Cell state + ecotype discovery from per-cell-type expression profiles (EcoTyper_discovery_bulk.R steps 3–6 and 8 with CSx HiRes profiles as input, or EcoTyper_discovery_presorted.R with “no filter”).

profiles: cell type → genes x samples DataFrame (values as read by read.delim(row.names = 1)), in the order of classes.txt. exact=False: fast mode; nmf_method="cd": alternative NMF solver (see ecotyper.nmf.nmf_cd()).

Parameters:
ecotyper.workflows.read_profiles(input_dir, classes=None)[source]

Per-cell-type profiles <input_dir>/<cell type>.txt (read.delim(row.names = 1)). classes: cell type order (default: list.files order).

Return type:

dict

ecotyper.workflows.write_discovery(res, out_dir, name, fractions)[source]

Write the R layout <out_dir>/EcoTyper/<name>/<fractions>/....

Parameters:
Return type:

Path

ecotyper.workflows.discover_files(input_dir, annotation_path, out_dir, *, name, fractions='All_genes', scale_column=None, max_states=20, restarts=5, cophenetic_cutoff=0.95, min_states=3, n_jobs=1, r_exact=True, exact=True, nmf_method='brunet')[source]

File-based discovery from a folder of per-cell-type profiles (CSx HiRes output or presorted profiles) and a sample annotation file.

Parameters:
ecotyper.workflows.discover_scrna_frame(expr, annotation, *, filter_genes='cell type specific', scale_column=None, max_states=20, restarts=5, cophenetic_cutoff=0.975, p_value_cutoff=1.0, min_states=3, n_jobs=1, r_exact=True, verbose=True, exact=True, nmf_method='brunet')[source]

EcoTyper_discovery_scRNA.R on a genes x cells matrix (fread semantics) and a cell annotation with ID, CellType and Sample. exact=False: fast mode.

Parameters:
ecotyper.workflows.discover_scrna(adata, *, layer=None, **kwargs)[source]

scRNA-seq discovery on AnnData (cells x genes, raw-scale expression; obs with CellType and Sample). Results are stored in adata.obs["ecotyper_state_<cell type>"] (per cell) and returned.

ecotyper.workflows.write_discovery_scrna(res, out_dir, name, fractions='Cell_type_specific_genes', write_large=False)[source]

Write the R layout of a scRNA discovery run. The very large expression_full_matrix_* files are only written with write_large.

Parameters:
Return type:

Path