Class

Preprocess

class dynamo.pp.Preprocessor(collapse_species_adata_function=<function collapse_species_adata>, convert_gene_name_function=<function convert2symbol>, filter_cells_by_outliers_function=<function filter_cells_by_outliers>, filter_cells_by_outliers_kwargs={}, filter_genes_by_outliers_function=<function filter_genes_by_outliers>, filter_genes_by_outliers_kwargs={}, normalize_by_cells_function=<function normalize>, normalize_by_cells_function_kwargs={}, size_factor_function=<function calc_sz_factor>, size_factor_kwargs={}, select_genes_function=<function select_genes_monocle>, select_genes_kwargs={}, normalize_selected_genes_function=None, normalize_selected_genes_kwargs={}, norm_method=<function log1p>, norm_method_kwargs={}, pca_function=<function pca>, pca_kwargs={}, gene_append_list=[], gene_exclude_list=[], force_gene_list=None, sctransform_kwargs={}, regress_out_kwargs={}, cell_cycle_score_enable=False, cell_cycle_score_kwargs={})[source]

Preprocessor constructor.

The default preprocess functions are those of monocle recipe by default. You can pass your own Callable objects (functions) to this constructor directly, which wil be used in the preprocess steps later. These functions parameters are saved into Preprocessor instances. You can set these attributes directly to your own implementation.

Parameters:
  • collapse_species_adata_function (Callable) – function for collapsing the species data. Defaults to collapse_species_adata.

  • convert_gene_name_function (Callable) – transform gene names, by default convert2symbol, which transforms unofficial gene names to official gene names. Defaults to convert2symbol.

  • filter_cells_by_outliers_function (Callable) – filter cells by thresholds. Defaults to monocle_filter_cells_by_outliers.

  • filter_cells_by_outliers_kwargs (Dict[str, Any]) – arguments that will be passed to filter_cells_by_outliers. Defaults to {}.

  • filter_genes_by_outliers_function (Callable) – filter genes by thresholds. Defaults to monocle_filter_genes_by_outliers.

  • filter_genes_by_outliers_kwargs (Dict[str, Any]) – arguments that will be passed to filter_genes_by_outliers. Defaults to {}.

  • normalize_by_cells_function (Callable) – function for performing cell-wise normalization. Defaults to normalize_cell_expr_by_size_factors.

  • normalize_by_cells_function_kwargs (Dict[str, Any]) – arguments that will be passed to normalize_by_cells_function. Defaults to {}.

  • select_genes_function (Callable) – function for selecting gene features. Defaults to select_genes_monocle.

  • select_genes_kwargs (Dict[str, Any]) – arguments that will be passed to select_genes. Defaults to {}.

  • normalize_selected_genes_function (Optional[Callable]) – function for normalize selected genes. Defaults to None.

  • normalize_selected_genes_kwargs (Dict[str, Any]) – arguments that will be passed to normalize_selected_genes. Defaults to {}.

  • norm_method (Callable) – whether to use a method to normalize layers in adata. Defaults to True.

  • norm_method_kwargs (Dict[str, Any]) – arguments passed to norm_method. Defaults to {}.

  • pca_function (Callable) – function to perform pca. Defaults to pca in utils.py.

  • pca_kwargs (Dict[str, Any]) – arguments that will be passed pca. Defaults to {}.

  • gene_append_list (List[str]) – ensure that a list of genes show up in selected genes across all the recipe pipeline. Defaults to [].

  • gene_exclude_list (List[str]) – exclude a list of genes across all the recipe pipeline. Defaults to [].

  • force_gene_list (Optional[List[str]]) – use this gene list as selected genes across all the recipe pipeline. Defaults to None.

  • sctransform_kwargs (Dict[str, Any]) – arguments passed into sctransform function. Defaults to {}.

  • regress_out_kwargs (Dict[List[str], Any]) – arguments passed into regress_out function. Defaults to {}.

add_experiment_info(adata, tkey=None, experiment_type=None)[source]

Infer the experiment type and experiment layers stored in the AnnData object and record the info in unstructured metadata (.uns).

Parameters:
  • adata (AnnData) – an AnnData object.

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type. If set to None, the experiment type would be inferred from the data.

Raises:

ValueError – the tkey is invalid.

Return type:

None

standardize_adata(adata, tkey, experiment_type)[source]

Process the AnnData object to make it meet the standards of dynamo.

The index of the observations would be ensured to be unique. The layers with sparse matrix would be converted to compressed csr_matrix. DKM.allowed_layer_raw_names() will be used to define only_splicing, only_labeling and splicing_labeling keys. The genes would be renamed to their official name.

Parameters:
  • adata (AnnData) – an AnnData object.

  • tkey (str) – the key for time information (labeling time period for the cells) in .obs.

  • experiment_type (str) – the experiment type.

Return type:

None

preprocess_adata_seurat_wo_pca(adata, tkey=None, experiment_type=None)[source]

Preprocess the anndata object according to standard preprocessing in Seurat recipe without PCA. This can be used to test different dimension reduction methods.

Return type:

None

config_monocle_recipe(adata, n_top_genes=2000)[source]

Automatically configure the preprocessor for monocle recipe.

Parameters:
  • adata (AnnData) – an AnnData object.

  • n_top_genes (int) – Number of top feature genes to select in the preprocessing step. Defaults to 2000.

Return type:

None

preprocess_adata_monocle(adata, tkey=None, experiment_type=None)[source]

Preprocess the AnnData object based on Monocle style preprocessing recipe.

Parameters:
  • adata (AnnData) – an AnnData object.

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data.

Return type:

None

config_seurat_recipe(adata)[source]

Automatically configure the preprocessor for using the seurat style recipe.

Parameters:

adata (AnnData) – an AnnData object.

Return type:

None

preprocess_adata_seurat(adata, tkey=None, experiment_type=None)[source]

The preprocess pipeline in Seurat based on dispersion, implemented by dynamo authors.

Stuart and Butler et al. Comprehensive Integration of Single-Cell Data. Cell (2019) Butler et al. Integrating single-cell transcriptomic data across different conditions, technologies, and species. Nat Biotechnol

Parameters:
  • adata (AnnData) – an AnnData object

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data.

Return type:

None

config_sctransform_recipe(adata)[source]

Automatically configure the preprocessor for using the sctransform style recipe.

Parameters:

adata (AnnData) – an AnnData object.

Return type:

None

preprocess_adata_sctransform(adata, tkey=None, experiment_type=None)[source]

Python implementation of https://github.com/satijalab/sctransform.

Hao and Hao et al. Integrated analysis of multimodal single-cell data. Cell (2021)

Parameters:
  • adata (AnnData) – an AnnData object

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data. Defaults to None.

Return type:

None

config_pearson_residuals_recipe(adata)[source]

Automatically configure the preprocessor for using the Pearson residuals style recipe.

Parameters:

adata (AnnData) – an AnnData object.

Return type:

None

preprocess_adata_pearson_residuals(adata, tkey=None, experiment_type=None)[source]

A pipeline proposed in Pearson residuals (Lause, Berens & Kobak, 2021).

Lause, J., Berens, P. & Kobak, D. Analytic Pearson residuals for normalization of single-cell RNA-seq UMI data. Genome Biol 22, 258 (2021). https://doi.org/10.1186/s13059-021-02451-7

Parameters:
  • adata (AnnData) – an AnnData object

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data. Defaults to None.

Return type:

None

config_monocle_pearson_residuals_recipe(adata)[source]

Automatically configure the preprocessor for using the Monocle-Pearson-residuals style recipe.

Useful when you want to use Pearson residual to obtain feature genes and perform PCA but also using the standard size-factor normalization and log1p analyses to normalize data for RNA velocity and vector field analyses.

Parameters:

adata (AnnData) – an AnnData object.

Return type:

None

preprocess_adata_monocle_pearson_residuals(adata, tkey=None, experiment_type=None)[source]

A combined pipeline of monocle and pearson_residuals.

Results after running pearson_residuals can contain negative values, an undesired feature for later RNA velocity analysis. This function combine pearson_residual and monocle recipes so that it uses Pearson residual to obtain feature genes and perform PCA but also uses monocle recipe to generate X_spliced, X_unspliced, X_new, X_total or other data values for RNA velocity and downstream vector field analyses.

Parameters:
  • adata (AnnData) – an AnnData object

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data.

Return type:

None

preprocess_adata(adata, recipe='monocle', tkey=None, experiment_type=None)[source]

Preprocess the AnnData object with the recipe specified.

Parameters:
  • adata (AnnData) – An AnnData object.

  • recipe (Literal['monocle', 'seurat', 'sctransform', 'pearson_residuals', 'monocle_pearson_residuals']) – The recipe used to preprocess the data. Defaults to “monocle”.

  • tkey (Optional[str]) – the key for time information (labeling time period for the cells) in .obs. Defaults to None.

  • experiment_type (Optional[str]) – the experiment type of the data. If not provided, would be inferred from the data.

Raises:

NotImplementedError – the recipe is invalid.

Return type:

None

Estimation

Conventional scRNA-seq (est.csc)

class dynamo.est.csc.ss_estimation(U=None, Ul=None, S=None, Sl=None, P=None, US=None, S2=None, conn=None, t=None, ind_for_proteins=None, model='stochastic', est_method='gmm', experiment_type='deg', assumption_mRNA=None, assumption_protein='ss', concat_data=True, cores=1, **kwargs)

The class that estimates parameters with input data.

Parameters:
  • U (ndarray or sparse csr_matrix) – A matrix of unspliced mRNA count.

  • Ul (ndarray or sparse csr_matrix) – A matrix of unspliced, labeled mRNA count.

  • S (ndarray or sparse csr_matrix) – A matrix of spliced mRNA count.

  • Sl (ndarray or sparse csr_matrix) – A matrix of spliced, labeled mRNA count.

  • P (ndarray or sparse csr_matrix) – A matrix of protein count.

  • US (ndarray or sparse csr_matrix) – A matrix of second moment of unspliced/spliced gene expression count for conventional or NTR velocity.

  • S2 (ndarray or sparse csr_matrix) – A matrix of second moment of spliced gene expression count for conventional or NTR velocity.

  • conn (ndarray or sparse csr_matrix) – The connectivity matrix that can be used to calculate first /second moment of the data.

  • t (ss_estimation) – A vector of time points.

  • ind_for_proteins (ndarray) – A 1-D vector of the indices in the U, Ul, S, Sl layers that corresponds to the row name in the protein or X_protein key of .obsm attribute.

  • experiment_type (str) – labelling experiment type. Available options are: (1) ‘deg’: degradation experiment; (2) ‘kin’: synthesis experiment; (3) ‘one-shot’: one-shot kinetic experiment; (4) ‘mix_std_stm’: a mixed steady state and stimulation labeling experiment.

  • assumption_mRNA (str) – Parameter estimation assumption for mRNA. Available options are: (1) ‘ss’: pseudo steady state; (2) None: kinetic data with no assumption.

  • assumption_protein (str) – Parameter estimation assumption for protein. Available options are: (1) ‘ss’: pseudo steady state;

  • concat_data (bool (default: True)) – Whether to concatenate data

  • cores (int (default: 1)) – Number of cores to run the estimation. If cores is set to be > 1, multiprocessing will be used to parallel the parameter estimation.

Returns:

  • t (ss_estimation) – A vector of time points.

  • data (dict) – A dictionary with uu, ul, su, sl, p as its keys.

  • extyp (str) – labelling experiment type.

  • asspt_mRNA (str) – Parameter estimation assumption for mRNA.

  • asspt_prot (str) – Parameter estimation assumption for protein.

  • parameters (dict) –

    A dictionary with alpha, beta, gamma, eta, delta as its keys.

    alpha: transcription rate beta: RNA splicing rate gamma: spliced mRNA degradation rate eta: translation rate delta: protein degradation rate

fit(intercept=False, perc_left=None, perc_right=5, clusters=None, one_shot_method='combined')

Fit the input data to estimate all or a subset of the parameters

Parameters:
  • intercept (bool) – If using steady state assumption for fitting, then: True – the linear regression is performed with an unfixed intercept; False – the linear regression is performed with a fixed zero intercept.

  • perc_left (float (default: 5)) – The percentage of samples included in the linear regression in the left tail. If set to None, then all the samples are included.

  • perc_right (float (default: 5)) – The percentage of samples included in the linear regression in the right tail. If set to None, then all the samples are included.

  • clusters (list) – A list of n clusters, each element is a list of indices of the samples which belong to this cluster.

fit_gamma_steady_state(u, s, intercept=True, perc_left=None, perc_right=5, normalize=True)

Estimate gamma using linear regression based on the steady state assumption.

Parameters:
  • u (ndarray or sparse csr_matrix) – A matrix of unspliced mRNA counts. Dimension: genes x cells.

  • s (ndarray or sparse csr_matrix) – A matrix of spliced mRNA counts. Dimension: genes x cells.

  • intercept (bool) – If using steady state assumption for fitting, then: True – the linear regression is performed with an unfixed intercept; False – the linear regresssion is performed with a fixed zero intercept.

  • perc_left (float) – The percentage of samples included in the linear regression in the left tail. If set to None, then all the left samples are excluded.

  • perc_right (float) – The percentage of samples included in the linear regression in the right tail. If set to None, then all the samples are included.

  • normalize (bool) – Whether to first normalize the data.

Returns:

k: float

The slope of the linear regression model, which is gamma under the steady state assumption.

b: float

The intercept of the linear regression model.

r2: float

Coefficient of determination or r square for the extreme data points.

r2: float

Coefficient of determination or r square for the extreme data points.

all_r2: float

Coefficient of determination or r square for all data points.

fit_gamma_stochastic(est_method, u, s, us, ss, perc_left=None, perc_right=5, normalize=True)

Estimate gamma using GMM (generalized method of moments) or negbin distrubtion based on the steady state assumption.

Parameters:
  • est_method (str {gmm, negbin} The estimation method to be used when using the stochastic model.) –

    • Available options when the model is ‘ss’ include:

    (2) ‘gmm’: The new generalized methods of moments from us that is based on master equations, similar to the “moment” model in the excellent scVelo package; (3) ‘negbin’: The new method from us that models steady state RNA expression as a negative binomial distribution, also built upon on master equations. Note that all those methods require using extreme data points (except negbin, which use all data points) for estimation. Extreme data points are defined as the data from cells whose expression of unspliced / spliced or new / total RNA, etc. are in the top or bottom, 5%, for example. linear_regression only considers the mean of RNA species (based on the deterministic ordinary different equations) while moment based methods (gmm, negbin) considers both first moment (mean) and second moment (uncentered variance) of RNA species (based on the stochastic master equations). The above method are all (generalized) linear regression based method. In order to return estimated parameters (including RNA half-life), it additionally returns R-squared (either just for extreme data points or all data points) as well as the log-likelihood of the fitting, which will be used for transition matrix and velocity embedding. All est_method uses least square to estimate optimal parameters with latin cubic sampler for initial sampling.

  • u (ndarray or sparse csr_matrix) – A matrix of unspliced mRNA counts. Dimension: genes x cells.

  • s (ndarray or sparse csr_matrix) – A matrix of spliced mRNA counts. Dimension: genes x cells.

  • us (ndarray or sparse csr_matrix) – A matrix of unspliced mRNA counts. Dimension: genes x cells.

  • ss (ndarray or sparse csr_matrix) – A matrix of spliced mRNA counts. Dimension: genes x cells.

  • perc_left (float) – The percentage of samples included in the linear regression in the left tail. If set to None, then all the left samples are excluded.

  • perc_right (float) – The percentage of samples included in the linear regression in the right tail. If set to None, then all the samples are included.

  • normalize (bool) – Whether to first normalize the

Returns:

k: float

The slope of the linear regression model, which is gamma under the steady state assumption.

b: float

The intercept of the linear regression model.

r2: float

Coefficient of determination or r square for the extreme data points.

r2: float

Coefficient of determination or r square for the extreme data points.

all_r2: float

Coefficient of determination or r square for all data points.

fit_beta_gamma_lsq(t, U, S)

Estimate beta and gamma with the degradation data using the least squares method.

Parameters:
  • t (ndarray) – A vector of time points.

  • U (ndarray) – A matrix of unspliced mRNA counts. Dimension: genes x cells.

  • S (ndarray) – A matrix of spliced mRNA counts. Dimension: genes x cells.

Returns:

beta: ndarray

A vector of betas for all the genes.

gamma: ndarray

A vector of gammas for all the genes.

u0: float

Initial value of u.

s0: float

Initial value of s.

fit_gamma_nosplicing_lsq(t, L)

Estimate gamma with the degradation data using the least squares method when there is no splicing data.

Parameters:
  • t (ndarray) – A vector of time points.

  • L (ndarray) – A matrix of labeled mRNA counts. Dimension: genes x cells.

Returns:

gamma: ndarray

A vector of gammas for all the genes.

l0: float

The estimated value for the initial spliced, labeled mRNA count.

solve_alpha_mix_std_stm(t, ul, beta, clusters=None, alpha_time_dependent=True)

Estimate the steady state transcription rate and analytically calculate the stimulation transcription rate given beta and steady state alpha for a mixed steady state and stimulation labeling experiment.

This approach assumes the same constant beta or gamma for both steady state or stimulation period.

Parameters:
  • t (list or numpy.ndarray) – Time period for stimulation state labeling for each cell.

  • ul – A vector of labeled RNA amount in each cell.

  • beta (numpy.ndarray) – A list of splicing rate for genes.

  • clusters (list) – A list of n clusters, each element is a list of indices of the samples which belong to this cluster.

  • alpha_time_dependent (bool) – Whether or not to model the simulation alpha rate as a time dependent variable.

Returns:

alpha_std, alpha_stm: numpy.ndarray, numpy.ndarray

The constant steady state transcription rate (alpha_std) or time-dependent or time-independent (determined by alpha_time_dependent) transcription rate (alpha_stm)

fit_alpha_oneshot(t, U, beta, clusters=None)

Estimate alpha with the one-shot data.

Parameters:
  • t (float) – labelling duration.

  • U (ndarray) – A matrix of unspliced mRNA counts. Dimension: genes x cells.

  • beta (ndarray) – A vector of betas for all the genes.

  • clusters (list) – A list of n clusters, each element is a list of indices of the samples which belong to this cluster.

Returns:

alpha: ndarray

A numpy array with the dimension of n_genes x clusters.

concatenate_data()

Concatenate available data into a single matrix.

See “concat_time_series_matrices” for details.

get_n_genes(key=None, data=None)

Get the number of genes.

set_parameter(name, value)

Set the value for the specified parameter.

Parameters:
  • name (string) – The name of the parameter. E.g. ‘beta’.

  • value (ndarray) – A vector of values for the parameter to be set to.

get_exist_data_names()

Get the names of all the data that are not ‘None’.

dynamo.est.csc.velocity

alias of <module ‘dynamo.estimation.csc.velocity’ from ‘/home/docs/checkouts/readthedocs.org/user_builds/dynamo-release/checkouts/latest/dynamo/estimation/csc/velocity.py’>

Time-resolved metabolic labeling based scRNA-seq (est.tsc)

Base class: a general estimation framework

class dynamo.est.tsc.kinetic_estimation(param_ranges, x0_ranges, simulator)

A general parameter estimation framework for all types of time-seris data.

Initialize the kinetic_estimation class.

Parameters:
  • param_ranges (ndarray) – A n-by-2 numpy array containing the lower and upper ranges of n parameters (and initial conditions if not fixed).

  • x0_ranges (ndarray) – Lower and upper bounds for initial conditions for the integrators. To fix a parameter, set its lower and upper bounds to the same value.

  • simulator (LinearODE) – An instance of python class which solves ODEs. It should have properties ‘t’ (k time points, 1d numpy array), ‘x0’ (initial conditions for m species, 1d numpy array), and ‘x’ (solution, k-by-m array), as well as two functions: integrate (numerical integration), solve (analytical method).

Returns:

An instance of the kinetic_estimation class.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

Deterministic models via analytical solution of ODEs

class dynamo.est.tsc.Estimation_DeterministicDeg(beta=None, gamma=None, x0=None)

An estimation class for degradation (with splicing) experiments. Order of species: <unspliced>, <spliced>

Initialize the Estimation_DeterministicDeg object.

Parameters:
Returns:

An instance of the Estimation_DeterministicDeg class.

auto_fit(time, x_data, **kwargs)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (ndarray) – A matrix representing RNA data.

  • kwargs – The additional keyword arguments.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

calc_half_life(key)

Calculate half-life of a parameter.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The half-life value.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

get_param(key)

Get the estimated parameter value by key.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The estimated parameter value.

guestimate_gamma(x_data, time)

Roughly estimate initial conditions for parameter estimation.

Parameters:
  • x_data (ndarray) – A matrix representing RNA data.

  • time (ndarray) – A matrix of time information.

Return type:

ndarray

Returns:

Estimated gamma.

guestimate_init_cond(x_data)

Roughly estimate initial conditions for parameter estimation.

Parameters:

x_data (ndarray) – A matrix representing RNA data.

Return type:

ndarray

Returns:

Estimated initial conditions.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_DeterministicDegNosp(gamma=None, x0=None)

An estimation class for degradation (without splicing) experiments.

Initialize the Estimation_DeterministicDegNosp object.

Parameters:
Returns:

An instance of the Estimation_DeterministicDegNosp class.

auto_fit(time, x_data, sample_method='lhs', method=None, normalize=False)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (ndarray) – A matrix representing RNA data.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize the data.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

calc_half_life(key)

Calculate half-life of a parameter.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The half-life value.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

get_param(key)

Get the estimated parameter value by key.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The estimated parameter value.

guestimate_gamma(x_data, time)

Roughly estimate initial conditions for parameter estimation.

Parameters:
  • x_data (ndarray) – A matrix representing RNA data.

  • time (ndarray) – A matrix of time information.

Return type:

ndarray

Returns:

Estimated gamma.

guestimate_init_cond(x_data)

Roughly estimate initial conditions for parameter estimation.

Parameters:

x_data (ndarray) – A matrix representing RNA data.

Return type:

ndarray

Returns:

Estimated initial conditions.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_DeterministicKinNosp(alpha, gamma, x0=0)

An estimation class for kinetics (without splicing) experiments with the deterministic model. Order of species: <unspliced>, <spliced>

Initialize the Estimation_DeterministicKinNosp object.

Parameters:
Returns:

An instance of the Estimation_DeterministicKinNosp class.

get_alpha()

Get the transcription rate.

Return type:

ndarray

Returns:

The transcription rate.

get_gamma()

Get the degradation rate.

Return type:

ndarray

Returns:

The degradation rate.

calc_half_life(key)

Calculate the half life.

Return type:

ndarray

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_DeterministicKin(alpha, beta, gamma, x0=array([0., 0.]))

An estimation class for kinetics experiments with the deterministic model. Order of species: <unspliced>, <spliced>

Initialize the Estimation_DeterministicKin object.

Parameters:
Returns:

An instance of the Estimation_DeterministicKin class.

get_alpha()

Get the transcription rate.

Return type:

ndarray

Returns:

The transcription rate.

get_beta()

Get the splicing rate.

Return type:

ndarray

Returns:

The splicing rate.

get_gamma()

Get the degradation rate.

Return type:

ndarray

Returns:

The degradation rate.

calc_spl_half_life()

Calculate the half life of splicing.

Return type:

ndarray

Returns:

The half life of splicing.

calc_deg_half_life()

Calculate the half life of degradation.

Return type:

ndarray

Returns:

The half life of degradation.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

Stochastic models via matrix form of moment equations

class dynamo.est.tsc.Estimation_MomentDeg(beta=None, gamma=None, x0=None, include_cov=True)

An estimation class for degradation (with splicing) experiments. Order of species: <unspliced>, <spliced>, <uu>, <ss>, <us> Order of parameters: beta, gamma

Initialize the Estimation_MomentDeg object.

Parameters:
Returns:

An instance of the Estimation_MomentDeg class.

extract_data_from_simulator()

Get corresponding data from the LinearODE class.

Return type:

ndarray

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

auto_fit(time, x_data, **kwargs)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (ndarray) – A matrix representing RNA data.

  • kwargs – The additional keyword arguments.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

calc_half_life(key)

Calculate half-life of a parameter.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The half-life value.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

get_param(key)

Get the estimated parameter value by key.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The estimated parameter value.

guestimate_gamma(x_data, time)

Roughly estimate initial conditions for parameter estimation.

Parameters:
  • x_data (ndarray) – A matrix representing RNA data.

  • time (ndarray) – A matrix of time information.

Return type:

ndarray

Returns:

Estimated gamma.

guestimate_init_cond(x_data)

Roughly estimate initial conditions for parameter estimation.

Parameters:

x_data (ndarray) – A matrix representing RNA data.

Return type:

ndarray

Returns:

Estimated initial conditions.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_MomentDegNosp(gamma=None, x0=None)

An estimation class for degradation (without splicing) experiments. Order of species: <r>, <rr>.

Initialize the Estimation_MomentDeg object.

Parameters:
Returns:

An instance of the Estimation_MomentDeg class.

auto_fit(time, x_data, sample_method='lhs', method=None, normalize=False)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (ndarray) – A matrix representing RNA data.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize the data.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

calc_half_life(key)

Calculate half-life of a parameter.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The half-life value.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

get_param(key)

Get the estimated parameter value by key.

Parameters:

key (str) – The key of parameter.

Return type:

ndarray

Returns:

The estimated parameter value.

guestimate_gamma(x_data, time)

Roughly estimate initial conditions for parameter estimation.

Parameters:
  • x_data (ndarray) – A matrix representing RNA data.

  • time (ndarray) – A matrix of time information.

Return type:

ndarray

Returns:

Estimated gamma.

guestimate_init_cond(x_data)

Roughly estimate initial conditions for parameter estimation.

Parameters:

x_data (ndarray) – A matrix representing RNA data.

Return type:

ndarray

Returns:

Estimated initial conditions.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_MomentKin(a, b, alpha_a, alpha_i, beta, gamma, include_cov=True)

An estimation class for kinetics experiments. Order of species: <unspliced>, <spliced>, <uu>, <ss>, <us>

Initialize the Estimation_MomentKin object.

Parameters:
  • a (ndarray) – Switching rate from active promoter state to inactive promoter state.

  • b (ndarray) – Switching rate from inactive promoter state to active promoter state.

  • alpha_a (ndarray) – Transcription rate for active promoter.

  • alpha_i (ndarray) – Transcription rate for inactive promoter.

  • beta (ndarray) – Splicing rate.

  • gamma (ndarray) – Degradation rate.

  • include_cov (bool) – Whether to include the covariance when estimating.

Returns:

An instance of the Estimation_MomentKin class.

extract_data_from_simulator()

Get corresponding data from the LinearODE class.

Return type:

ndarray

Returns:

The variable from ODE simulator as an array.

get_alpha_a()

Get the transcription rate for active promoter.

Return type:

ndarray

Returns:

The transcription rate for active promoter.

get_alpha_i()

Get the transcription rate for inactive promoter.

Return type:

ndarray

Returns:

The transcription rate for inactive promoter.

get_alpha()

Get all transcription rates.

Return type:

ndarray

Returns:

All transcription rates.

get_beta()

Get the splicing rate.

Return type:

ndarray

Returns:

The splicing rate.

get_gamma()

Get the degradation rate.

Return type:

ndarray

Returns:

The degradation rate.

calc_spl_half_life()

Calculate the half life of splicing.

Return type:

ndarray

Returns:

The half life of splicing.

calc_deg_half_life()

Calculate the half life of degradation.

Return type:

ndarray

Returns:

The half life of degradation.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Estimation_MomentKinNosp(a, b, alpha_a, alpha_i, gamma)

An estimation class for kinetics experiments. Order of species: <r>, <rr>

Initialize the Estimation_MomentKinNosp object.

Parameters:
  • a (ndarray) – Switching rate from active promoter state to inactive promoter state.

  • b (ndarray) – Switching rate from inactive promoter state to active promoter state.

  • alpha_a (ndarray) – Transcription rate for active promoter.

  • alpha_i (ndarray) – Transcription rate for inactive promoter.

  • gamma (ndarray) – Degradation rate.

Returns:

An instance of the Estimation_MomentKinNosp class.

extract_data_from_simulator()

Get corresponding data from the LinearODE class.

Return type:

ndarray

Returns:

The variable from ODE simulator as an array.

get_alpha_a()

Get the transcription rate for active promoter.

Return type:

ndarray

Returns:

The transcription rate for active promoter.

get_alpha_i()

Get the transcription rate for inactive promoter.

Return type:

ndarray

Returns:

The transcription rate for inactive promoter.

get_alpha()

Get all transcription rates.

Return type:

ndarray

Returns:

All transcription rates.

get_gamma()

Get the degradation rate.

Return type:

ndarray

Returns:

The degradation rate.

calc_deg_half_life()

Calculate the half life of degradation.

Return type:

ndarray

Returns:

The half life of degradation.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model name, kinetic parameters, and initial conditions.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_model(reinstantiate=True)

Export the simulator model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model class (default: True).

Return type:

LinearODE

Returns:

Exported simulator model.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

Mixture models for kinetic / degradation experiments

class dynamo.est.tsc.Lambda_NoSwitching(model1, model2, alpha=None, lambd=None, gamma=None, x0=None, beta=None)

An estimation class with the mixture model. If beta is None, it is assumed that the data does not have the splicing process.

Initialize the Lambda_NoSwitching object.

Parameters:
Returns:

An instance of the Lambda_NoSwitching class.

auto_fit(time, x_data, **kwargs)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (Union[csr_matrix, ndarray]) – A matrix representing RNA data.

  • kwargs – The additional keyword arguments.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

export_model(reinstantiate=True)

Export the mixture model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model.

Return type:

Union[LambdaModels_NoSwitching, LinearODE]

Returns:

MixtureModels or LinearODE.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model nameS, kinetic parameters, and initial conditions.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

export_x0()

Export optimized initial conditions for the mixture of models analysis.

Return type:

Optional[ndarray]

Returns:

Exported initial conditions.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

normalize_deg_data(x_data, weight)

Normalize the degradation data while preserving the relative proportions between species. It calculates scaling factors to ensure the data’s range remains within a certain limit.

Parameters:
Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the normalized degradation data and the scaling factor.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

class dynamo.est.tsc.Mixture_KinDeg_NoSwitching(model1, model2, alpha=None, gamma=None, x0=None, beta=None)

An estimation class with the mixture model. If beta is None, it is assumed that the data does not have the splicing process.

Initialize the Mixture_KinDeg_NoSwitching object.

Parameters:
Returns:

An instance of the Mixture_KinDeg_NoSwitching class.

normalize_deg_data(x_data, weight)

Normalize the degradation data while preserving the relative proportions between species. It calculates scaling factors to ensure the data’s range remains within a certain limit.

Parameters:
Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the normalized degradation data and the scaling factor.

auto_fit(time, x_data, alpha_min=0.1, beta_min=50, gamma_min=10, kin_weight=2, use_p0=True, **kwargs)

Estimate the parameters.

Parameters:
  • time (ndarray) – The time information.

  • x_data (Union[csr_matrix, ndarray]) – A matrix representing RNA data.

  • alpha_min (Union[float, int]) – The minimum limitation on transcription rate.

  • beta_min (Union[float, int]) – The minimum limitation on splicing rate.

  • gamma_min (Union[float, int]) – The minimum limitation on degradation rate.

  • kin_weight (Union[float, int]) – Weight for scaling during normalization.

  • use_p0 (bool) – Whether to use initial parameters when estimating.

  • kwargs – The additional keyword arguments.

Return type:

Tuple[ndarray, float]

Returns:

The optimized parameters and the cost.

export_model(reinstantiate=True)

Export the mixture model.

Parameters:

reinstantiate (bool) – Whether to reinstantiate the model.

Return type:

Union[MixtureModels, LinearODE]

Returns:

MixtureModels or LinearODE.

export_x0()

Export optimized initial conditions for the mixture of models analysis.

Return type:

Optional[ndarray]

Returns:

Exported initial conditions.

export_dictionary()

Export parameter estimation results as a dictionary.

Return type:

Dict

Returns:

Dictionary containing model nameS, kinetic parameters, and initial conditions.

assemble_kin_params(unfixed_params)

Assemble the kinetic parameters array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled kinetic parameters.

assemble_x0(unfixed_params)

Assemble the initial conditions array.

Parameters:

unfixed_params (ndarray) – Array of unfixed parameters.

Return type:

ndarray

Returns:

The assembled initial conditions.

export_parameters()

Export the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

extract_data_from_simulator(t=None, **kwargs)

Extract data from the ODE simulator.

Parameters:
  • t (Optional[ndarray]) – The time information. If provided, the data will be integrated with time information.

  • kwargs – Additional keyword arguments.

Return type:

ndarray

Returns:

The variable from ODE simulator.

f_lsq(params, t, x_data, method=None, normalize=True)

Calculate the difference between simulated and observed data for least squares fitting.

Parameters:
  • params (ndarray) – Array of parameters for the simulation.

  • t (ndarray) – Array of time values.

  • x_data (ndarray) – The input array.

  • method (Optional[str]) – Method for integration.

  • normalize (bool) – Whether to normalize data.

Return type:

ndarray

Returns:

Residuals representing the differences between simulated and observed data (flattened).

fit_lsq(t, x_data, p0=None, n_p0=1, bounds=None, sample_method='lhs', method=None, normalize=True)

Fit time-seris data using the least squares method.

This method iteratively optimizes the parameters for different initial conditions (p0) and returns the optimized parameters and associated cost.

Parameters:
  • t (ndarray) – A numpy array of n time points.

  • x_data (ndarray) – An m-by-n numpy array of m species, each having n values for the n time points.

  • p0 (Optional[ndarray]) – Initial guesses of parameters. If None, a random number is generated within the bounds.

  • n_p0 (int) – Number of initial guesses.

  • bounds (Optional[Tuple[Union[float, int], Union[float, int]]]) – Lower and upper bounds for parameters.

  • sample_method (str) – Method used for sampling initial guesses of parameters: lhs: Latin hypercube sampling; uniform: Uniform random sampling.

  • method (Optional[str]) – Method used for solving ODEs. See options in simulator classes.

  • normalize (bool) – Whether to normalize values in x_data across species, so that large values do not dominate the optimizer.

Return type:

Tuple[ndarray, float]

Returns:

Optimal parameters and the cost function evaluated at the optimum.

get_SSE()

Get the sum of squared errors (SSE) from the least squares fitting.

Return type:

float

Returns:

Sum of squared errors (SSE).

get_bound(axis)

Get the bounds of the specified axis for all parameters.

Parameters:

axis (int) – The index of axis.

Return type:

ndarray

Returns:

An array containing the bounds of the specified axis for all parameters.

get_opt_kin_params()

Get the optimized kinetic parameters.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized kinetic parameters, or None if not available.

get_opt_x0_params()

Get the optimized initial conditions.

Return type:

Optional[ndarray]

Returns:

Array containing the optimized initial conditions, or None if not available.

normalize_data(X)

Perform log1p normalization on the data.

Parameters:

X (ndarray) – Target data to normalize.

Return type:

ndarray

Returns:

The normalized data.

sample_p0(samples=1, method='lhs')

Sample the initial parameters with either Latin Hypercube Sampling or random method.

Parameters:
  • samples (int) – The number of samples.

  • method (str) – The sampling method. Only support “lhs” and random sampling.

Return type:

ndarray

Returns:

The sampled array.

set_params(params)

Set the parameters of the simulator using assembled kinetic parameters.

Parameters:

params (ndarray) – Array of assembled kinetic parameters.

Return type:

None

test_chi2(t, x_data, species=None, method='matrix', normalize=True)

Perform a Pearson’s chi-square test. The statistics is computed as: sum_i (O_i - E_i)^2 / E_i, where O_i is the data and E_i is the model predication.

The data can be either:
  1. stratified moments: ‘t’ is an array of k distinct time points, ‘x_data’ is an m-by-k matrix of data,

    where m is the number of species.

Or
  1. raw data: ‘t’ is an array of k time points for k cells, ‘x_data’ is an m-by-k matrix of data, where m is

    the number of species. Note that if the method is ‘numerical’, t has to monotonically increasing.

If not all species are included in the data, use ‘species’ to specify the species of interest.

Return type:

Tuple[float, float, int]

Returns:

The p-value of a one-tailed chi-square test, the chi-square statistics and degree of freedom.

Vector field

Vector field class

class dynamo.vf.SvcVectorField(X=None, V=None, Grid=None, *args, **kwargs)[source]

Initialize the VectorField class.

Parameters:
  • X (Optional[ndarray]) – (dimension: n_obs x n_features), Original data.

  • V (Optional[ndarray]) – (dimension: n_obs x n_features), Velocities of cells in the same order and dimension of X.

  • Grid (Optional[ndarray]) – The function that returns diffusion matrix which can be dependent on the variables (for example, genes)

  • Mint (default: None) The number of basis functions to approximate the vector field. By default it is calculated as min(len(X), int(1500 * np.log(len(X)) / (np.log(len(X)) + np.log(100)))). So that any datasets with less than about 900 data points (cells) will use full data for vector field reconstruction while any dataset larger than that will at most use 1500 data points.

  • afloat (default 5) Parameter of the model of outliers. We assume the outliers obey uniform distribution, and the volume of outlier’s variation space is a.

  • betafloat (default: None) Parameter of Gaussian Kernel, k(x, y) = exp(-beta*||x-y||^2). If None, a rule-of-thumb bandwidth will be computed automatically.

  • ecrfloat (default: 1e-5) The minimum limitation of energy change rate in the iteration process.

  • gammafloat (default: 0.9) Percentage of inliers in the samples. This is an inital value for EM iteration, and it is not important. Default value is 0.9.

  • lambdafloat (default: 3) Represents the trade-off between the goodness of data fit and regularization.

  • minPfloat (default: 1e-5) The posterior probability Matrix P may be singular for matrix inversion. We set the minimum value of P as minP.

  • MaxIterint (default: 500) Maximum iteration times.

  • thetafloat (default 0.75) Define how could be an inlier. If the posterior probability of a sample is an inlier is larger than theta, then it is regarded as an inlier.

  • div_cur_free_kernelsbool (default: False) A logic flag to determine whether the divergence-free or curl-free kernels will be used for learning the vector field.

  • sigmaint Bandwidth parameter.

  • etaint Combination coefficient for the divergence-free or the curl-free kernels.

  • seed – int or 1-d array_like, optional (default: 0) Seed for RandomState. Must be convertible to 32 bit unsigned integers. Used in sampling control points. Default is to be 0 for ensure consistency between different runs.

train(normalize=False, **kwargs)[source]

Learn an function of vector field from sparse single cell samples in the entire space robustly. Reference: Regularized vector field learning with sparse approximation for mismatch removal, Ma, Jiayi, etc. al, Pattern Recognition

Parameters:

normalize (bool) – Logic flag to determine whether to normalize the data to have zero means and unit covariance. This is often required for raw dataset (for example, raw UMI counts and RNA velocity values in high dimension). But it is normally not required for low dimensional embeddings by PCA or other non-linear dimension reduction methods.

Return type:

VecFldDict

Returns:

A dictionary which contains X, Y, beta, V, C, P, VFCIndex. Where V = f(X), P is the posterior probability and VFCIndex is the indexes of inliers which found by VFC.

get_Jacobian(method='analytical', input_vector_convention='row', **kwargs)[source]

Get the Jacobian of the vector field function. If method is ‘analytical’: The analytical Jacobian will be returned and it always take row vectors as input no matter what input_vector_convention is.

If method is ‘numerical’: If the input_vector_convention is ‘row’, it means that fjac takes row vectors as input, otherwise the input should be an array of column vectors. Note that the returned Jacobian would behave exactly the same if the input is an 1d array.

The column vector convention is slightly faster than the row vector convention. So the matrix of row vector convention is converted into column vector convention under the hood.

Return type:

ndarray

No matter the method and input vector convention, the returned Jacobian is of the following format:

df_1/dx_1 df_1/dx_2 df_1/dx_3 … df_2/dx_1 df_2/dx_2 df_2/dx_3 … df_3/dx_1 df_3/dx_2 df_3/dx_3 … … … … …

get_Hessian(method='analytical', **kwargs)[source]

Get the Hessian of the vector field function. If method is ‘analytical’: The analytical Hessian will be returned and it always take row vectors as input no matter what input_vector_convention is.

Return type:

ndarray

No matter the method and input vector convention, the returned Hessian is of the following format:

df^2/dx_1^2 df_1^2/(dx_1 dx_2) df_1^2/(dx_1 dx_3) … df^2/(dx_2 dx_1) df^2/dx_2^2 df^2/(dx_2 dx_3) … df^2/(dx_3 dx_1) df^2/(dx_3 dx_2) df^2/dx_3^2 … … … … …

get_Laplacian(method='analytical', **kwargs)[source]

Get the Laplacian of the vector field. Laplacian is defined as the sum of the diagonal of the Hessian matrix. Because Hessian is originally defined for scalar function and here we extend it to vector functions. We will calculate the summation of the diagonal of each output (target) dimension.

A Laplacian filter is an edge detector used to compute the second derivatives of an image, measuring the rate at which the first derivatives change (so it is the derivative of the Jacobian). This determines if a change in adjacent pixel values is from an edge or continuous progression.

Return type:

ndarray

evaluate(CorrectIndex, VFCIndex, siz)[source]

Evaluate the precision, recall, corrRate of the sparseVFC algorithm.

Parameters:
  • CorrectIndex (List) – Ground truth indexes of the correct vector field samples.

  • VFCIndex (List) – Indexes of the correct vector field samples learned by VFC.

  • siz (int) – Number of initial matches.

Return type:

Tuple[float, float, float]

Returns:

A tuple of precision, recall, corrRate, where Precision, recall, corrRate are Precision and recall of VFC, percentage of initial correct matches, respectively.

See also:: sparseVFC().

assign_fixed_points(domain=None, cores=1, **kwargs)

assign each cell to the associated fixed points

Parameters:
  • domain (Optional[ndarray]) – Array of shape (n_dim, 2), which stores the domain for each dimension

  • cores (int) – Defaults to 1.

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

Tuple of fixed points, type assignments, and assignment IDs

compute_acceleration(X=None, method='analytical', **kwargs)

Calculate acceleration for many samples via

\[\]

a = || J cdot v ||.

Parameters:
  • X (Optional[ndarray]) – Current state. Defaults to None, initialized from self.data

  • method (str) – Method for calculating the Jacobian, one of numerical, analytical, parallel

Return type:

ndarray

Returns:

np.ndarray storing the vector norm of acceleration (across all genes) for each cell

compute_curl(X=None, method='analytical', dim1=0, dim2=1, dim3=2, **kwargs)

Curl computation for many samples for 2/3 D systems.

Parameters:
  • X (Optional[ndarray]) – Current state. Defaults to None, initialized from self.data

  • method (str) – Method for calculating the Jacobian, one of numerical, analytical, parallel

  • dim1 (int) – index of first dimension

  • dim2 (int) – index of second dimension

  • dim3 (int) – index of third dimension

Return type:

ndarray

Returns:

np.ndarray storing curl

compute_curvature(X=None, method='analytical', formula=2, **kwargs)

Calculate curvature for many samples via :rtype: ndarray

Formula 1: .. math:: kappa =

rac{||mathbf{v} imes mathbf{a}||}{||mathbf{V}||^3}

Formula 2: .. math:: kappa =

rac{||mathbf{Jv} (mathbf{v} cdot mathbf{v}) - ||mathbf{v} (mathbf{v} cdot mathbf{Jv})}{||mathbf{V}||^4}

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel formula: Choose between formulas 1 and 2 to compute the curvature. Defaults to 2.

Returns:

np.ndarray storing the vector norm of curvature (across all genes) for each cell

compute_divergence(X=None, method='analytical', **kwargs)

Takes the trace of the jacobian matrix to calculate the divergence.

Parameters:
  • X (Optional[ndarray]) – Current state. Defaults to None, initialized from self.data

  • method (str) – Method for calculating the Jacobian, one of numerical, analytical, parallel

Return type:

ndarray

Returns:

The divergence of the Jacobian matrix.

compute_sensitivity(X=None, method='analytical', **kwargs)

Calculate sensitivity for many samples via :rtype: ndarray

\[\]

S = (I - J)^{-1} D(

rac{1}{{I-J}^{-1}})

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel Defaults to “analytical”.

Returns:

np.ndarray storing sensitivity matrix

compute_torsion(X=None, method='analytical', **kwargs)

Calculate torsion for many samples via :rtype: ndarray

\[au =\]

rac{(mathbf{v} imes mathbf{a}) cdot (mathbf{J} cdot mathbf{a})}{||mathbf{V} imes mathbf{a}||^2}

Args:

X: Current state. Defaults to None, initialized from self.data method: Method for calculating the Jacobian, one of numerical, analytical, parallel

Returns:

np.ndarray storing torsion for each sample

find_fixed_points(n_x0=100, X0=None, domain=None, sampling_method='random', **kwargs)

Search for fixed points of the vector field function.

Parameters:
  • n_x0 (int) – Number of sampling points

  • X0 (Optional[ndarray]) – An array of shape (n_samples, n_dim)

  • domain (Optional[ndarray]) – Domain in which to search for fixed points

  • sampling_method (Literal['random', 'velocity', 'trn', 'kmeans']) – Method for sampling initial points. Can be one of random, velocity, trn, or kmeans.

Return type:

None

get_fixed_points(**kwargs)

Get fixed points of the vector field function.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple storing the coordinates of the fixed points and the types of the fixed points.

Types of the fixed points: -1 – stable,

0 – saddle, 1 – unstable

integrate(init_states, dims=None, scale=1, t_end=None, step_size=None, args=(), integration_direction='forward', interpolation_num=250, average=True, sampling='arc_length', verbose=False, disable=False)

Integrate along a path through the vector field field function to predict the state after a certain amount of time t has elapsed.

Parameters:
  • init_states (ndarray) – Initial state provided to scipy’s ivp_solver with shape (num_cells, num_dim)

  • dims (Union[int, list, ndarray, None]) – Dimensions of state to be used

  • scale – Scale the vector field function by this factor. Defaults to 1.

  • t_end – Integrates up till when t=t_end, Defaults to None.

  • step_size – Defaults to None.

  • args – Additional arguments provided to scipy’s ivp_solver Defaults to ().

  • integration_direction – Defaults to “forward”.

  • interpolation_num – Defaults to 250.

  • average – Defaults to True.

  • sampling – Defaults to “arc_length”.

  • verbose – Defaults to False.

  • disable – Defaults to False.

Return type:

Tuple[ndarray, ndarray]

Returns:

Tuple storing times and predictions

class dynamo.vf.Pot(Function=None, DiffMat=None, boundary=None, n_points=25, fixed_point_only=False, find_fixed_points=False, refpoint=None, stable=None, saddle=None)[source]

It implements the least action method to calculate the potential values of fixed points for a given SDE (stochastic differential equation) model. The function requires the vector field function and a diffusion matrix. This code is based on the MATLAB code from Ruoshi Yuan and Ying Tang. Potential landscape of high dimensional nonlinear stochastic dynamics with large noise. Y Tang, R Yuan, G Wang, X Zhu, P Ao - Scientific reports, 2017

Parameters:
  • Function (Optional[Callable]) – The (reconstructed) vector field function.

  • DiffMat (Optional[Callable]) – The function that returns the diffusion matrix which can variable (for example, gene) dependent.

  • boundary (Optional[List]) – The range of variables (genes).

  • n_points (int) – The number of points along the least action path.

  • fixed_point_only (bool) – The logic flag to determine whether only the potential for fixed point or entire space should be mapped.

  • find_fixed_points (bool) – The logic flag to determine whether only the gen_fixed_points function should be run to identify fixed points.

  • refpoint (Optional[ndarray]) – The reference point to define the potential.

  • stable (Optional[ndarray]) – The matrix for storing the coordinates (gene expression configuration) of the stable fixed point (characteristic state of a particular cell type).

  • saddle (Optional[ndarray]) – The matrix for storing the coordinates (gene expression configuration) of the unstable fixed point (characteristic state of cells prime to bifurcation).

fit(adata, x_lim, y_lim, basis='umap', method='Ao', xyGridSpacing=2, dt=0.01, tol=0.01, numTimeSteps=1400)[source]

Function to map out the pseudo-potential landscape.

Although it is appealing to define “potential” for biological systems as it is intuitive and familiar from other fields, it is well-known that the definition of a potential function in open biological systems is controversial (Ping Ao 2009). In the conservative system, the negative gradient of potential function is relevant to the velocity vector by ma = −Δψ (where m, a, are the mass and acceleration of the object, respectively). However, a biological system is massless, open and nonconservative, thus methods that directly learn potential function assuming a gradient system are not directly applicable. In 2004, Ao first proposed a framework that decomposes stochastic differential equations into either the gradient or the dissipative part and uses the gradient part to define a physical equivalent of potential in biological systems (P. Ao 2004). Later, various theoretical studies have been conducted towards this very goal (Xing 2010; Wang et al. 2011; J. X. Zhou et al. 2012; Qian 2013; P. Zhou and Li 2016). Bhattacharya and others also recently provided a numeric algorithm to approximate the potential landscape.

This function implements the Ao, Bhattacharya method and Ying method and will also support other methods shortly.

Parameters:
  • adata (AnnData) – AnnData object that contains U_grid and V_grid data.

  • x_lim (List) – Lower or upper limit of x-axis.

  • y_lim (List) – Lower or upper limit of y-axis.

  • basis (str) – The dimension reduction method to use.

  • method (str) – Method used to map the pseudo-potential landscape. By default, it is Bhattacharya (A deterministic map of Waddington’s epigenetic landscape for cell fate specification. Sudin Bhattacharya, Qiang Zhang and Melvin E. Andersen). Other methods will be supported include: Tang (), Ping (), Wang (), Zhou ().

  • xyGridSpacing (int) – Grid spacing for “starting points” for each “path” on the potential surface

  • dt (float) – Time step for the path integral.

  • tol (float) – Tolerance to test for convergence.

  • numTimeSteps (int) – A high-enough number for convergence with given dt.

Returns:

if Bhattacharya is used:

Xgrid: The X grid to visualize “potential surface” Ygrid: The Y grid to visualize “potential surface” Zgrid: The interpolate potential corresponding to the X,Y grids.

if Tang method is used:

retmat: The action value for the learned least action path. LAP: The least action path learned

Return type:

The AnnData object updated with the following values

Predictions

Least action path

class dynamo.pd.GeneTrajectory(adata, X=None, t=None, X_pca=None, PCs='PCs', mean='pca_mean', genes='use_for_pca', expr_func=None, **kwargs)[source]

This class is not fully functional yet.

calc_msd(save_key='traj_msd', **kwargs)[source]

Calculate the mean squared displacement (MSD) of the curve with respect to a reference point.

Parameters:
  • decomp_dim – If True, return the MSD of each dimension separately. If False, return the total MSD.

  • ref – Index of the reference point. Default is 0.

Returns:

The MSD of the curve with respect to the reference point.

calc_arclength()

Calculate the arc length of the trajectory.

Return type:

float

Returns:

arc length of the trajectory

calc_curvature()

Calculate the curvature of the trajectory.

Return type:

ndarray

Returns:

curvature of the trajectory, shape (n_points,)

calc_tangent(normalize=True)

Calculate the tangent vectors of the trajectory.

Parameters:

normalize (bool) – whether to normalize the tangent vectors. Defaults to True.

Returns:

tangent vectors of the trajectory, shape (n_points-1, n_dimensions)

dim()

Returns the number of dimensions in the trajectory.

Return type:

int

Returns:

number of dimensions in the trajectory

integrate(func)

Calculate the integral of a function along the curve.

Parameters:

func (Callable) – A function to integrate along the curve.

Return type:

ndarray

Returns:

The integral of func along the discrete curve.

interp_X(num=100, **interp_kwargs)

Interpolates the curve at num equally spaced points in t.

Parameters:
  • num (int) – The number of points to interpolate the curve at.

  • **interp_kwargs – Additional keyword arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated curve at num equally spaced points in t.

interp_t(num=100)

Interpolates the t parameter linearly.

Parameters:

num (int) – Number of interpolation points.

Return type:

ndarray

Returns:

The array of interpolated t values.

interpolate(t, **interp_kwargs)

Interpolate the curve at new time values.

Parameters:
  • t (ndarray) – The new time values at which to interpolate the curve.

  • **interp_kwargs – Additional arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated values of the curve at the specified time values.

Raises:

Exception – If self.t is None, which is needed for interpolation.

resample(n_points, tol=0.0001, inplace=True)

Resample the curve with the specified number of points.

Parameters:
  • n_points (int) – An integer specifying the number of points in the resampled curve.

  • tol (float) – A float specifying the tolerance for removing redundant points. Default is 1e-4.

  • inplace (bool) – A boolean flag indicating whether to modify the curve object in place. Default is True.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the resampled curve coordinates and time values (if available).

Raises:

ValueError – If the specified number of points is less than 2.

set_time(t, sort=True)

Set the time stamps for the trajectory. Sorts the time stamps if requested.

Parameters:
  • t (ndarray) – trajectory times, shape (n_points,)

  • sort (bool) – whether to sort the time stamps. Defaults to True.

Return type:

None

class dynamo.pd.Trajectory(X, t=None, sort=True)[source]

Base class for handling trajectory interpolation, resampling, etc.

Parameters:
  • X (ndarray) – trajectory positions, shape (n_points, n_dimensions)

  • t (Optional[ndarray]) – trajectory times, shape (n_points,). Defaults to None.

  • sort (bool) – whether to sort the time stamps. Defaults to True.

set_time(t, sort=True)[source]

Set the time stamps for the trajectory. Sorts the time stamps if requested.

Parameters:
  • t (ndarray) – trajectory times, shape (n_points,)

  • sort (bool) – whether to sort the time stamps. Defaults to True.

Return type:

None

dim()[source]

Returns the number of dimensions in the trajectory.

Return type:

int

Returns:

number of dimensions in the trajectory

calc_tangent(normalize=True)[source]

Calculate the tangent vectors of the trajectory.

Parameters:

normalize (bool) – whether to normalize the tangent vectors. Defaults to True.

Returns:

tangent vectors of the trajectory, shape (n_points-1, n_dimensions)

calc_arclength()[source]

Calculate the arc length of the trajectory.

Return type:

float

Returns:

arc length of the trajectory

calc_curvature()[source]

Calculate the curvature of the trajectory.

Return type:

ndarray

Returns:

curvature of the trajectory, shape (n_points,)

resample(n_points, tol=0.0001, inplace=True)[source]

Resample the curve with the specified number of points.

Parameters:
  • n_points (int) – An integer specifying the number of points in the resampled curve.

  • tol (float) – A float specifying the tolerance for removing redundant points. Default is 1e-4.

  • inplace (bool) – A boolean flag indicating whether to modify the curve object in place. Default is True.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the resampled curve coordinates and time values (if available).

Raises:

ValueError – If the specified number of points is less than 2.

interpolate(t, **interp_kwargs)[source]

Interpolate the curve at new time values.

Parameters:
  • t (ndarray) – The new time values at which to interpolate the curve.

  • **interp_kwargs – Additional arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated values of the curve at the specified time values.

Raises:

Exception – If self.t is None, which is needed for interpolation.

interp_t(num=100)[source]

Interpolates the t parameter linearly.

Parameters:

num (int) – Number of interpolation points.

Return type:

ndarray

Returns:

The array of interpolated t values.

interp_X(num=100, **interp_kwargs)[source]

Interpolates the curve at num equally spaced points in t.

Parameters:
  • num (int) – The number of points to interpolate the curve at.

  • **interp_kwargs – Additional keyword arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated curve at num equally spaced points in t.

integrate(func)[source]

Calculate the integral of a function along the curve.

Parameters:

func (Callable) – A function to integrate along the curve.

Return type:

ndarray

Returns:

The integral of func along the discrete curve.

calc_msd(decomp_dim=True, ref=0)[source]

Calculate the mean squared displacement (MSD) of the curve with respect to a reference point.

Parameters:
  • decomp_dim (bool) – If True, return the MSD of each dimension separately. If False, return the total MSD.

  • ref (int) – Index of the reference point. Default is 0.

Return type:

Union[float, ndarray]

Returns:

The MSD of the curve with respect to the reference point.

class dynamo.pd.LeastActionPath(X, vf_func, D=1, dt=1)[source]

A class for computing the Least Action Path for a given function and initial conditions.

Parameters:
  • X (ndarray) – The initial conditions as a 2D array of shape (n, m), where n is the number of points in the trajectory and m is the dimension of the system.

  • vf_func (Callable) – The vector field function that governs the system.

  • D (float) – The diffusion constant of the system. Defaults to 1.

  • dt (float) – The time step for the simulation. Defaults to 1.

func

The vector field function that governs the system.

D

The diffusion constant of the system.

_action

The Least Action Path action values for each point in the trajectory.

get_t()[source]

Returns the time points of the least action path.

get_dt()[source]

Returns the time step of the least action path.

action(t=None, **interp_kwargs)

Returns the Least Action Path action values at time t. If t is None, returns the action values for all time points. **interp_kwargs are passed to the interp1d function.

mfpt(action=None)[source]

Returns the mean first passage time using the action values. If action is None, uses the action values stored in the _action attribute.

optimize_dt()[source]

Optimizes the time step of the simulation to minimize the Least Action Path action.

Initializes the LeastActionPath class instance with the given initial conditions, vector field function, diffusion constant and time step.

Parameters:
  • X (ndarray) – The initial conditions as a 2D array of shape (n, m), where n is the number of points in the trajectory and m is the dimension of the system.

  • vf_func (Callable) – The vector field function that governs the system.

  • D (float) – The diffusion constant of the system. Defaults to 1.

  • dt (float) – The time step for the simulation. Defaults to 1.

get_t()[source]

Returns the time points of the trajectory.

Returns:

The time points of the trajectory.

Return type:

ndarray

get_dt()[source]

Returns the time step of the trajectory.

Returns:

The time step of the trajectory.

Return type:

float

action_t(t=None, **interp_kwargs)[source]

Returns the Least Action Path action values at time t.

Parameters:
  • t (Optional[float]) – The time point(s) to return the action value(s) for. If None, returns the action values for all time points. Defaults to None.

  • **interp_kwargs – Additional keyword arguments to pass to the interp1d function.

Returns:

The Least Action Path action value(s).

Return type:

ndarray

mfpt(action=None)[source]

Eqn. 7 of Epigenetics as a first exit problem.

Return type:

ndarray

optimize_dt()[source]

Optimizes the time step of the simulation to minimize the Least Action Path action.

Returns:

optimal time step

Return type:

float

calc_arclength()

Calculate the arc length of the trajectory.

Return type:

float

Returns:

arc length of the trajectory

calc_curvature()

Calculate the curvature of the trajectory.

Return type:

ndarray

Returns:

curvature of the trajectory, shape (n_points,)

calc_msd(decomp_dim=True, ref=0)

Calculate the mean squared displacement (MSD) of the curve with respect to a reference point.

Parameters:
  • decomp_dim (bool) – If True, return the MSD of each dimension separately. If False, return the total MSD.

  • ref (int) – Index of the reference point. Default is 0.

Return type:

Union[float, ndarray]

Returns:

The MSD of the curve with respect to the reference point.

calc_tangent(normalize=True)

Calculate the tangent vectors of the trajectory.

Parameters:

normalize (bool) – whether to normalize the tangent vectors. Defaults to True.

Returns:

tangent vectors of the trajectory, shape (n_points-1, n_dimensions)

dim()

Returns the number of dimensions in the trajectory.

Return type:

int

Returns:

number of dimensions in the trajectory

integrate(func)

Calculate the integral of a function along the curve.

Parameters:

func (Callable) – A function to integrate along the curve.

Return type:

ndarray

Returns:

The integral of func along the discrete curve.

interp_X(num=100, **interp_kwargs)

Interpolates the curve at num equally spaced points in t.

Parameters:
  • num (int) – The number of points to interpolate the curve at.

  • **interp_kwargs – Additional keyword arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated curve at num equally spaced points in t.

interp_t(num=100)

Interpolates the t parameter linearly.

Parameters:

num (int) – Number of interpolation points.

Return type:

ndarray

Returns:

The array of interpolated t values.

interpolate(t, **interp_kwargs)

Interpolate the curve at new time values.

Parameters:
  • t (ndarray) – The new time values at which to interpolate the curve.

  • **interp_kwargs – Additional arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated values of the curve at the specified time values.

Raises:

Exception – If self.t is None, which is needed for interpolation.

resample(n_points, tol=0.0001, inplace=True)

Resample the curve with the specified number of points.

Parameters:
  • n_points (int) – An integer specifying the number of points in the resampled curve.

  • tol (float) – A float specifying the tolerance for removing redundant points. Default is 1e-4.

  • inplace (bool) – A boolean flag indicating whether to modify the curve object in place. Default is True.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the resampled curve coordinates and time values (if available).

Raises:

ValueError – If the specified number of points is less than 2.

set_time(t, sort=True)

Set the time stamps for the trajectory. Sorts the time stamps if requested.

Parameters:
  • t (ndarray) – trajectory times, shape (n_points,)

  • sort (bool) – whether to sort the time stamps. Defaults to True.

Return type:

None

class dynamo.pd.GeneLeastActionPath(adata, lap=None, X_pca=None, vf_func=None, D=1, dt=1, **kwargs)[source]

Calculates the least action path trajectory and action for a gene expression dataset. Inherits from GeneTrajectory class.

Parameters:
  • adata – AnnData object containing the gene expression dataset.

  • lap (Optional[LeastActionPath]) – LeastActionPath object. Defaults to None.

  • X_pca – PCA transformed expression data. Defaults to None.

  • vf_func – Vector field function. Defaults to None.

  • D – Diffusivity value. Defaults to 1.

  • dt – Time step size. Defaults to 1.

  • **kwargs – Additional keyword arguments passed to the GeneTrajectory class.

adata

AnnData object containing the gene expression dataset.

X

Expression data.

to_pca

Transformation matrix from gene expression space to PCA space.

from_pca

Transformation matrix from PCA space to gene expression space.

PCs

Principal components from PCA analysis.

func

Vector field function reconstructed within the PCA space.

D

Diffusivity value.

t

Array of time values.

action

Array of action values.

from_lap(adata, lap, **kwargs)[source]

Initializes class from a LeastActionPath object.

Parameters:
  • adata (AnnData) – AnnData object containing the gene expression dataset.

  • lap (LeastActionPath) – LeastActionPath object.

  • **kwargs – Additional keyword arguments passed to the GeneTrajectory class.

get_t()[source]

Returns the array of time values.

Returns:

Array of time values.

Return type:

np.ndarray

get_dt()[source]

Returns the average time step size.

Returns:

Average time step size.

Return type:

float

genewise_action()[source]

Calculates the genewise action values.

Returns:

Array of genewise action values.

Return type:

np.ndarray

select_genewise_action(genes)[source]

Returns the genewise action values for the specified genes.

Parameters:

genes (Union[str, List[str]]) – List of gene names or a single gene name.

Returns:

Array of genewise action values.

Return type:

np.ndarray

calc_arclength()

Calculate the arc length of the trajectory.

Return type:

float

Returns:

arc length of the trajectory

calc_curvature()

Calculate the curvature of the trajectory.

Return type:

ndarray

Returns:

curvature of the trajectory, shape (n_points,)

calc_msd(save_key='traj_msd', **kwargs)

Calculate the mean squared displacement (MSD) of the curve with respect to a reference point.

Parameters:
  • decomp_dim – If True, return the MSD of each dimension separately. If False, return the total MSD.

  • ref – Index of the reference point. Default is 0.

Returns:

The MSD of the curve with respect to the reference point.

calc_tangent(normalize=True)

Calculate the tangent vectors of the trajectory.

Parameters:

normalize (bool) – whether to normalize the tangent vectors. Defaults to True.

Returns:

tangent vectors of the trajectory, shape (n_points-1, n_dimensions)

dim()

Returns the number of dimensions in the trajectory.

Return type:

int

Returns:

number of dimensions in the trajectory

integrate(func)

Calculate the integral of a function along the curve.

Parameters:

func (Callable) – A function to integrate along the curve.

Return type:

ndarray

Returns:

The integral of func along the discrete curve.

interp_X(num=100, **interp_kwargs)

Interpolates the curve at num equally spaced points in t.

Parameters:
  • num (int) – The number of points to interpolate the curve at.

  • **interp_kwargs – Additional keyword arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated curve at num equally spaced points in t.

interp_t(num=100)

Interpolates the t parameter linearly.

Parameters:

num (int) – Number of interpolation points.

Return type:

ndarray

Returns:

The array of interpolated t values.

interpolate(t, **interp_kwargs)

Interpolate the curve at new time values.

Parameters:
  • t (ndarray) – The new time values at which to interpolate the curve.

  • **interp_kwargs – Additional arguments to pass to scipy.interpolate.interp1d.

Return type:

ndarray

Returns:

The interpolated values of the curve at the specified time values.

Raises:

Exception – If self.t is None, which is needed for interpolation.

resample(n_points, tol=0.0001, inplace=True)

Resample the curve with the specified number of points.

Parameters:
  • n_points (int) – An integer specifying the number of points in the resampled curve.

  • tol (float) – A float specifying the tolerance for removing redundant points. Default is 1e-4.

  • inplace (bool) – A boolean flag indicating whether to modify the curve object in place. Default is True.

Return type:

Tuple[ndarray, ndarray]

Returns:

A tuple containing the resampled curve coordinates and time values (if available).

Raises:

ValueError – If the specified number of points is less than 2.

set_time(t, sort=True)

Set the time stamps for the trajectory. Sorts the time stamps if requested.

Parameters:
  • t (ndarray) – trajectory times, shape (n_points,)

  • sort (bool) – whether to sort the time stamps. Defaults to True.

Return type:

None

Movie

Animation class

class dynamo.mv.StreamFuncAnim(adata, basis='umap', fp_basis=None, dims=None, n_steps=100, cell_states=None, color='ntr', fig=None, ax=None, logspace=False, max_time=None)[source]

The class for animating cell fate commitment prediction with matplotlib.

This function is originally inspired by https://tonysyu.github.io/animating-particles-in-a-flow.html and relies on animation module from matplotlib. Note that you may need to install imagemagick in order to properly show or save the animation. See for example, http://louistiao.me/posts/notebooks/save-matplotlib-animations-as-gifs/ for more details.

Examples 1
>>> from matplotlib import animation
>>> progenitor = adata.obs_names[adata.obs.clusters == 'cluster_1']
>>> fate_progenitor = progenitor
>>> info_genes = adata.var_names[adata.var.use_for_transition]
>>> dyn.pd.fate(adata, basis='umap', init_cells=fate_progenitor, interpolation_num=100,  direction='forward',
...    inverse_transform=False, average=False)
>>> instance = dyn.mv.StreamFuncAnim(adata=adata, fig=None, ax=None)
>>> anim = animation.FuncAnimation(instance.fig, instance.update, init_func=instance.init_background,
...                                frames=np.arange(100), interval=100, blit=True)
>>> from IPython.core.display import display, HTML
>>> HTML(anim.to_jshtml()) # embedding to jupyter notebook.
>>> anim.save('fate_ani.gif',writer="imagemagick") # save as gif file.
>>> from matplotlib import animation
>>> progenitor = adata.obs_names[adata.obs.clusters == 'cluster_1']
>>> fate_progenitor = progenitor
>>> info_genes = adata.var_names[adata.var.use_for_transition]
>>> dyn.pd.fate(adata, basis='umap', init_cells=fate_progenitor, interpolation_num=100,  direction='forward',
...    inverse_transform=False, average=False)
>>> fig, ax = plt.subplots()
>>> ax = dyn.pl.topography(adata_old, color='time', ax=ax, save_show_or_return='return', color_key_cmap='viridis')
>>> ax.set_xlim(xlim)
>>> ax.set_ylim(ylim)
>>> instance = dyn.mv.StreamFuncAnim(adata=adata, fig=fig, ax=ax)
>>> anim = animation.FuncAnimation(fig, instance.update, init_func=instance.init_background,
...                                frames=np.arange(100), interval=100, blit=True)
>>> from IPython.core.display import display, HTML
>>> HTML(anim.to_jshtml()) # embedding to jupyter notebook.
>>> anim.save('fate_ani.gif',writer="imagemagick") # save as gif file.
>>> from matplotlib import animation
>>> progenitor = adata.obs_names[adata.obs.clusters == 'cluster_1']
>>> fate_progenitor = progenitor
>>> info_genes = adata.var_names[adata.var.use_for_transition]
>>> dyn.pd.fate(adata, basis='umap', init_cells=fate_progenitor, interpolation_num=100,  direction='forward',
...    inverse_transform=False, average=False)
>>> dyn.mv.animate_fates(adata)

See also:: animate_fates()

Construct the StreamFuncAnim class.

Parameters:
  • adata (AnnData) – annData object that already went through the fate prediction.

  • basis (str) – the embedding data to use for predicting cell fate. If basis is either umap or pca, the reconstructed trajectory will be projected back to high dimensional space via the inverse_transform function space.

  • fp_basis (Optional[str]) – the basis that will be used for identifying or retrieving fixed points. Note that if fps_basis is different from basis, the nearest cells of the fixed point from the fps_basis will be found and used to visualize the position of the fixed point on basis embedding.

  • dims (Optional[list]) – the dimensions of low embedding space where cells will be drawn, and it should correspond to the space fate prediction take place.

  • n_steps (int) – the number of times steps (frames) fate prediction will take.

  • cell_states (Union[int, list, None]) – the number of cells state that will be randomly selected (if int), the indices of the cells states (if list) or all cell states which fate prediction executed (if None)

  • color (str) – the key of the data that will be used to color the embedding.

  • fig (Optional[Figure]) – the figure that will contain both the background and animated components.

  • ax (Optional[Axes]) – the matplotlib axes object that will be used as background plot of the vector field animation. If ax is None, topography(adata, basis=basis, color=color, ax=ax, save_show_or_return=’return’) will be used to create an axes.

  • logspace (bool) – whether or to sample time points linearly on log space. If not, the sorted unique set of all-time points from all cell states’ fate prediction will be used and then evenly sampled up to `n_steps time points.

  • max_time (Optional[float]) – the maximum time that will be used to scale the time vector.

Returns:

A class that contains .fig attribute and .update, .init_background that can be used to produce an animation of the prediction of cell fate commitment.

init_background()[source]

Initialize background of the animation.

update(frame)[source]

Update locations of “particles” in flow on each frame.