=============
Notes on LFPy
=============

Morphology files
================

Cell morphologies can be specified manually in a ``.hoc`` file. For a simple example, see
``examples/morphologies/example_morphology.hoc``. Note the following conventions:

-  Sections should be named according to the following scheme:
   
   -  ``soma*[]`` for somatic sections, ``*`` is optional
   -  ``dend*[]`` for dendritic sections
   -  ``apic*[]`` for apical dendrite sections
   -  ``axon*[]`` for axonal sections
-  Sections must be defined as types Section or SectionList (as ``soma[1]`` or ``soma``)


Also the morphologies exported from the NEURON simulator 
(for example using Cell Builder -> Export) should
work with LFPy, but some times ``create soma`` may have to be corrected to
``create soma[1]`` directly in the files.
Multi-sectioned somas may occurr e.g., due to faulty conversion from NeuroLucida or SWC format,
however, we recommend that these files are corrected. It may not affect the predictions of intracellular
voltages, but have implications for predictions of extracellular potentials. We usually assume
that the soma is a single compartment and that it is the root section for all other sections.


NEURON convention for creating morphology files in ``hoc``:
::

    /* ----------------------------------------------------
    example_morphology.hoc

    This hoc file creates a neuron of the following shape:

                \       
                 \     
                  \   /
                   \ /
                    V
                    |
                    |
                    |
                    O
                
    Note the conventions:
     - use soma for the soma compartment,
     - use a name starting with dend or apic for the dendrites.
    -----------------------------------------------------*/


    create soma[1]
    create dend[3]

    soma[0] {
        pt3dadd(0, 0, 0, 25)
        pt3dadd(0, 0, 35, 25)
    }

    dend[0] {
        pt3dadd(0, 0, 35, 5)
        pt3dadd(0, 0, 150, 5)
    }

    dend[1] {
        pt3dadd(0, 0, 150, 2)
        pt3dadd(-50, 20, 200, 1)
    }

    dend[2] {
        pt3dadd(0, 0, 150, 2)
        pt3dadd(30, 0, 160, 2)
    }

    connect dend[0](0), soma[0](1)
    connect dend[1](0), dend[0](1)
    connect dend[2](0), dend[0](1)

Other file formats
------------------

Support for SWC, NeuroLucida3 and NeuroML morphology file formats is added in LFPy, but consider this
an experimental feature as the functionality is not properly tested. If there is something wrong with
the files, strange behaviour may occur or LFPy may even fail
to load the desired morphology.


Using NEURON NMODL mechanisms
=============================

Custom NEURON mechanisms can be loaded from external ``.hoc``- or ``.py``-files - see ``example2.py`` and ``example3.py``.
Python function definitions with arguments can also be given as input to the ``Cell``-class, specifying model specific conductances etc.
Remeber to compile any ``mod`` files (if needed) using ``nrnivmodl`` (or ``mknrdll`` on Windows).

These model specific declarations is typically run after the ``Cell``-class try to read the morphology file,
and before running the ``_set_nsegs()`` and ``_collect_geometry()`` procedures. Hence, code that modifies the
segmentation of the morphology will affect the properties of the instantiated ``LFPy.Cell`` object.


Units
=====

Units follow the NEURON conventions found `here <https://www.neuron.yale.edu/neuron/static/docs/units/unitchart.html>`_.
The units in LFPy for given quantities are:

+----------------------------+-----------+
| Quantity                   | Unit      |
+============================+===========+
| Potential                  | [mV]      |
+----------------------------+-----------+
| Current                    | [nA]      |
+----------------------------+-----------+
| Conductance                | [S/cm2]   |
+----------------------------+-----------+
| Extracellular conductivity | [S/m]     |
+----------------------------+-----------+
| Capacitance                | [μF/cm2]  |
+----------------------------+-----------+
| Dimension                  | [μm]      |
+----------------------------+-----------+
| Synaptic weight            | [µS]      |
+----------------------------+-----------+
| Current dipole moment      | [nA µm]   |
+----------------------------+-----------+
| Magnetic field (H)         | [nA/µm]   |
+----------------------------+-----------+
| Permeability (µ)           | [T m/A]   |
+----------------------------+-----------+

Note: resistance, conductance and capacitance are usually specific values, i.e per membrane area (lowercase r_m, g, c_m)
Depending on the mechanism files, some may use different units altogether, but this should be taken care of internally by NEURON.


Contributors
============

LFPy was developed by (`as per commit <https://github.com/LFPy/LFPy/graphs/contributors>`_):

*	Henrik Lindén https://lindenh.wordpress.com

*	Espen Hagen http://www.mn.uio.no/fysikk/english/?vrtx=person-view&uid=espehage

*	Szymon Łęski

*   Torbjørn V. Ness

*   Solveig Næss

*   Alessio Buccino

*	Eivind Norheim 

*   Klas H. Pettersen http://www.med.uio.no/imb/english/?vrtx=person-view&uid=klashp

*   Gaute T. Einevoll https://www.nmbu.no/ans/gaute.einevoll


Contact
=======

If you want to contact us with questions, bugs and comments,
please create an issue on `GitHub.com/LFPy/LFPy/issues <https://github.com/LFPy/LFPy/issues>`_. 
We are of course happy to receive feedback of any kind.