This module allows the user to easily run an evolutionary algorithm to create mass-action chemical reaction networks with specific behaviors or to match time series data. It is intended as a research tool for computational systems biology.
There are three primary use cases for this packge:
- Evolving reaction networks with specific behaviors. The default is oscillation, but other behaviors may be added in the future. Additionally, users can input time series that reflect those desired behaviors.
- Evolving reaction networks (or ensemble models) to fit time series data. Often systems biologist will have timeseries data from experiments and will want to search for a reaction network (or group of them) that can recapitulate the time series data. This is useful for building models, informing future experiments or looking at output models for common reaction themes which may indicate the presence of those reactions in the ground truth.
- Parameter (rate constants) fitting. In the case where model topology is known (for example, the biologist has already built the model from first principles) and wants to generate parameter values for those reactions that will recapitulate experimental time series data.
This module uses the julia programming language. Installation instructions can be found here.
-
Download the package
From a julia console:using Pkg Pkg.add("ReactionNetworkEvolution") -
Run evolution with default settings Remaining in the julia console:
import ReactionNetworkEvolution as rne rne.run_evolution()NOTE: If an output directory is not supplied, then one will be created in the current working directory. Make sure that the working directory allows new directories to be made.
-
Customize Evolution (optional) The run_evolution() function takes several optional keyword arguments:
ntrials: the number of trials to run (100 by default)ngenerations: the number of generations per batch (800 by default)population_size: the number of networks in a populationpathtosettings: path to a json file storing additional custom settingsoutputpath: path to a directory where evolution output will be writtenseed: specify a seed for the random number generator
For example, to change the population_size to 200 via the command line:
rne.run_evolution(population_size=200)
Additional settings can be specified in a JSON file and supplied to the run_evolution() function as a keyword argument.
run_evolution(pathtosettings="/home/name/path/to/your/settings.json")
An example of a JSON file specifying custom settings:
{"chemical_species_names": ["A", "B", "C"],
"initial_concentrations": [5.0, 3.0, 6.0],
"reaction_probabilities": [0.2, 0.3, 0.3, 0.2],
"ngenerations": 500,
"population_size": 200,
}
Any settings that are not specified in the JSON file will be set to the default value.
| Setting Name | Default Value | Description |
|---|---|---|
| ngenerations | 800 | The number of generations |
| population_size | 100 | The number of reaction networks in the population |
| nreactions | 5 | The number of reactions in each network at the beginning of evolution (this number may be different in final networks) |
| chemical_species_names | ["S0", "S1", "S2"] | List of the chemical species names |
| initial_concentrations | [1.0, 5.0, 9.0] | The initial concentrations for the chemical species in chemical_species_names |
| seed | Random seed | |
| portion_elite | 0.1 | Portion of best networks to copy to the next generation |
| portion_delete | 0.1 | Portion of worst networks to remove |
| tournament_select | false | If true, use tournament selection to choose non-elite networks |
| reaction_probabilities | [0.1, 0.4, 0.4, 0.1] | Probability of adding uni-uni, uni-bi, bi-uni, and bi-bi reaction types |
| rateconstant_range | [0.1, 50] | Min and max values for rate constants in new reactions or when choosing a completely new rate constant (values can be mutated to outside this range for existing reactions) |
| p_rateconstant_mutation | 0.6 | Probability of changing a rate constant (as opposed to adding/deleting a reaction) |
| p_new_rateconstant | 0.15 | If mutating a rate constant, probability that a completely new rate constant will be selected from the rate constant range |
| p_crossover | 0 | Probability of crossover |
| same_fitness_crossover | false | If true, networks with similar fitness will be considered equally fit and crossed over more leniently |
| same_fitness_percent_range | 0.05 | If using same fitness crossover, networks with fitnesses within 1-x and 1+x will be considered the same fitness |
| p_mutation | 1 | Probability of mutating a network by modifying rate constants or adding/deleting reactions |
| exclusive_crossover_mutation | false | If true, networks will EITHER be crossed over OR mutated but never both |
| enable_speciation | true | If true, networks will be divided into species and compete amongst themselves |
| starting_delta | 0.65 | The speciation threshold at the beginning of evolution |
| delta_step | 0.1 | The amount by which delta is adjusted to achieve the target number of species |
| target_num_species | 10 | The threshold to split reaction networks into species will be adjusted up and down to attempt to maintain this number of species. |
| use_seed_network | false | If true, the first generation will be populated with copies of a seed network loaded from the specified path |
| seed_network_path | If using a seed network, the path to the network | |
| randomize_seed_network_rates | true | If true and using a seed network, the reaction rate constants will be selected randomly from the rate constant range |
| average_fitness | false | If true, each species fitness will be the average of its networks - otherwise species fitness is the top network’s fitness |
| rateconstant_distance_weight | 0.0 | Weight given to different paramters values when calculating distance between two networks - if 0, parameters will not be considered when calculating distance |
| objective_data_path | If generating networks to fit data, path to .csv file with data to fit - if no path is given, ReactionNetworkEvolution.jl will attempt to generate oscillators | |
| track_fitness | true | Track information about evolution such as top fitness, number of species, etc for each generation |
| writeout_threshold | 0.05 | If the best network reaches this fitness or higher, evolution will be stopped |
| process_output_oscillators | true | If true, automatically test if evolved networks are oscillators or not |
This package was primarily designed to generate mass-action chemical reaction networks with oscillatory behavior. With the defualt settings, it will generate oscillators with 3 chemical species.
- Download the package
From a julia console:using Pkg Pkg.add("ReactionNetworkEvolution") - Run evolution with default settings
Remaining in the julia console:
import ReactionNetworkEvolution as rne rne.run_evolution()
- Supply the time series data as a CSV file.
- Create a JSON file with at least the following setting to direct the package to the time series CSV and disable sorting oscillators
{"objective_data_path": "/path/to/timeseries_data.csv",
"process_output_oscillators": false}
- Run evolution supplying the JSON file:
import ReactionNetworkEvolution as rne
rne.run_evolution(pathtosettings="/path/to/settingsfile.json")
- Supply the time series data as a CSV file
- Supply the network topology as an antimony file.
- Create a JSON file with at least the following settings:
{"objective_data_path": "/path/to/timeseries_data.csv",
"process_output_oscillators": false,
"seed_network_path": "/path/to/antimonyfile.txt",
"rateconstant_distance_weight": 1.0,
"p_rateconstant_mutation" 1.0}
The rateconstant_distance_weight setting enables the package to consider differences in reaction weight constants when comparing twp networks. This is necessary if all networks have the same topology, although some adjustments to the value may be necessary.
Setting p_rateconstant_mutation to 1.0 prevents the algorithm from adding or deleting reactions during evolution.
- Run evolution supplying the JSON file:
import ReactionNetworkEvolution as rne
rne.run_evolution(pathtosettings="/path/to/settingsfile.json")