From e5ba7e4617c60316b1c59b3996d3955787aa0f5a Mon Sep 17 00:00:00 2001 From: Sam Yates Date: Thu, 28 Mar 2019 19:01:51 +0100 Subject: [PATCH] READMEs for validation tests. (#59) * Add validation test-specific README.md * Add README.md detailing model dynamics, parameter values, and acceptance criteria to the two existing tests. * Remove stale validation/README.md. * Fix ncell parameter inconsistency in rc-exp2syn-spike. --- validation/README.md | 72 ------------------- validation/rc-exp2syn-spike/README.md | 58 +++++++++++---- validation/rc-exp2syn-spike/default.param | 1 + .../generate-rc-exp2syn-spike | 3 +- validation/rc-expsyn/README.md | 35 +++++++++ 5 files changed, 84 insertions(+), 85 deletions(-) delete mode 100644 validation/README.md create mode 100644 validation/rc-expsyn/README.md diff --git a/validation/README.md b/validation/README.md deleted file mode 100644 index e5d1e4a..0000000 --- a/validation/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# Layout / conventions for validation tests. - -Each _model_ lives in its own subdirectory under `validation/`. -This document will detail the structure of tests to be run -under a model `example`. - -## Model configuration - -A model configuration comprises a model and an optional parameter set. - -Parameter sets are simple text files containing a series of _key_=_value_ -pairs, terminated by newlines. A parameter set named `set` for the model -`example` will be found in the file `example/set.param`. - -A model configuration is referred to by '_model_/_paramsetname_'; '_model_' -alone is a shorthand for '_model_/default'. - - -## Run scripts - -A 'run script' is an executable script that runs the model and validation for a -particular simulator. It takes an optional flag '-r' followed by two arguments: -the name of the simulator and the name of the parameter set. - -Run scripts attempt to change to the directory in which the script resides, and then: - - 1. Make any required cache and output directories. - - 2. Run the simulator-specific model script. Conventionally, this will be a script - in the current directory called 'run-_sim_', and will take an output file in the - output directory as the first argument, followed by a key=value parameter settings - taken from the .param file. - - 3. Generate any required reference data for comparison, optionally checking for - cached reference data. If '-r' was given to the run script, force the regeneration - of any cached reference data. - - 4. Run an analysis script on the simulator model output + reference data, directing output - to the output subdirectory. - - 5. Run a pass/fail test on the generated analysis data, and report result. - -The run scripts will generally use helper functions defined in `model_common.sh`. -These require the `ns_base_path` variable to be set to the nsuite root directory. - - * `model_setup` - - Takes three or four arguments: the name of the model, an optional '-r' to indicate that - reference data should be regenerated, the name of the simulator, and the name of parameter set. - - * Defines variables `model_name`, `model_refresh`, `model_sim`, `model_param` - from the arguments. - - * Sets the corresponding `model_cache_dir` and `model_output_dir` paths, and creates - these directories if they do not exist. - - * Reads the parameter data into `model_param_data`, and sets `model_status_path` - to the path where the final pass or fail result should be written. - - * Prefixes the PATH variable with the current working directory and the nsuite - install and common binary directories. - - * `model_find_cacheable` - - Looks for file in the current directory, and then in the model cache directory. - Prints the path to the local or else cached file, and returns non-zero if the - file does not exist. - - * `model_notify_pass_fail` - - Takes one parameter, 0 for pass or non-zero for fail (corresponding to e.g. the - exit status of a test). It reports pass or fail status to stdout. diff --git a/validation/rc-exp2syn-spike/README.md b/validation/rc-exp2syn-spike/README.md index f9fdf70..2543540 100644 --- a/validation/rc-exp2syn-spike/README.md +++ b/validation/rc-exp2syn-spike/README.md @@ -1,15 +1,49 @@ -Placeholder doc: expand and move to nsuite docs. +Model rc-exp2syn-spike +====================== -* Model comprises two cells, each with a single compartment -soma and passive channels together with a double-exponential -synapse. -* The synpase on the first cell is triggered at t = 0. -* The synapse on the second cell is triggered by a spike generated -on the first cell via a connection with configurable delay. -* Times to first threshold crossing (spike) on each cell is recorded. +This model comprises a single source cell connected to a number of +target cells via a range of delays. -Pass criterion: checks difference in spike times against -a supplied `max_error` parameter, which hand-wavingly is -set to three times dt. (Realistically, the pass criterion -should be more relaxed.) +Each cell has a single compartment with passive dynamics and a +single double exponential synapse. The source cell, with label +zero, has the synapse triggered at time _t_ = 0. +When a cell membrane potential crosses the threshold value, it +will generate a spike; the spike from the source cell is +delivered to the target cell _k_ with quasirandom delay +_d_ = _d₀_ + { _k_ φ }, where φ = (√ 5 − 1)/2. + +Each cell is equivalent to an RC circuit with two exponentially +decaying current sources of opposite sign and different time +constants. + +The fixed electrical parameters are as follows: + +| Parameter | Value | +|----------------------------|---------| +| Total membrane resistance | 100 MΩ | +| Total membrane capacitance | 0.01 nF | +| Reversal potential | -65 mV | +| Initial membrane voltage | -65 mV | +| Synaptic time constants | 0.5 ms | +| | 4.0 ms | + +Test parameters +--------------- + + +| Parameter | Interpretation | +|-------------|-----------------------------------------------------| +| `dt` | maximum simulation integration timestep [ms] | +| `g0` | initial current of exponential current sources [µS] | +| `mindelay` | minimum connection delay _d₀_ [ms] | +| `threshold` | spiking threshold [mV] | +| `ncell` | total number of cells (including source) | +| `max_error` | acceptance threshold for spike time differences | + +Acceptance critera +------------------ + +The recorded spike times from each cell should differ from the +reference times by at most 3·_dt_. (This is set explicitly as +the `max_error` test parameter.) diff --git a/validation/rc-exp2syn-spike/default.param b/validation/rc-exp2syn-spike/default.param index b6b3eed..0de5a0e 100644 --- a/validation/rc-exp2syn-spike/default.param +++ b/validation/rc-exp2syn-spike/default.param @@ -1,3 +1,4 @@ +ncell=101 dt=0.01 g0=0.1 mindelay=3.3 diff --git a/validation/rc-exp2syn-spike/generate-rc-exp2syn-spike b/validation/rc-exp2syn-spike/generate-rc-exp2syn-spike index 58b3fa0..80d57f4 100755 --- a/validation/rc-exp2syn-spike/generate-rc-exp2syn-spike +++ b/validation/rc-exp2syn-spike/generate-rc-exp2syn-spike @@ -28,9 +28,10 @@ nsamp = 300 ts = np.linspace(0., tend, num=nsamp) output, params = stdarg.parse_run_stdarg() -param_vars = ['g0', 'mindelay', 'threshold'] +param_vars = ['g0', 'mindelay', 'threshold', 'ncell'] for v in param_vars: if v in params: globals()[v] = params[v] +ncell = int(ncell) # Voltage on one cell given by ODE: # diff --git a/validation/rc-expsyn/README.md b/validation/rc-expsyn/README.md new file mode 100644 index 0000000..a23021a --- /dev/null +++ b/validation/rc-expsyn/README.md @@ -0,0 +1,35 @@ +Model rc-expsyn +=============== + +The model describes a single compartment cell with passive dynamics and +a single exponential synapse, that is triggered at time t = 0. + +This is equivalent to an RC circuit with an exponentially decaying +current source. + +The fixed electrical parameters are as follows: + +| Parameter | Value | +|----------------------------|---------| +| Total membrane resistance | 100 MΩ | +| Total membrane capacitance | 0.01 nF | +| Reversal potential | -65 mV | +| Initial membrane voltage | -65 mV | +| Synaptic time constant | 1 ms | + +Test parameters +--------------- + + +| Parameter | Interpretation | +|-----------|----------------| +| `dt` | maximum simulation integration timestep [ms] | +| `g0` | synaptic current at time _t_ = 0 [µS] | + + +Acceptance critera +------------------ + +The relative error in membrane voltage should be within 1% of +the reference value at time _t_ = 10 ms. +