Documentation

FindSim source code is hosted at http://github.com/BhallaLab/FindSim.

Quick start for Command line reference and Utilities for FindSim:

    A. Run one of the example experiments on the default model, generating a graph to compare model to experiment

    python findSim.py [-h] [-m MODEL] [-d DUMP_SUBSET] [-p PARAM_FILE] [-t] [-hp] [-hs] [-o] [-s SCALE_PARAM SCALE_PARAM SCALE_PARAM] [-settle_time SETTLE_TIME] script

      required arguments:
      • script : filename of experiment spec, in tsv format.
        optional arguments:
        • -h, --help : show this help message and exit
        • -m MODEL, --model MODEL : model filename, .g or .xml
        • -d DUMP_SUBSET, --dump_subset DUMP_SUBSET : dump selected subset of model into named file
        • -p PARAM_FILE, --param_file PARAM_FILE : Generate file of tweakable params belonging to selected subset of model
        • -hp, --hide_plot : Hide plot output of simulation along with expected values. Default is to show plot.
        • -hs, --hide_subplots : Hide subplot output of simulation. By default the graphs include dotted lines to indicate individual quantities (e.g., states of a molecule) that are being summed to give a total response. This flag turns off just those dotted lines, while leaving the main plot intact.
        • -o, --optimize_elec : Optimize electrical computation. By default the electrical computation runs for the entire duration of the simulation. With this flag the system turns off the electrical engine except during the times when electrical stimuli are being given. This can be *much* faster.
        • -s SCALE_PARAM SCALE_PARAM SCALE_PARAM, --scale_param SCALE_PARAM SCALE_PARAM SCALE_PARAM : Scale specified object.field by ratio.
        • -settle_time SETTLE_TIME, --settle_time SETTLE_TIME : Run model for specified settle time and return dict of {path,conc}.

    To run the script, run the command in python with one of the example experiments on the default model, generating a graph to compare model to experiment:
      python findSim.py Curated/FindSim-Jain2009-Fig2B.tsv

    To run with the latest model "synSynth7.g" that is tested out the worksheet, run the command in python
      python findSim.py Curated/FindSim-Jain2009-Fig2B.tsv --model synSynth7.g

     

      B. Batch run
      1. runAllParallel: This program is useful to find out how a given model works against a range of experiments.
        This script runs the findSim program on all experiments (codified as tsv files) in the specified directory and computes scores to indicate how well the simulations fit the experimental data. The program then prints out basic stats of the scores.
        Since there are likely to be multiple tsv files pertaining to any given model, the program is able to run all these in parallel on multicore machines. Even your laptop is probably a multicore machine

        python runAllParallel.py [-h] [-n NUMPROCESSES] [-m MODEL] [-s SCALE_PARAM SCALE_PARAM SCALE_PARAM] location

          required arguments:
          • location : Directory in which the scripts (in tsv format) are all located.
            optional arguments:
            • -h, --help: show this help message and exit
            • -n NUMPROCESSES, --numProcesses NUMPROCESSES : Number of processes to spawn
            • -m MODEL, --model MODEL : Composite model definition file. First searche's in "location" directory, then in current directory.
            • -s SCALE_PARAM SCALE_PARAM SCALE_PARAM, --scale_param SCALE_PARAM SCALE_PARAM SCALE_PARAM : Scale specified object.field by ratio.

      2. basicParameterSweep: This program is useful for initial explorations of parameter space, and parameter sensitivity analysis.

      This program launches a parameter sweep, that is a systematic scan through parameter space for a model. It runs the findSim program on all experiments (codified into tsv files) in the specified directory, and repeats all this for each combination of parameters. It computes the mean score of all experiments for each parameter setting and presents the "best" (parameter, score) along with next-best flanking parameters. It can do this in parallel on a multicore machine, using Python's multiprocessing library. parallel on a multicore machine.

        python basicParameterSweep.py [-h] [-n NUMPROCESSES] [-m MODEL] [-p [PARAMETER_SWEEP [PARAMETER_SWEEP ...]]] [-f FILE] location

          required arguments:
          • location : Directory in which the scripts (in tsv format) are all located OR File in which each line is the filename of a scripts.tsv file, followed by weight to assign for that file.
            optional arguments:
            • -p [PARAMETER_SWEEP [PARAMETER_SWEEP ...]], --parameter_sweep [PARAMETER_SWEEP [PARAMETER_SWEEP ...]] : Does a parameter sweep in range 0.5-2x of each object.field pair.
            • -f FILE, --file FILE : File name for output of parameter sweep.

      3. Brent_minimization: This script does a one-dimensional minimization on the model. It runs the findSim program on all tsv files in the specified directory with modifications of the selected parameters. It computes the weighted score for each run as the return value for the minimization function. While the Brent algorithm is serial, there are lots of indvidual tsv calculations for each step that can be done in parallel.

        python runAllParallel.py [-h] [-n NUMPROCESSES] [-m MODEL] [-s SCALE_PARAM SCALE_PARAM SCALE_PARAM] location

          required arguments:
          • location : Directory in which the scripts (in tsv format) are all located, OR File in which each line is the filename of a scripts.tsv file, followed by weight to assign for that file.
            optional arguments:
            • -p [PARAMETER_OPTIMIZE [PARAMETER_OPTIMIZE ...]], --parameter_optimize [PARAMETER_OPTIMIZE [PARAMETER_OPTIMIZE ...]] : Does a parameter optimization for each specified object.field pair.
            • -ps PRESETTLE PRESETTLE PRESETTLE, --presettle PRESETTLE PRESETTLE PRESETTLE Arguments : tsv_file, model_file, settle_time. Obtains values of all concentrations after a specified settle-time, so that all calculations for the optimization runs can be initialized to this presettled value. The tsv_file is to specify which subset of the model_file to use. This option is most useful in costly multiscale models.
            • -f FILE, --file FILE Optional : File name for output of parameter optimization.

      4. multi_param_minimization:This program is useful to 'improve' a model by comparing it systematically to all the relevant experiments, and tweaking parameters.

      Beware: if you have a bad model (which is incorrect about key biological interactions) then no amount of parameter tweaking will give you a good model!

      This program does a multi-parameter optimization using the Python implementation of the BGFR method with bounds. Like the Brent minimization, it runs the findSim program on all tsv files in the specified directory. It computes the weighted score for each run as the return value for the minimization function, which the BGFR algorithm then uses to choose its next test point. While the BGFR algorithm is serial, the _multi_param_minimization_ program supports parallelization as follows: one typically has large numbers of tsv files (experiments) to constrain each model. Thus there may be several indvidual tsv calculations for each step that can be done in parallel. This is highly advisable for this program because multi-parameter optimization usually requires hundreds of individual FindSim runs. There are many caveats to using multi-parameter optimization: the method is prone to getting stuck in local minima, you should NOT use too many parameters, you SHOULD set bounds to allowed parameters (which we do here), and so on. Most importantly, I remind you: A bad model cannot be parameter-tweaked into a good one.

        python multi_param_minimization.py [-h] [-n NUMPROCESSES] [-t TOLERANCE] [-m MODEL] [-p [PARAMETERS [PARAMETERS ...]]] [-f FILE] location

          required arguments:
          • location : Directory in which the scripts (in tsv format) are all located OR File in which each line is the filename of a scripts.tsv file, followed by weight to assign for that file.
            optional arguments:
            • -t TOLERANCE, --tolerance TOLERANCE : Tolerance criterion for completion of minimization
            • -p [PARAMETERS [PARAMETERS ...]], --parameters [PARAMETERS [PARAMETERS ...]] : Parameter to vary.
              Each is defined as an object.field pair.
              The object is defined as a unique MOOSE name, typically name or parent/name. The field is separated from the object by a period.
              The field may be
                - concInit for molecules,
                - Kf, Kb, Kd or tau for reactions, and
                - Km or kcat for enzymes.
              One can specify more than one parameter for a given reaction or enzyme. It is advisable to use Kd and tau for reactions unless you have a unidirectional reaction.
            • -f FILE, --file FILE Optional : File name for output of parameter minimization

    TSV file reference for kinds of experiments supported by FindSim:

    Filename
    What it does
  • ts_j4d.tsv
    • Time-series experiment for chemical signaling pathway
  • ts_norm_m3b.tsv
    • Time-series experiment, readout normalized to max value
  • ts_ratio_t2a.tsv
    • Time-series experiment, readout reported as ratio to baseline.
  • dr_j2c.tsv
    • Dose-response curve for chemical signaling pathway.
  • dr_ratio_b2c.tsv
    • Dose-response curve plotted as ratio with respect to a reference measurement.
  • bc_ratio_sb8.tsv
    • BarChart experiment where each bar is the outcome of a set of defined inputs, reported as the ratio to a reference measurement.
  • dp.tsv
    • Direct Parameter comparison of Km and kcat for a couple of enzymes in the model.
  • dp_Kd_tau.tsv
    • Direct Parameter comparison for Kd and tau
  • epsp.tsv
    • Electrophysiology experiment measuring excitatory post-synaptic potential.
  • epsp_ratio.tsv
    • Electrophysiology experiment measuring excitatory post-synaptic potential, reported as ratio to baseline.
  • epsc.tsv
    • Electrophysiology experiment measuring excitatory post-synaptic current.
  • epsc_ratio.tsv
    • Electrophysiology experiment measuring excitatory post-synaptic current, reported as ratio to baseline
  • epsp.tsv
    • Electrophysiology experiment measuring excitatory field potential.
  • iclamp_hh13.tsv
    • Electrophysiology experiment doing a current-clamp experiment on the classic Hodgkin-Huxley model, comparing with Figure 13 from their paper.
  • vclamp_hh.tsv
    • Electrophysiology experiment doing a voltage-clamp experiment on the classic Hodgkin-Huxley model