Consolidate mechanism naming convention

Action: The current naming convention for mechanisms is to use the name of it in the ORIGINAL model that it is inherited from. E.g., if we have (Sherfey, 1996)'s "iNa" current implemented, it will be in dnsim/database/iNa.txt rather than whatever naming convention we so choose. I believe we should include the previous implementation's name in a comment in the file, but we should name all mechanisms according to an agreed-upon scheme. I'm open to ideas about the scheme itself.

Reason: This prevents duplicates (including "different-case duplicates" as exist now, which interfere with Dropbox) and makes the list of mechanisms more clear/explanatory.

This entry is about the unique-ifying part of a mechanism's name, so for a given mechanism `iNa` I'm trying to figure out/discuss `iNa_<unique identifier>`

Suggestions for overall naming scheme:

(see the bottom for my TL;DR suggestion)
tie it to the paper from which the mechanism is cited. Two examples below, for instance for the thalamocortical relay cell's Na current inheriting from (Ching et al., 2010).
- iNa_C10
- iNa_C2010
- Problems with this: there could still be overlap that confuses these, e.g. if there's another Na current from a different paper like (Charles et al., 2010) or whatever, then this scheme wouldn't work. Edit: I just realized that this is even more vague since in all likelihood there's multiple Na current mechanisms (for different celltypes) in most modeling papers in the first place, so by itself, this naming scheme is not good.
tie it to the commonly used celltype abbreviation used in the literature. For example, if thalamocortical relay = TC cells,
- iNa_TC
- Problems: differently-derived models of consecutive model generations within the same lab, or between different labs, often use the same terminology for slightly-different models, e.g. (Vijayan 2012)'s TC cells are different than (Ching 2010)'s. It's also possible that some celltypes do not have convenient abbreviations, but this is probably not a real issue.
tie it to just a basic numbering scheme dependent on when the mechanism is added to the DNSIM system. E.g., if you've already put in two different Na currents, we call those
- iNa_001 and iNa_002
- and then when I add one, we call the new one iNa_003
- Issues:
- This still keeps the user very removed from being able to intuit what each version of the similar current does, even though
  1. it's just as nonintuitive as the current system, and
  2. at least in the GUI interface, it is trivial to look at the actual mechanism file itself, which will contain all the suitable identifying information for the mechanism at the top of the file
- The most confusing case would be if there is a number in the current name, but even then I think it's pretty clear, since the ID # would be separated by an underscore, e.g.: iHCN4_003
- Note: I think this is the 2nd best idea. It's the most future-proof, and it makes it obvious that the mechanism name alone is not the way to intuitively know what exact version of the mechanism this corresponds to, especially in a system that maybe has hundreds or thousands of mechanisms.
- Question: should we use 2 ##'s or 3 ###'s as placeholders? Or even 4 ####'s?
some combination of the above, e.g. iNa_C10_003 or even iNa_TC_C10_002.
- Pros:
- This would be the most informative to the user
- The numbers on the numbering scheme here wouldn't get as high, so 3 ###'s is potentially adequate for the future-history of the system
- Cons:
- This would mean basically all mechanism names are this long, which COULD severely reduce readability in the actual code or GUI system. But it may be an acceptable loss.
- I doubt (and hope) that this would be an issue, but supposedly MATLAB's max variable name limit is 63 characters. Sticking to this scheme, though, means most mechanisms would probably be on the order of 14-20 characters I think.
- This very extended format like iNa_TC_C10_002 is what I think is the best choice, if you think it's an acceptable loss to readability in the code.

This entry is about the "core" part of a mechanism's name, so for a given mechanism `iNa_<unique identifier>` I'm trying to figure out/discuss how to name the `iNa` part.

(I do NOT intend "core" vs "unique identifier" to become canon for discussion of the mechanisms names, though we can do that if we wish -- I only intend to use that for the sake of this discussion.)
I like the style of most of the current mechanism filenames, which are "iPhone"-esque; an "i" to indicate it's a current, immediately followed by a core, literature-common identifier that starts with a capital letter like "Nap".
Rules:
- 1. Any mechanism that outputs a current should have its file begin with a lowercase i e.g. above.
- Judging from some grepping, the only files that don't do this are some of the Ca-related dynamics files (not to mention entire-model .mat files) and a 'getPoissonExp.m' function that may belong in dnsim/matlab/functions instead of dnsim/database. So this would apply to most of the files currently in the database.
- 2. Currents with well-established names should try to be named as closely as possible to those names, within reason.
- I'm really thinking of the mechanisms like iNaF.txt and naf.txt here; I mainly mean that, if these refer to two different implementations of the same THEORETICAL mechanism (a fast Sodium current, I presume), then their core mechanism name should be the same, like iNaF, and we should use some other identification to discriminate between them, like what I posted in the previous comment. I want there to be a distinction between two mechanisms differentiated by case like iNaP and iNap such that the user can confidently say "well that's not even the same theoretical current; the first one is probably the Persistent Na current, but the second one is probably not referring to an implementation of the Persistent Na current."
- Another way to say it is, if a mechanism is for Persistent Sodium currents, and we agree that the classic subtext identifier is P, then all Persistent Sodium currents should start with iNaP and not iNap. I don't really care about WHICH we pick, as long as everyone is on the same page and everyone is CONSISTENT, since obviously some notion of "which one is dominant in the literature" is subjective, and the choice doesn't really matter that much at the end of the day.
- 3. Consistency, including case-consistency, is ultra mega important x9000.
- **4. Element symbol names should be capitalized, like CaDyns.

Additionally, is there reason to or not to use the a similar name to the filename in the "interface" part of the current? E.g. for mechanism iK_TC_C10_001.txt, is there reason to or not to give it the interface current => IK_TC_C10_001(V,<args>)? where the 'i' is made into an uppercase 'I', but other than that the name is the same as the defining filename?

One reason I can think to do this is to avoid confusion when a single cell/compartment might have multiple of a similarly-named current, like iKs or something. If we used the longer filename, then this would solve the problem.

As of Meeting001 2015_02_05 Thu we discussed a new naming mechanism naming convention; the relevant transcript is shown below

- Mechanism standards
    - mechanism groups
        - toolbox (/dnsim/examples - with tutorials on github wiki; /dnsim/database)
        - infinitebrain.org
        - personal projects
    - files/names
        - directory hierarchy
            - directories: Field => (intrinsic, connection) => Context => [files]
            - Field = "neuroscience", ...
        - naming conventions
            - file names: `<MechName>_<###>_<Descriptor>` (eg, naf_001_tc)
            - Need aliases to standardize names
                - currents: `h = (h,AR), ks = (M,ks)`
                - cells: `RE = (RE,nRT,TRN)`
            - eg, `/dnsim/database/neuroscience/intrinsic/HH/naf_001_tc`
    - comments to provide
        - references to papers
        - variable names used in paper
        - units

This requires three TODO things:
1. DNSIM needs to recursively search through some set of its database/ directory to know what mechanisms are available. This could get complicated, as there might exist mechanisms with the same name but for different paradigms (like Hodgkin-Huxley mechanisms with the same name as neural field or Morris-Lecar ones), in which case we may want to force DNSIM to query the user which paradigm they're using.
  - Alternatively, we could specify this information in the file, but that would imply continuing to have all mechanisms, of which there might be many in the starter pack, in the same folder.
  - Alternatively, we could just name mechanisms around this, since we discussed only using this hierarchy for the starter pack.
2. We need to rename all the current mechanisms to under this new scheme.
3. We need to add an abbreviations file for all the overlapping aliases, something like into database/abbreviations.txt.

jsherfey / dnsim