ecotyper.discovery_steps¶

Cell state and ecotype discovery from purified (CIBERSORTx HiRes) or presorted profiles: state_discovery_*.R, ecotypes.R, ecotypes_assign_samples.R (bulk and presorted discovery wrappers).

Each R script becomes one function; values that R writes to a text file and the next script reads back are passed through _rt() (r_exact) so the port sees exactly the numbers R sees.

Functions

`assign_samples`(states, eco, cell_types, ...)	`ecotypes_assign_samples.R` (discovery cohort).
`discover_ecotypes`(initial, states, cell_types)	`ecotypes.R`.
`extract_features`(raw_input, cell_type[, ...])	`state_discovery_extract_features.R`.
`first_filter`(init, feats, annotation[, ...])	`state_discovery_first_filter.R` (`csx_filter=False`: `state_discovery_first_filter_scRNA.R`, without the filter on genes whose imputed values are mostly identical).
`get_fc_for_clusters`(data, variable)	`get_FC_for_clusters` (lib/misc.R).
`get_variable_genes`(log_data)	`get_variable_genes` (lib/misc.R): top 1000 genes by normalised dispersion within mean-expression bins, ordered by decreasing dispersion.
`initial_states`(merged, top_scaled, ...[, ...])	`state_discovery_initial_plots.R` (`gene_info=False`: the scRNA cross-correlation variant, which does not compute marker genes).
`log_transform`(X)	`log2(x)` if min >= 1, `log2(x + 1)` if min >= 0, else unchanged.
`nmf_input`(top_scaled[, r_exact])	`posneg(as.matrix(read.delim("expression_top_genes_scaled.txt")))`.
`rank_metrics`(fits, rank)	`state_discovery_combine_NMF_restarts.R` for one rank → (merged, metrics dict).
`run_nmf`(V, rank, restart[, exact, method])	`state_discovery_NMF.R`: `nmf(V, rank, "brunet", seed = 1234 + restart)`.
`scale_data`(data[, by])	`scale_data` (lib/misc.R): row z-scores within groups of samples.
`select_ranks`(rank_tables, max_n_clusters, ...)	`state_discovery_rank_selection.R`.

Classes

`Ecotypes`(mapping_all_states, binary, ...)
`Features`(cell_type, log_data, top_log2, ...)
`InitialStates`(cell_type, rank, W, H, ...)
`States`(cell_type, rank, first_filter_data, ...)

ecotyper.discovery_steps.log_transform(X)[source]¶

log2(x) if min >= 1, log2(x + 1) if min >= 0, else unchanged.

Parameters:: X (ndarray)
Return type:: ndarray

ecotyper.discovery_steps.get_variable_genes(log_data)[source]¶

get_variable_genes (lib/misc.R): top 1000 genes by normalised dispersion within mean-expression bins, ordered by decreasing dispersion.

Parameters:: log_data (DataFrame)
Return type:: DataFrame

ecotyper.discovery_steps.scale_data(data, by=None)[source]¶

scale_data (lib/misc.R): row z-scores within groups of samples.

Note: the R pipeline passes the name of the annotation column (a single string) as by, so every sample falls in the same group; pass a scalar to reproduce that, or one label per sample for true within-group scaling.

Parameters:: data (DataFrame)
Return type:: DataFrame

class ecotyper.discovery_steps.Features(cell_type: 'str', log_data: 'pd.DataFrame', top_log2: 'pd.DataFrame', top_scaled: 'pd.DataFrame', full_scaled: 'pd.DataFrame')[source]¶

Bases: object

Parameters:

cell_type (str)
log_data (DataFrame)
top_log2 (DataFrame)
top_scaled (DataFrame)
full_scaled (DataFrame)

cell_type: str¶

log_data: DataFrame¶

top_log2: DataFrame¶

top_scaled: DataFrame¶

full_scaled: DataFrame¶

ecotyper.discovery_steps.extract_features(raw_input, cell_type, annotation=None, scale_column=None, specific_genes=None)[source]¶

state_discovery_extract_features.R. raw_input: genes x samples (read.delim(..., row.names = 1)). Returns None when fewer than 50 genes.

Parameters:

raw_input (DataFrame)
cell_type (str)
annotation (DataFrame | None)
scale_column (str | None)
specific_genes (list | None)

Return type:

Features | None

ecotyper.discovery_steps.nmf_input(top_scaled, r_exact=True)[source]¶

posneg(as.matrix(read.delim("expression_top_genes_scaled.txt"))).

Parameters:: top_scaled (DataFrame)
Return type:: ndarray

ecotyper.discovery_steps.run_nmf(V, rank, restart, exact=True, method='brunet')[source]¶

state_discovery_NMF.R: nmf(V, rank, "brunet", seed = 1234 + restart).

method="cd": the alternative solver ecotyper.nmf.nmf_cd() (not R-equivalent).

Parameters:

V (ndarray)
rank (int)
restart (int)
exact (bool)
method (str)

Return type:

NMFFit

ecotyper.discovery_steps.rank_metrics(fits, rank)[source]¶

state_discovery_combine_NMF_restarts.R for one rank → (merged, metrics dict).

Parameters:

fits (list[NMFFit])
rank (int)

ecotyper.discovery_steps.select_ranks(rank_tables, max_n_clusters, min_cophenetic, r_exact=True)[source]¶

state_discovery_rank_selection.R. rank_tables: cell type → DataFrame with one row per rank (columns as rank_data.txt).

Parameters:

rank_tables (dict)
max_n_clusters (int)
min_cophenetic (float)

Return type:

DataFrame

ecotyper.discovery_steps.get_fc_for_clusters(data, variable)[source]¶

get_FC_for_clusters (lib/misc.R).

Parameters:: data (DataFrame)
Return type:: DataFrame

class ecotyper.discovery_steps.InitialStates(cell_type: 'str', rank: 'int', W: 'pd.DataFrame', H: 'pd.DataFrame', initial_abundances: 'pd.DataFrame', initial_assignment: 'pd.DataFrame', initial_gene_info: 'pd.DataFrame')[source]¶

Bases: object

Parameters:

cell_type (str)
rank (int)
W (DataFrame)
H (DataFrame)
initial_abundances (DataFrame)
initial_assignment (DataFrame)
initial_gene_info (DataFrame)

cell_type: str¶

rank: int¶

W: DataFrame¶

H: DataFrame¶

initial_abundances: DataFrame¶

initial_assignment: DataFrame¶

initial_gene_info: DataFrame¶

ecotyper.discovery_steps.initial_states(merged, top_scaled, cell_type, rank, r_exact=True, gene_info=True)[source]¶

state_discovery_initial_plots.R (gene_info=False: the scRNA cross-correlation variant, which does not compute marker genes).

Parameters:

top_scaled (DataFrame)
cell_type (str)
rank (int)
gene_info (bool)

Return type:

InitialStates

class ecotyper.discovery_steps.States(cell_type: 'str', rank: 'int', first_filter_data: 'pd.DataFrame', mapping: 'pd.DataFrame', state_abundances: 'pd.DataFrame', state_assignment: 'pd.DataFrame', heatmap_top_ann: 'pd.DataFrame', gene_info: 'pd.DataFrame', heatmap_data: 'pd.DataFrame', log: 'list' = <factory>)[source]¶

Bases: object

Parameters:

cell_type (str)
rank (int)
first_filter_data (DataFrame)
mapping (DataFrame)
state_abundances (DataFrame)
state_assignment (DataFrame)
heatmap_top_ann (DataFrame)
gene_info (DataFrame)
heatmap_data (DataFrame)
log (list)

cell_type: str¶

rank: int¶

first_filter_data: DataFrame¶

mapping: DataFrame¶

state_abundances: DataFrame¶

state_assignment: DataFrame¶

heatmap_top_ann: DataFrame¶

gene_info: DataFrame¶

heatmap_data: DataFrame¶

log: list¶

ecotyper.discovery_steps.first_filter(init, feats, annotation, r_exact=True, csx_filter=True)[source]¶

state_discovery_first_filter.R (csx_filter=False: state_discovery_first_filter_scRNA.R, without the filter on genes whose imputed values are mostly identical).

Parameters:

init (InitialStates)
feats (Features)
annotation (DataFrame | None)
csx_filter (bool)

Return type:

States

class ecotyper.discovery_steps.Ecotypes(mapping_all_states: 'pd.DataFrame', binary: 'pd.DataFrame', jaccard: 'pd.DataFrame', silhouette_initial: 'float', initial_ecotypes: 'pd.DataFrame', ecotypes: 'pd.DataFrame', silhouette: 'float', n_clusters: 'int')[source]¶