Merge pull request #82 from NeuroML/pg_updates

Changes from #79 and minor tweaks

source/Userdocs/Conventions.md

@@ -0,0 +1,40 @@
+(userdocs:conventions)=
+# Conventions
+
+This page documents various conventions in use in NeuroML.
+
+In general, please prefer underscores `_` instead of spaces wherever possible, in filenames and ids.
+
+(userdocs:conventions:files)=
+## File naming
+
+When naming different NeuroML files, we suggest the following suffixes:
+
+- `channel.nml` for NeuroML files describing ion channels, for example: `Na.channel.nml`
+- `cell.nml` for NeuroML files describing cells, for example: `hh.cell.nml`
+- `synapse.nml` for NeuroML files describing synapses, for example: `AMPA.synapse.nml`
+- `net.nml` for NeuroML files describing networks of cells, for example: `excitatory.net.nml`
+
+For LEMS files that describe simulations of NeuroML models ({ref}`"LEMS Simulation files" <userdocs:lemssimulation>`), we suggest that:
+
+- file names start with the `LEMS_` prefix,
+- file names end in `xml`
+
+For example `LEMS_HH_Simulation.xml`.
+
+(userdocs:conventions:segments)=
+## Neuron segments
+
+When naming segments in multi-compartmental neuron models, we suggest the following prefixes:
+
+- `axon_` for axonal segments
+- `dend_` for dendritic segments
+- `soma_` for somatic segments
+
+There are 3 specific recommended names for segment groups which contain **ALL** of the somatic, dendritic or axonal segments
+
+- `axon_group` for the group of all axonal segments
+- `dend_group` for the group of all dendritic segments
+- `soma_group` for the group of all somatic segments
+
+Ideally every segment should be a member of one and only one of these groups. 

source/Userdocs/LEMSSimulation.md

@@ -1,7 +1,7 @@
 (userdocs:lemssimulation)=
 # LEMS Simulation files
 
-For many users, the most obvious place that LEMS is used is in the LEMS Simulation file (usually LEMS_*.xml).
+For many users, the most obvious place that LEMS is used is in the LEMS Simulation file (usually {ref}`LEMS_*.xml <userdocs:conventions:files>`).
 
 ## Specification of format
 
@@ -10,13 +10,15 @@ See <a href="Schemas/Simulation.html">here</a> for definition of the main elemen
 
 ## Quantities and paths
 
-Specifying the quantities to save/display in a LEMS Simulation file is an important and sometimes confusing process. There is a {ref}`dedicated page <userdocs:quantitiesandpaths>` on quantities and paths in LEMS and NeuroML2.
+Specifying the quantities to save/display in a LEMS Simulation file is an important and sometimes confusing process. There is a {ref}`dedicated page <userdocs:quantitiesandrecording>` on quantities and paths in LEMS and NeuroML2.
 
 
 ## What about SED-ML?
 
 The Simulation Experiment Description Markup Language ([SED-ML](https://sed-ml.org/)) is used by a number of other initiatives such as SBML for specifying simulation setup, execution and basic analysis.
 
+We chose to have a LEMS specific format for specifying simulations in NeuroML2 as opposed to natively supporting SED-ML, mainly because of the tight link to the LEMS language and {ref}`jLEMS <jLEMS>` package, i.e. all of the NeuroML2 elements and elements in a LEMS simulation file have underlying definitions in the LEMS language. However it is possible to convert the LEMS simulation to the equivalent in SED-ML.
+
 ### Exporting LEMS simulation descriptions to SED-ML
 
 

source/Userdocs/NML2_examples/HH_example_cell.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="cell">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="cell">
     <notes>HH cell</notes>
     <include href="HH_example_na_channel.nml"/>
     <include href="HH_example_k_channel.nml"/>

source/Userdocs/NML2_examples/HH_example_k_channel.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="k_channel">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="k_channel">
     <notes>k channel for HH neuron</notes>
     <ionChannelHH id="k_channel" species="k" conductance="10pS">
         <notes>Potassium channel for HH cell</notes>

source/Userdocs/NML2_examples/HH_example_leak_channel.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="leak_channel">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="leak_channel">
     <notes>leak channel for HH neuron</notes>
     <ionChannelHH id="leak_channel" conductance="10pS">
         <notes>Leak conductance</notes>

source/Userdocs/NML2_examples/HH_example_na_channel.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="na_channel">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="na_channel">
     <notes>Na channel for HH neuron</notes>
     <ionChannelHH id="na_channel" species="na" conductance="10pS">
         <notes>Sodium channel for HH cell</notes>

source/Userdocs/NML2_examples/HH_example_net.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="network">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="network">
     <notes>HH cell network</notes>
     <include href="HH_example_cell.nml"/>
     <pulseGenerator id="pg" delay="100ms" duration="100ms" amplitude="0.08nA">

source/Userdocs/NML2_examples/LEMS_HH_single_compartment_example_sim.xml

@@ -2,7 +2,7 @@
 
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v0.5.11 (libNeuroML v0.2.55)
+        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.57)
 
      -->
 

source/Userdocs/NML2_examples/LEMS_example-single-izhikevich2007cell-sim.xml

@@ -2,7 +2,7 @@
 
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.56)
+        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.57)
 
      -->
 

source/Userdocs/NML2_examples/LEMS_example_izhikevich2007network_sim.xml

@@ -2,7 +2,7 @@
 
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.56)
+        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.57)
 
      -->
 

source/Userdocs/NML2_examples/LEMS_olm_example_sim.xml

@@ -2,7 +2,7 @@
 
     <!-- 
 
-        This LEMS file has been automatically generated using PyNeuroML v0.5.11 (libNeuroML v0.2.55)
+        This LEMS file has been automatically generated using PyNeuroML v0.5.13 (libNeuroML v0.2.57)
 
      -->
 

source/Userdocs/NML2_examples/olm.cell.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="oml_cell">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="oml_cell">
     <include href="olm-example/leak_chan.channel.nml"/>
     <include href="olm-example/HCNolm.channel.nml"/>
     <include href="olm-example/Kdrfast.channel.nml"/>

source/Userdocs/NML2_examples/olm_example_net.nml

@@ -1,4 +1,4 @@
-<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.1.xsd" id="network">
+<neuroml xmlns="http://www.neuroml.org/schema/neuroml2"  xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.neuroml.org/schema/neuroml2 https://raw.github.com/NeuroML/NeuroML2/development/Schemas/NeuroML2/NeuroML_v2.2.xsd" id="network">
     <notes>OLM cell network</notes>
     <include href="olm.cell.nml"/>
     <pulseGenerator id="pg_olm" delay="100ms" duration="100ms" amplitude="0.08nA">

source/Userdocs/Paths.md

@@ -0,0 +1,53 @@
+(userdocs:paths)=
+# Paths
+
+Since NeuroMLv2 and LEMS are both XML based, entities in models and simulations must be referred to using *paths*.
+This page documents how paths can be constructed, and how they can be used to refer to entities in NeuroML/LEMS based models and simulations.
+
+(userdocs:constructingpaths)=
+## Constructing paths
+Paths start from any element and ascend/descend to refer to the entity that is to be referenced.
+
+The `.` and `..` path constructs are special constructs that mean "the current node" and "the parent node" respectively.
+
+For example, in the {ref}`Izhikevich network example <userdocs:getting_started:single_example>`, the network is defined in NeuroML like this:
+```{code-block} xml
+    <network id="IzNet">
+        <population id="IzPop0" component="iz2007RS0" size="5">
+            <property tag="color" value="0 0 .8"/>
+        </population>
+        <population id="IzPop1" component="iz2007RS0" size="5">
+            <property tag="color" value=".8 0 0"/>
+        </population>
+        <projection id="proj" presynapticPopulation="IzPop0" postsynapticPopulation="IzPop1" synapse="syn0">
+            <connection id="0" preCellId="../IzPop0[0]" postCellId="../IzPop1[0]"/>
+            <connection id="1" preCellId="../IzPop0[0]" postCellId="../IzPop1[1]"/>
+            <connection id="2" preCellId="../IzPop0[0]" postCellId="../IzPop1[2]"/>
+            ...
+        </projection>
+        <explicitInput target="IzPop0[0]" input="pg_0"/>
+        <explicitInput target="IzPop0[1]" input="pg_1"/>
+        <explicitInput target="IzPop0[2]" input="pg_2"/>
+        <explicitInput target="IzPop0[3]" input="pg_3"/>
+        <explicitInput target="IzPop0[4]" input="pg_4"/>
+    </network>
+</neuroml>
+```
+Here, in the `explicitInput` node, we need to refer to neurons of the `IzPop0` `population` node.
+Since `explicitInput` and `population` are *siblings* (both have the `IzNet` `network` as *parent*), they are at the same *level*.
+Therefore, in `explicitInput`, one can refer directly to `IzPop0`.
+
+The `projection` and `population` nodes are also *siblings* and therefore are at the same level.
+So, in the `projection` tag also, we can refer to the `population` nodes directly.
+The `connection` nodes, however, are *children* of the `projection` node.
+Therefore, for the `connection` nodes, the `population` nodes are at the *parent* level, and we must use `../IzPop0` to refer to them.
+
+`../IzPop0` means "go up one level to the parent level (to `projection`) and then refer to `IzPop0`".
+`../` can be used as many times as required and wherever required in the path.
+For example, `../../../` would mean "go up three levels".
+
+Additionally, when constructing the path:
+
+- for any `child` elements, the *name* of the element should be used in the path
+- for `children` elements, the *id* of the element should be used in the path
+- for elements that have a `size` attribute like {ref}`population <schema:population>`, individual elements should be referred to using the `[]` operator

source/Userdocs/QuantitiesAndRecording.md

@@ -0,0 +1,27 @@
+(userdocs:quantitiesandrecording)=
+# Quantities and recording
+
+```{note}
+TODO: document `list_exposures()` once https://github.com/NeuroML/pyNeuroML/pull/118 is merged.
+```
+```{note}
+TODO: document `list_recording_paths()` once https://github.com/NeuroML/pyNeuroML/pull/118 is merged.
+```
+
+In LEMS and NeuroML, `quantities` from all `exposures` and all `events` can be recorded by referring to them using {ref}`paths <userdocs:paths>`.
+For examples, please see the {ref}`Getting Started with NeuroML <userdocs:getting_started_neuroml>` section.
+
+(userdocs:quantitiesandrecording:events)=
+## Recording events
+
+In NeuroML, all `event`s can be recorded to files declared using the {ref}`EventOutputFile <schema:eventoutputfile>` component.
+Once an `EventOutputFile` has been declared, events to record can be selected using the {ref}`EventSelection <schema:eventselection>` component.
+
+{ref}`pyNeuroML <pyneuroml>` provides the [create_event_output_file](https://pyneuroml.readthedocs.io/en/development/pyneuroml.lems.html?highlight=add_selection_to_event_output_file#pyneuroml.lems.LEMSSimulation.LEMSSimulation.create_event_output_file) function to create a `EventOutputFile` to record `events` to, and the [add_selection_to_event_output_file](https://pyneuroml.readthedocs.io/en/development/pyneuroml.lems.html?highlight=add_selection_to_event_output_file#pyneuroml.lems.LEMSSimulation.LEMSSimulation.add_selection_to_event_output_file) function to record `events` to the declared data file(s).
+
+(userdocs:quantitiesandrecording:exposures)=
+## Recording quantities from exposures
+In NeuroML, all `quantities` can be recorded to files declared using the {ref}`OutputFile <schema:outputfile>` component.
+Once the `OutputFile` has been declared, `quantities` to record can be selected using the {ref}`OutputColumn <schema:outputcolumn>` component.
+
+{ref}`pyNeuroML <pyneuroml>` provides the [create_output_file](https://pyneuroml.readthedocs.io/en/development/pyneuroml.lems.html?highlight=add_selection_to_event_output_file#pyneuroml.lems.LEMSSimulation.LEMSSimulation.create_event_output_file) function to create a `OutputFile` to record `quantities` to, and the  [add_column_to_output_file](https://pyneuroml.readthedocs.io/en/development/pyneuroml.lems.html?highlight=add_selection_to_event_output_file#pyneuroml.lems.LEMSSimulation.LEMSSimulation.create_event_output_file) function to select `quantities` to record to the declared data file(s).

source/Userdocs/SingleNeuronExample.md

@@ -37,6 +37,11 @@ We will look at the pre-defined entities, and how NeuroML may be extended later
 For now, we limit ourselves to defining a new `Izhikevich2007Cell` (definition of this {ref}`here <schema:izhikevich2007Cell>`).
 The Izhikevich neuron model can take sets of parameters to show different types of spiking behaviour.
 Here, we define an instance of the general Izhikevich cell using parameters that exhibit regular spiking.
+
+```{admonition} Units in NeuroML
+NeuroML defines a {ref}`standard set of units <schema:neuromlcoredimensions>` that can be used in models.
+Learn more about units and dimensions in NeuroML and LEMS {ref}`here <userdocs:unitsanddimensions>`.
+```
 Once defined, we add this to our `NeuroMLDocument`.
 ```{literalinclude} ./NML2_examples/izhikevich-single-neuron.py
 ----
@@ -212,6 +217,7 @@ We will limit ourselves to the bits necessary to simulate our Izhikevich neuron
 The following lines of code instantiate a new simulation with certain simulation parameters: `duration`, `dt`, `simulation_seed`.
 Additionally, they also define what information is being recorded from the simulation.
 In this case, we create an output file, and then add a new column to record the membrane potential `v` from our one neuron in the one population in it.
+You can read more about recording from NeuroML simulations {ref}`here <userdocs:quantitiesandrecording>`.
 
 Finally, like we had saved our NeuroML model to a file, we also save our LEMS document to a file.
 

source/Userdocs/UnitsAndDimensions.md

@@ -5,13 +5,15 @@ Support for dimensional quantities is a fundamental (and essential) feature of N
 
 The basic rules are:
 
-```{admonition} Units and Dimensions
-Specify the **dimensions** of quantities in LEMS
+- specify the **dimensions** of quantities in LEMS
+- use compatible **units** defined in the NeuroML schema in NeuroML models.
 
-Use any<sup>*</sup> compatible **units** in NeuroML
+The main motivation for this is that fundamental expressions for defining a model are independent of any particular units.
+For example, Ohm's law, **V = I * R** relates to quantities with dimensions voltage, current and resistance, not millivolts, picoamps, ohms, etc.
 
-```
+Users can therefore use a wide range of commonly used units for each dimension defined in the {ref}`standard unit and dimension definitions <schema:neuromlcoredimensions>` of NeuroML 2 without worrying about conversion factors.
 
-The main motivation for this is that fundamental expressions for defining a model are independent of any particular units. For example, Ohm's law, **V = I * R** relates to quantities with dimensions voltage, current and resistance, not millivolts, picoamps, ohms, etc.
+Additionally, please keep in mind that:
 
-<sup>*</sup> While a wide range of commonly used units for each dimension are supported, they need to be present in the {ref}`standard unit and dimension definitions <schema:neuromlcoredimensions>` of NeuroML 2. 
+- all quantities are saved and {ref}`recorded <userdocs:quantitiesandrecording>` in SI Units
+- when plotting data using NeuroML/LEMS using the {ref}`Line <schema:line>` component, users can use the `scale` parameter to convert quantities to other units.

source/Userdocs/UsingNeuroMLv2AndLEMS.md

@@ -1,9 +1,10 @@
 (userdocs:usingnml2lems)=
-# Using NeuroML 2 and jLEMS
+# Using NeuroML 2 and LEMS
 
 While the {ref}`tutorials <userdocs:getting_started_neuroml>` cover many of the key points of using LEMS with NeuroML, there are some points which require further explanation:
 
+- {ref}`What are the conventions/best practices to follow in naming NeuroML/LEMS files/elements? <userdocs:conventions>`
 - {ref}`How are units and dimensions handled in NeuroML and LEMS? <userdocs:unitsanddimensions>`
 - {ref}`How do I use a LEMS Simulation file to specify how to execute a NeuroML model? <userdocs:lemssimulation>`
 - {ref}`How can I extend NeuroML model to include new types using LEMS? <userdocs:extending>`
-- {ref}`What is the correct format/usage of paths and quantities in NeuroML and LEMS? <userdocs:quantitiesandpaths>`
+- {ref}`What is the correct format/usage of paths and quantities in NeuroML and LEMS? <userdocs:paths>`

source/_toc.yml

@@ -36,9 +36,11 @@ parts:
         - file: Userdocs/NeuroMLv1
     - file: Userdocs/UsingNeuroMLv2AndLEMS
       sections:
+        - file: Userdocs/Conventions
         - file: Userdocs/UnitsAndDimensions
+        - file: Userdocs/Paths
+        - file: Userdocs/QuantitiesAndRecording
         - file: Userdocs/LEMSSimulation
-        - file: Userdocs/QuantitiesAndPaths
         - file: Userdocs/ExtendingNeuroMLv2WithLEMS
     - file: Userdocs/Software/Software
       sections: