Units in NMODL

[Robert Claar]

Hello,

I have used NEURON to successfully replicate a model ran in XPPAUT. This model is the product of models going back to the 1970s and I have finally traced back through all the prior papers and have done a ton of dimensional analysis to get the units for all my model variables.

When attempting to run modlunit on one of my mod files, it complains that

Code: Select all

ikb must have the units, nanoamp, instead of fA.

Based on the values of the currents in my model, nanoamps or microamps would likely be more appropriate but I am trying to keep the structure of the equation and the parameters similar to the source model if possible. The units tutorial states

New units can be defined in terms of default units and previously defined units by placing definitions in the UNITS block.

I checked the nrnunits.lib file and see that the femto prefix is there. In my units block I also tried variations like

Code: Select all

(femtoamp) = (0.000001 nanoamp)
(fA) = (femptoamp)

Do all point currents need to be in units of nanoamp? At the bottom of the units tutorial it states that point currents are checked for units of nanoamps, but it doesn't explicitly state that other units are not allowed if they are defined properly.

I also have other units that are not NEURON default units like picomolar, femtofarad, picoseimen, etc that I would like to define. The bottom part of the tutorial I just mentioned also states that concentration is checked for units of milli/liter, so for picomolar would I do pico/liter?

This is my UNITS block so so far in case it is helpful

Code: Select all

UNITS{
    (mV) = (millivolt)
    (pS) = (picosiemens)
    (molar) = (/liter)
    (mM) = (millimolar)
    (uM) = (micromolar)
    (pL) = (picoliter)
    (fF) = (femtofarad)
    (fA) = (femtoamp)
    sec_to_ms = (s) -> (ms)
}

Any help is greatly appreciated!

[ted]

I can't say I have ever seen a units declaration in the form
sec_to_ms = (s) -> (ms)
but then I haven't seen all NMODL code that has ever been written. Who knows, this might be the wave of the future.

If a point process generates a current, that current must be in nanoamps. If a density (aka distributed) mechanism generates a current, the units must be milliamps per square centimeter. Declarations in a UNITS block have two primary purposes: they can help make your NMODL code more readable (by enabling use of common abbreviations e.g. nA, mA, mV), and they are used by tools like modlunit that check NMODL code for for consistency of units.

A side comment: It's OK for intermediate variables to have whatever units you like, but (1) you may have to embed scale factors into formulas in order to satisfy units checking tools, and (2) any variables that have to "play well" with NEURON's computational engine must be in the units that NEURON expects if you want to avoid complaints from modlunit and you like your calculations to produce incorrect numerical values.

[Robert Claar]

Understood, thank you Ted.

As for the conversion factor syntax, I actually got that from the units tutorial from the NEURON documentation I linked in my original post. I found that it was the most readable and the tutorial stated it was the most clear way to define conversion factors.

...conversion factors ( dimensionless factors used to convert between conformable units) can most clearly be written

Code: Select all

UNITS {
    foot2inch = (foot) -> (inch)
}

[Robert Claar]

Also I have two follow-up questions regarding the proper way to use UNITSOFF and UNITSON and for best practices for defining custom units.

Part of my computational model involves a large equation that has been broken up into several smaller equations for practicality reasons. These smaller equations don't have any physical meaning and I would rather not worry about units for each of them as I think it could lead to more confusion in the future. These equations are just a subset of those included in my model so I tried to turn units off at first by using UNITSOFF and UNITSON inside my ASSIGNED and BREAKPOINT blocks like (I'll only show an example of the ASSIGNED block here for brevity, but I did the same thing with these variables corresponding equations inside the BREAKPOINT block)

Code: Select all

ASSIGNED{
	var1 (units)
	var2 (units)
	...
	UNITSOFF
	: Here are where the smaller equation variables are declared that I don't want to track units for
	no_unit_var1
	no_unit_var2
	...
	UNITSON
	varn (units)

This gave me the syntax error

Code: Select all

Illegal block at line 136 in file ... 
UNITSOFF
	^

I got modlunit to run without warning by using multiple ASSIGNED and BREAKPOINT blocks like

Code: Select all

ASSIGNED{
	var1 (units)
	var2 (units)
	...
	varn (units)
}
UNITSOFF
ASSIGNED{
	: Here are where the smaller equation variables are declared that I don't want to track units for
	no_unit_var1
	no_unit_var2
	...
	no_unit_varn
}
UNITSON

But I know just because there is no warning does not mean that I did this properly. What are best practices for using UNITSOFF and UNITSON for just a subset of your variables and model equations?

Another part of my model is a kinetic model for insulin granule exocytosis. This kinetic model for exocytosis includes several steps and each step has a corresponding compartment containing a certain number of insulin granules. For each compartment there is a differential equation describing how the amount of insulin-containing granules are changing. One step in the model tracks the amount of insulin-containing granules in the ready-releasable state and this determines the overall insulin secretion rate from the cell. Experiments using amperommetry observed estimates of ~1.6 amol of insulin per granule and this is used as a conversion factor to convert from granules to picomoles of insulin (0.0016 picomoles/granule).

The units for these variables are very important for the model but "moles" is not a valid unit as it is a constant in the units database and granules is also not a valid unit. What would be the best way to convey the units for these variables? Right now I have them as dimensionless and have inserted comments to explain what the variables represent and what the units are but I am wondering if there is a better way.

Any advice is greatly appreciated!

[ted]

Good questions. Also good to see that you're resolving documentation ambiguities by testing to see what syntax works and what doesn't.

You might find it helpful to read chapter 9 of The NEURON Book. If you don't have the book, get this draft instead https://www.neuron.yale.edu/ftp/ted/boo ... xedref.pdf. You'll see lots of best practice examples for many things.

WRT UNITSOFF...UNITSON in particular: don't do that in a variable declaration block (PARAMETER, ASSIGNED, STATE). Instead, to declare some variable foo but not specify its units, just write
foo
or
foo (1)

WRT insulin granule exocytosis--if the model is written in terms of number of granules that exist/are stored/are in a releasable pool/have been released etc., why bother assigning the molar content of a granule? Just deal with integers. Declare the variable names as STATEs or ASSIGNED, or even PARAMETERs. For example, if there is an upper limit on the total number of granules that can exist at one time, you might declare that in the PARAMETER block as
nmax
or even
nmax (1)

[Robert Claar]

Thanks for your response, I'll look into that chapter of the NEURON book.

WRT to the UNITSOFF and UNITSON: I have plenty of variables in my model that don't have units for which I am using the approach

Code: Select all

foo ()

Just so it is explicit that I didn't forget to put units, but that the variable is dimensionless. The issue with my case is that these intermediate variables created by breaking up this massive equation are in terms of variables and parameters that do have meaningful units so modlunit throws a warning if I try to leave them unitless and I think calculating what their units would be would be misleading. The big equation used is to calculate the amount of phosphofructokinase (PFK) that is in an active state and it depends on the concentrations of other glycolytic molecules and there are 16 states it could be in. Maybe there is another way I could break up the expression but I figured the easiest way would be to leave it as is, add a detailed comment, and turn units off but I'm still not sure if there is a way to do that for only a subset of ASSIGNED variables or PARAMETERs.

WRT the granule exocytosis: These variables (the number of granules in each stage of the exocytotic cascade) are STATEs and I have figured out a way that clearly communicates what the terms in the insulin secretion equation represent and have given them suitable units.

Thanks again for the help!

[Robert Claar]

Nevermind, I realized that you already answered my question regarding UNITSOFF and UNITON. I see now that I needed to use UNITSON and UNITSOFF in my BREAKPOINT block instead of ASSIGNED. I assumed that I would do it in ASSIGNED because that is where I declare the units but it makes sense that they can't be checked until the program gets to the equation where they are used.