fsml.simulate package

Submodules

fsml.simulate.main module

fsml.simulate.main.transform_and_simulate(**kwargs: Dict[str, any]) → None

Download, transform and simulate a bunch of model in a multiprocessing way.

Parameters:

kwargs – A Python Dictionary that must contains the following fields: - prefix_path, with the path of the test folder - nmodels, the number of models to download, transform and simulate - paths_file, the path to the file where to store the final paths - log_dir, with the path of the log folder - output_dir, with the path of the output folder - data_dir, with the path of the data folder - nsim_per_model, the number of simulations to run for each model - gen_do, boolean True generate also the dense output

Returns:

fsml.simulate.main.transform_and_simulate_one(kwargs: Dict[str, any]) → str

Given a kind of configuration, it download, transforms and simulate a biomodel.

Parameters:

kwargs – A Python Dictionary that must contains the following fields: - prefix_path, with the path of the test folder - model_id, with the ID of the model to simulate - log_dir, with the path of the log folder - output_dir, with the path of the output folder - data_dir, with the path of the data folder - job_id, not important left to 0 - nsim, the number of simulations - gen_do, boolean True generate also the dense output

Returns:

the path of the model stored in the test folder

fsml.simulate.simulate module

class fsml.simulate.simulate.ParameterSampler(params: List[float], param_conf: ParameterSamplerConfiguration)

Bases: object

A class for parameter sampling.

The goal is to generate each time a combination of all the parameters (in order) such that each parameter is transformed in according what’s written below. All the generated combinations are unique. A combination is generated using a random walk on the matrix starting from the first row, picking an element at random and then going down in the remaining rows.

Given the list of parameters as input, let N be the size of the list, it returns a matrix of N rows times nchange_per_param + 1 columns such that at each rows corresponds the vector of possible changes for the single parameter. That is, each row is a row vector of size nchange_per_param + 1, where the first element is the original value of the corresponding parameter and all the other columns contains a random value. The random value is sampled from a Ball of radius exactly the `perc`% of the original value centered on the parameter.

Attributes

paramsnp.ndarray

The vector with all the parameters

confParameterSamplerConfiguration

The configuration for the sampler

generate() → Generator[ndarray, None, None]

Generate the actual sampling

class fsml.simulate.simulate.ParameterSamplerConfiguration(total_number_of_sample: int, percentage_of_change: float, total_sample_per_param: int)

Bases: object

Just a configuration class for the ParameterSampler

percentage_of_change: float

total_number_of_sample: int

total_sample_per_param: int

class fsml.simulate.simulate.TaskConfiguration(step_size: float | None, initial_time: float, sim_horizon: float, gen_time_series: bool, automatic_step_size: bool, output_event: bool, abs_tolerance: float, rel_tolerance: float, report_out_stype: str, report_fixed_species: bool, data_path: Tuple[str, str])

Bases: object

This Python dataclass is used the represent a COPASI trajectory task configuration. A Trajectory task configuration is used to set the value for the simulation step number, the simulation initial time, the horizon, absolute and relative tolerances … This class is given as input to the obj:TrajectoryTask.setup_task function.

Attributes

step_sizefloat or None

the step size of the simulation

initial_timefloat

The initial time of the simulation

sim_horizonfloat

The horizon of the simulation

get_time_seriesbool

Tell the task (or problem) to generate the time series

automatic_step_sizebool

Tell the task to use automatic step size or not. This should be set to False whenever we set step_size to None. Otherwise, we can safely set True.

output_eventbool

Tell COPASI if we want additional points for event assignments

abs_tolerancefloat

the absolute tolerance

rel_tolerancefloat

the relative tolerance

report_out_stypestr

The output type of the species in the report (concentration or amount)

report_fixed_speciesbool

If consider in the report also FIXED value species

data_pathTuple[str,str]

A tuple with two elements, the first is the path for mean and std. output the second, instead, is the output path for the dense output.

abs_tolerance: float

automatic_step_size: bool

data_path: Tuple[str, str]

gen_time_series: bool

initial_time: float

output_event: bool

rel_tolerance: float

report_fixed_species: bool

report_out_stype: str

sim_horizon: float

step_size: float | None

class fsml.simulate.simulate.TrajectoryTask(model_file: str, log_dir: str, output_dir: str, filename: str, job: int, nsim: int, param_conf: ParameterSamplerConfiguration)

Bases: object

A class used to represent a COPASI Trajectory Task. Each taks is independent from the others and can be identified by an appropriate Task ID. With this class the user can setup a Trajectory Task, initialize all the parameters like the horizon of the simulation, the initial time step, if automatic step size or not, absolute and relative tolerances and more other options. Finally, once the setup is done, the user can run the simulation and store the result in appropriate folders.

Attributes

datamodelCOPASI.CDataModel

a handle to the COPASI data model that contains the actual SBML model

idstr

the identifier of the task (unique and generated using generate_taskid function)

trajectory_taskCOPASI.CTrajectoryTask

the actual trajectory task returned by the data model

log_pathstr

the path where to store the file containing the log of the simulation

output_pathstr

the path where to store the file containing the results of the simulation

output_filestr

the file path where to store the final resulsts of the simulation

res_filestr

the file path where to store all the dense output for the simulation

filenamestr

the filename of the model (without the extension)

num_simulationsint

The total number of simulations

real_parameters_valueDict[str, float]

A dictionary containing the original values for the parameters of the model

modified_parameters_valuesList[Dict[str, float]]

A List containing mapping from parameters name and parameter values

runnedbool

If the trajectory task has been runned or not

psampler_confParameterSamplerConfiguration

The configurator for the ParameterSampler

mean_std_arrayList[List[float]]

The array that contains the output of the simulations such that each row is a simulation and the first N columns are the parameters while the last M columns are the mean and the standard deviation of the outputs

get_model() → CModel

Return the model handler of the current datamodel

get_used_parameters() → List[Dict[str, float]]

Return the list of all the parameter mapping used for each simulation

Returns:

the parameter mapping

load_model() → None

Load a new model from file

print_informations() → None

Print all the useful information about the input model into two files <log_path><filename>_species.csv and <log_path><filename>_parameters.csv. The stored informations involve all the species of the model and all its paremeters.

print_results() → None

This method prints the final result of the simulation to the output file. The output file is identified by the task ID with an _res suffix. The file will be stored in the output folder given as input to the constructor of the class. In the result file will be visible: the total number of steps of the simulation, the total number of variables for each step and the final state, i.e., the final values for each species.

run(conf: TaskConfiguration, gen_denseoutput: bool = False) → None

Run the trajectory task

Parameters:

• conf – the Trajectory Task Configuration

• gen_denseoutput – True to genereate also the Denseoutput file

Returns:

run_task() → bool

Run a Time-Course simulation with COPASI and returns TRUE If no error occurred, otherwise it returns False.

Parameters:

trajectory_task – a handle to the Time-Course Task

Returns:

True if no errors, False otherwise

setup_task(conf: TaskConfiguration) → None

Setup different options for the trajectory task.

Parameters:

conf – the configuration to be applied

Returns:

fsml.simulate.simulate.create_report(datamodel: CDataModel, task_id: str, out_stype: str, fixed_species: bool = False) → CReportDefinition

Function to create a report definition which will contain all the information (i.e. time step and species values) from a time-course simulation. The report will have N + 1 columns, where N is equal to the number of species and the +1 is given by the “time” column, and a number of row that is equal to the horizon of the simulation times the size of each step (in the case a fixed time step has been chosen).

Parameters:

• datamodel – a handle to a COPASI DataModel

• task_id – the string representing the ID of the task

• out_stype – (possible values are “Concetration” (or “concentration”) and “Amount” (or “amount”)) if we want to consider the concentration or the amount value for each specie.

• fixed_species – if in the output we want to put also FIXED value species.

Returns:

the report definition

fsml.simulate.simulate.generate_default_configuration() → TaskConfiguration

Generate a default configuration for the Trajectory Task. The default configuration is the following:

• step size = 0.01

• initial time = 0.0

• simulation horizon = 100.0

• generate time series = True

• automatic step size = False

• output event = False

• absolute tolerance 1.0e-9

• relative tolerance 1.0e-9

• output also fixed species = False

• output concentration or amount ? Concentration

Returns:

a new TaskConfiguration object already configured

fsml.simulate.simulate.generate_default_param_sampler_configuration() → ParameterSamplerConfiguration

Generate a default configuration for the ParameterSampler

fsml.simulate.simulate.generate_taskid(model_name: str, count: int) → str

Generate a new task ID. The ID is in the following format: <hour><min><sec>-<number>-<filename>, where all the component are in Hexadecimal form. <number> is an integer that is sequentially incremented each time a new task is generated.

Parameters:

• model_name – the name of the model

• count – just an integer

Returns:

the ID

fsml.simulate.simulate.run_one(model_path: str, log_dir: str, output_dir: str, data_dir: str, job_id: int, nsim: int, gen_do: bool) → None

Run nsim simulation for the single input model

Parameters:

model_path – the absolute path to the SBML

:param log_dir : the absolute path to the log folder where to store the parameter and specie files :param output_dir: the absolute path to the output dir where to store the report and the result files :param data_dir : the absolute path to the data folder where to store the output data :param job_id : The ID of the job (just an integer) :param nsim : the total number of simultations to run :param gen_do : True if also the Dense Output should be generated :return:

fsml.simulate.simulate.run_simulations(paths_file: str, log_dir: str, output_dir: str, data_dir: str, nsim_per_model: int = 100, gen_denseoutput: bool = False) → None

Run nsim_per_model simulations per each model belonging to the paths file where the paths file is a path that in each line contains the fully qualified path to the SBML of that model.

:param paths_file : the absolute path to the paths file :param log_dir : the absolute path to the log folder where to store the parameter and specie files :param output_dir: the absolute path to the output dir where to store the report and the result files :param data_dir : the absolute path to the data folder where to store the output data :param nsim_per_model: the number of simulations per model :param gen_denseoutput: True if also the Dense Output should be generated :return

fsml.simulate.transform module

fsml.simulate.transform.add_amount_species(document: SBMLDocument) → None

Given a libsbml.SBMLDocument object that describe the current loaded SBML model, add to the species list a number of new species such that each of the new specie represent the amount (or particle number) value of the already existing species. That is, given a model with N species, we add N more species such that given an existing specie s_i the new one will be s_i_amount.

Then for each of the N new species, we need to add a new assignment rules that map the new specie to the product s_i / compartment.

Parameters:

document – A handle to the SBML Document

Returns:

fsml.simulate.transform.convert_models(prefix_path: str, nmodels: int) → List[str]

Download and converts a bunch of models

Parameters:

• prefix_path – the path where to save the downloaded models

• nmodels – the number of models to download and convert

Returns:

a list containing all the paths to the transformed models

fsml.simulate.transform.convert_one(prefix_path: str, model_id: int) → str

Convert one model speciefied by the model_id input parameter

Parameters:

args –

a List of arguments for the multiprocessing map function This parameter must contains only three elements:

• prefix_path: the path where to save the model

• model_id: the ID of the model in the BioModels database

Returns:

the path where the transformed model has been saved

fsml.simulate.transform.sbml_to_raterules(document: SBMLDocument) → SBMLDocument

Convert the SBML model by replacing all the reactions with the corresponding Rate Rules, i.e. ODE. In this way we also have that all the parameters local to reactions, now they become global to all the model.

Parameters:

document – a handler to the SBML document

Returns:

fsml.simulate.transform.transform(sbmlfile: str, outputfile: str) → None

Load the model, transform the model and finally save the modified model.

Parameters:

• sbmlfile – the absolute path to the SBML model to load

• outputfile – the absolute path to the file where to store the new SBML

Returns:

fsml.simulate.transform.transform_model(sbml_path: str) → str

Transform a SBML model using the transform function

Parameters:

sbml_path – the path to the SBML model

Returns:

the path where the transformed model has been saved

Module contents