mimic.model_simulate package

Submodules

mimic.model_simulate.base_model module

class mimic.model_simulate.base_model.BaseModel(debug: str | None = None)

Bases: ABC

Abstract base class for creating and managing simulation models.

This class serves as a foundation for any type of model that requires managing data, parameters, and basic I/O operations. It defines a common interface for parameter handling, data simulation, and data persistence.

Attributes:

data (np.ndarray | None):

Holds the output data generated by the model’s simulation. This could be None if the model has not yet produced any data.

model (object | None):

A generic placeholder for the specific simulation model instance. This attribute should be overridden in subclasses with an actual model representation.

parameters (dict | None):

A dictionary containing the parameters that control the model’s behavior. Parameters should be defined in subclasses or set through the provided methods.

Abstract Methods:

set_parameters(self):

Should be implemented by subclasses to define how model parameters are set or updated.

simulate(self):

Should be implemented by subclasses to define the model’s simulation process based on the set parameters.

Methods:

check_params(self, params, sim_type):

Checks provided parameters against required ones for a given simulation type, applying default values if necessary.

read_parameters(self, filepath):

Reads model parameters from a specified JSON file and updates the model’s parameters accordingly.

save_parameters(self, filepath, parameters=None):

Saves the model’s current parameters to a JSON file. Optionally, a specific set of parameters can be provided to save instead.

print_parameters(self, precision=2):

Prints the current set of model parameters to the console, formatting numpy arrays with specified precision.

save_data(self, filename, data=None):

Saves the model’s generated data to a CSV file. Optionally, specific data can be provided to save instead.

load_data(self, filename):

Loads data from a specified CSV file into the model’s data attribute.

_custom_array_to_string(self, array, precision=2):

Converts a numpy array to a string representation with specified precision.

update_attributes(self):

Updates class attributes based on the current parameters dictionary.

Initializes the BaseModel with default values.

check_params(params: Dict[str, Any] | None, sim_type: str) → None

Checks and updates simulation parameters with defaults if necessary.

Validates provided parameters against the simulation type and updates missing or None values with defaults. Warnings are issued for missing parameters.

Parameters:

params (dict): User-provided parameters for the simulation. sim_type (str): The type of simulation to perform (‘VAR’, ‘gMLV’, or ‘sVAR’).

Raises:

ValueError: If an unsupported simulation type is specified.

property debug: str | None

Gets the current debug level.

load_data(filename: str) → None

Loads data from a CSV file into the model’s data attribute.

Parameters:

filename (str): The name of the CSV file from which to load data.

Raises:

ValueError: If filename does not point to a .csv file. FileNotFoundError: If filename does not exist.

print_parameters(precision: int = 2) → None

Prints the model’s parameters to the console with formatted numpy arrays.

Numpy arrays are converted to strings with compact formatting, using the specified precision for floating-point numbers.

Parameters:

precision (int): Precision for formatting numpy array elements.

read_parameters(filepath: str) → None

Reads parameters from a JSON file and updates the model’s parameters.

Parameters that can be converted to numpy arrays are handled accordingly.

Parameters:

filepath (str): Path to the JSON file containing parameters.

Raises:

ValueError: If the filepath does not point to a .json file. FileNotFoundError: If the specified file does not exist.

save_data(filename: str, data: ndarray | None = None) → None

Saves data to a CSV file.

If data is not provided, the model’s current data is used. Raises exceptions if the filename does not end with ‘.csv’ or if the specified directory does not exist.

Parameters:

filename (str): The name of the CSV file to save data. data (numpy.ndarray, optional): The data to save. Uses model’s data if None.

Raises:

ValueError: If filename does not end with ‘.csv’. FileNotFoundError: If the directory to save the file does not exist.

save_parameters(filepath: str, parameters: Dict[str, int | float | ndarray | str | Any] | None = None) → None

Saves the model’s parameters to a JSON file.

Parameters can be optionally provided; otherwise, the model’s current parameters are used. Numpy arrays are converted to lists for JSON serialization.

Parameters:

filepath (str): Path to the JSON file for saving parameters. parameters (dict, optional): Parameters to save. Uses model’s parameters if None.

Raises:

ValueError: If the filepath does not end with ‘.json’. FileNotFoundError: If the specified directory does not exist.

abstract set_parameters() → None

Abstract method for setting parameters specific to the model.

Subclasses should implement this method to customize parameter handling.

abstract simulate(*args, **kwargs)

Abstract method to simulate data based on the model’s parameters.

Subclasses must implement this method to provide specific simulation functionality.

update_attributes() → None

Updates class attributes based on the current parameters dictionary.

This method iterates through the parameters dictionary and updates the class attributes with corresponding keys to match the parameter values.

mimic.model_simulate.sim_VAR module

class mimic.model_simulate.sim_VAR.sim_VAR

Bases: BaseModel

A class for simulating Vector Autoregression (VAR) models.

Inherits from BaseModel and adds specific functionalities for VAR model simulation, including data generation for both univariate and multivariate autoregressive processes.

This class allows users to simulate data from VAR models, specify model parameters, generate simulated data, visualize the results through various plotting methods, and save the generated data for further analysis. It supports both single and multi-variable autoregressive models, making it versatile for different simulation scenarios.

Attributes:

n_obs (int): Number of observations to generate. coefficients (np.ndarray): Coefficients of the VAR model. initial_values (np.ndarray): Initial values for the VAR model simulation. noise_stddev (float): Standard deviation of the noise in the VAR model. output (str): Specifies the output action for plots (‘show’, ‘save’, or ‘both’). dataM (np.ndarray): Holds the generated data for multivariate simulations. coefficientsM (np.ndarray): Coefficients for the multivariate VAR model. initial_valuesM (np.ndarray): Initial values for the multivariate VAR model simulation.

Methods:

set_parameters: Allows setting or updating model parameters like number of observations,

model coefficients, initial values, and noise standard deviation. It supports both univariate and multivariate VAR models.

generate_var1_data: Simulates data from a VAR(1) process using the specified model parameters

and saves the generated data. It can also generate and overlay plots based on the ‘output’ attribute.

generate_mvar1_data: Generates data from a multivariate autoregressive process. It can work

with complex interactions between multiple variables and supports overlay plotting based on the ‘output’ attribute.

simulate: Acts as a controller to execute the simulation based on the specified command. It

supports commands for simulating univariate VAR, multivariate VAR, and generating plots as specified.

make_plot_overlay: Creates overlay plots for visual comparison of simulated data across

different variables or processes.

make_plot_stacked: Generates a stacked plot and heatmap for the given data, offering a

detailed visualization of the simulation results.

make_plot: Produces separate line plots for each variable in the given data, facilitating

an in-depth analysis of each variable’s behavior over time.

Initializes the sim_VAR instance with default parameter values.

generate_mvar1_data(coefficientsM: ndarray, initial_valuesM: ndarray) → tuple[ndarray, ndarray]

Generates synthetic data for a multivariate autoregressive (MVAR) process of order 1.

Specifically tailored for generating data from complex MVAR processes where interactions between multiple variables are considered.

Parameters:

coefficientsM (np.ndarray): Coefficients for the MVAR model. initial_valuesM (np.ndarray): Initial values for the MVAR model simulation.

Returns:

tuple: A tuple containing two numpy.ndarrays. The first array is the generated data

for the X process, and the second array is the generated data for the S process. Both arrays have shapes (n_obs, number of X variables) and (n_obs, number of S variables), respectively.

generate_var1_data() → ndarray

Generate simulated data from a VAR(1) process.

Simulates a univariate or multivariate VAR(1) process based on the set parameters. This method populates the data attribute with the generated data.

Returns:

np.ndarray: The generated data as a numpy array with shape (n_obs, number of variables).

make_plot(dataX: ndarray, dataS: ndarray | None = None, output: str | None = 'show') → None

Generates separate line plots for each variable in the given data, facilitating detailed analysis.

This method creates individual line plots for each variable in the primary and, optionally, secondary data series. This detailed visualization allows for in-depth analysis of each variable’s behavior over time.

Parameters:

dataX (np.ndarray): The primary data series for the VAR process. Shape: (n_obs, num_variables). dataS (np.ndarray, optional): The secondary data series for comparison. Shape: (n_obs, num_variables). output (str): Controls the output of the plot (‘show’, ‘save’, or ‘both’).

Note:

Saves the individual plots as “plot-data-XS.pdf” if ‘save’ or ‘both’ is selected as output.

make_plot_overlay(dataX: ndarray, dataS: ndarray | None = None, output: str | None = 'show') → None

Creates an overlay plot of the given data for easy comparison.

This method visualizes the time series data by overlaying the plots of each variable. It supports both the primary VAR process data and an optional secondary process data for comparison.

Parameters:

dataX (np.ndarray): The primary data series for the VAR process. Shape: (n_obs, num_variables). dataS (np.ndarray, optional): The secondary data series for comparison. Shape: (n_obs, num_variables). output (str): Controls the output of the plot (‘show’, ‘save’, or ‘both’).

Note:

Saves the plot as “plot-data-overlay.pdf” if ‘save’ or ‘both’ is selected as output.

make_plot_stacked(dataX: ndarray, dataS: ndarray) → None

Creates a stacked plot and a heatmap for the given data, providing a comprehensive view of the data dynamics.

This method visualizes the time series data from the VAR process in a stacked plot for a clear overview of each variable’s contribution over time. Additionally, it generates a heatmap for secondary data, offering an intuitive representation of data intensity across variables and time points.

Parameters:

dataX (np.ndarray): The primary data series from the VAR process. Shape: (n_obs, num_variables). dataS (np.ndarray): The secondary data series for heatmap visualization. Shape: (n_obs, num_variables).

Note:

Saves the plots as “plot-data-XS-stacked.pdf”.

set_parameters(n_obs: int | None = None, coefficients: List[List[int | float]] | None = None, initial_values: List[List[int]] | None = None, noise_stddev: int | float | None = None, output: str | None = None, coefficientsM: List[List[int | float]] | None = None, initial_valuesM: List[List[int | float]] | None = None) → None

Sets the parameters for the sim_VAR instance.

Allows optional specification of all model parameters. Parameters not provided (None) are left unchanged.

Parameters:

n_obs (Optional[int]): Number of observations to generate. coefficients (Optional[List[List[Union[int, float]]]]): Coefficients of the VAR model. initial_values (Optional[List[List[int]]]): Initial values for the VAR model simulation. noise_stddev (Optional[Union[int, float]]): Standard deviation of the noise. output (Optional[str]): Output action for plots (‘show’, ‘save’, or ‘both’). coefficientsM (Optional[List[List[Union[int, float]]]]): Coefficients for the multivariate VAR model. initial_valuesM (Optional[List[List[int]]]): Initial values for the multivariate VAR model simulation.

simulate(command: str) → None

Simulates data based on the specified command.

Supports commands for simulating VAR and multivariate VAR (MVAR) processes. Adjusts internal state based on simulation results.

Parameters:

command (str): The simulation command (‘VARsim’ for VAR simulation, ‘MVARsim’ for multivariate VAR simulation).

Raises:

ValueError: If an invalid command is provided.

mimic.model_simulate.sim_gMLV module

mimic.model_simulate.sim_gMLV.gMLV(sy, t, nsp, np, mu, M, beta, epsilon, u) → ndarray

Differential equations for the generalized Lotka-Volterra model with metabolite production.

Parameters:

sy (numpy.ndarray): Combined vector of species and metabolites at the current time. t (float): Current time point. nsp (int): Number of species. np (int): Number of perturbations. mu (numpy.ndarray): Specific growth rates vector. M (numpy.ndarray): Interaction matrix. beta (numpy.ndarray): Metabolite production rate matrix. epsilon (numpy.ndarray): Perturbation matrix. u (callable): Function to compute the perturbation signal at time t.

Returns:

numpy.ndarray: The derivative of the combined species and metabolites vector.

class mimic.model_simulate.sim_gMLV.sim_gMLV(num_species=2, num_metabolites=0, num_perturbations=0, mu=None, M=None, beta=None, epsilon=None)

Bases: BaseModel

Simulation class for generalized Lotka-Volterra (gMLV) models with metabolite production.

This class extends the BaseModel to support simulations of ecological systems or microbial communities described by the gMLV model, which can include interactions between species, production of metabolites, and responses to external perturbations.

Attributes:

num_species (int): The number of species in the simulation. num_metabolites (int): The number of metabolites produced by the species. num_perturbations (int): The number of external perturbations applied to the system. mu (numpy.ndarray): Vector of intrinsic growth rates of the species. M (numpy.ndarray): Interaction matrix describing the effects of species on each other. beta (numpy.ndarray): Metabolite production matrix describing the production rates of metabolites by species. epsilon (numpy.ndarray): Perturbation matrix describing the effects of external perturbations on species.

Methods:

set_parameters: Sets or updates the parameters for the simulation. simulate: Runs the gMLV simulation over a specified time course and initial conditions.

Initializes the gMLV simulation with given parameters or defaults.

Parameters:

num_species (int, optional): The number of species. Defaults to 2. num_metabolites (int, optional): The number of metabolites. Defaults to 0. num_perturbations (int, optional): The number of perturbations. Defaults to 0. mu (numpy.ndarray, optional): Intrinsic growth rates. Random lognormal values by default. M (numpy.ndarray, optional): Interaction matrix. Random values with self-repression on diagonal by default. beta (numpy.ndarray, optional): Metabolite production rates. Zeros by default or random values if num_metabolites > 0. epsilon (numpy.ndarray, optional): Perturbation effects. Zeros by default.

set_parameters(num_species: int | None = None, num_metabolites: int | None = None, num_perturbations: int | None = None, mu: List[float] | ndarray | None = None, M: List[List[float]] | ndarray | None = None, beta: List[List[float]] | ndarray | None = None, epsilon: List[List[float]] | ndarray | None = None) → None

Updates the simulation parameters. Only provided values are updated; others remain unchanged.

Parameters:

num_species (Optional[int]): Number of species. num_metabolites (Optional[int]): Number of metabolites. num_perturbations (Optional[int]): Number of perturbations. mu (Optional[Union[List[float], numpy.ndarray]]): Growth rates. M (Optional[Union[List[List[float]], numpy.ndarray]]): Interaction matrix. beta (Optional[Union[List[List[float]], numpy.ndarray]]): Metabolite production rates. epsilon (Optional[Union[List[List[float]], numpy.ndarray]]): Perturbation effects.

simulate(times, sy0, u=None) → tuple[ndarray, ndarray, ndarray, ndarray, ndarray, ndarray]

Runs the gMLV simulation over the specified time course with given initial conditions and optional perturbations.

Parameters:

times (numpy.ndarray): Array of time points at which to simulate. sy0 (numpy.ndarray): Initial conditions for species and metabolites. u (callable, optional): Function representing the external perturbation signal over time.

Returns:

tuple: Tuple containing the simulation results for species (yobs), metabolites (sobs), initial conditions (sy0), growth rates (mu), interaction matrix (M), and metabolite production rates (beta).

Module contents