Simulation metadata (README.yaml)

Each simulation in the NMRlipids databank is assigned with a README.yaml metadata file which contains all the essential information of the simulation. These files are created from the manually contributed info.yaml files as described in Adding simulations. The README.yaml files are stored as described in Data organisation.

You can view examples in the BilayerData GitHub repository.

README files contain information that is manually entered into info.yaml files and automatically exctracted information by the AddData.py program. Table below lists the manually entered compulsory and optional parameters, as well as automatically extracted information from simulation files.

---

key	description	type
DOI	DOI from where the raw data is found	User-given
TRJ	Name of the trajectory file found from DOI	User-given
TPR	Name of the topology file found from DOI	User-given
SOFTWARE	Software used to run the simulation	User-given
PREEQTIME	Pre-equilibrate time in nanoseconds.	User-given
TIMELEFTOUT	Equilibration period in the uploaded trajectory.	User-given
DATEOFRUNNIG	Date when added into the databank	User-given
DIR_WRK	Temporary local working directory	Deprecated
UNITEDATOM_DICT	Hydrogen information for united atom simulations	User-given
TYPEOFSYSTEM	Lipid bilayer or something else	User-given
SYSTEM	System description in the free text format	User-given
TEMPERATURE	Temperature of the simulation.	User-given
COMPOSITION	Molecules’ names, mappings, number.	Mixed*
PUBLICATION	Reference to a publication(s) related to the data.	User-given
AUTHORS_CONTACT	Name and email of the main author(s) of the data.	User-given
BATCHID	Identifier for a series of related simulations	User-given
SOFTWARE_VERSION	Version of the used software	User-given
FF	Name of the used force field	User-given
FF_SOURCE	Source of the force field parameters	User-given
FF_DATE	Date when force field parameters were accessed	User-given
FF{molname}	Molecule specific force field information.	User-given
CPT	Name of the Gromacs checkpoint file.	User-given
LOG	Name of the Gromacs log file.	User-given
TOP	Name of the Gromacs top file.	User-given
GRO	Name of the Gromacs gro file.	User-given
EDR	Name of the Gromacs edr file.	User-given
TRAJECTORY_SIZE	Size of the trajectory file in bytes	Autofilled
TRJLENGTH	Lenght of the trajectory (ps).	Autofilled
NUMBER_OF_ATOMS	Number of atoms in the simulation.	Autofilled
EXPERIMENT	Potentially connected experimental data	Gen by tools
ID	Unique integer identifier of the simulation	Gen by CI/CD

---

* — names and mappings are set by user whereas number of residues is autofilled

Fields description

1. DOI (compulsory)
   Give the DOI identity for the location of simulation files. Current databank works only for the data in Zenodo, but other potential sources are may be implemented in the future. Note that the DOI must point to a specific version of dataset in Zenodo. DOIs pointing to all versions of certain dataset do not work.

2. TRJ (compulsory)
   Give the name of the trajectory file that is found from the DOI given above.

3. TPR (compulsory)
   Give the name of the file with topology information (tpr file in the case of Gromacs) that is found from the DOI given above.

4. SOFTWARE (compulsory)
   Give the name of software used to run the simulation. The options are GROMACS, AMBER, NAMD, CHARMM and OPENMM. So far, only simulations run with GROMACS are accepted by the script.

5. PREEQTIME (compulsory)
   Give the time simulated before the uploaded trajectory in nanoseconds. For example, if you upload 100-200 ns part of total 200 ns simulation, this should value should be 100.

6. TIMELEFTOUT (compulsory)
   Give the time that should be considered as an equilibration period in the uploaded trajectory. Frames before the give time will be discarded in the analysis. For example, if you upload 0-200 ns part of total 200 ns simulation where the first 100 ns should be considered as an equilibration, this value should be 100.

7. COMPOSITION (compulsory)
   Information about the composition (i.e., the number of molecules) of each simulation is stored in COMPOSITION as python dictionary format. As an input, the COMPOSITION requires the universal name for each molecule present in the simulation (for definitions, see Universal molecule and atom names) as the first keys. For each molecule, another dictionary containing the simulation specific residue name (NAME) and the name of the mapping file (MAPPING) needs to be then defined. Mapping file defines the universal atom names for each molecule, for details see Universal molecule and atom names). For example, the COMPOSITION dictionary input for a system containing POPC, Cholesterol (CHOL), water (SOL), sodium (SOD), and chloride (CLA) is given as:

    COMPOSITION:
     CHOL:                                      # universal molecule name
      NAME: CHL1                                # simulation specific molecule name
      MAPPING: mappingCHOLESTEROLcharmm.txt     # name of the mapping file
     POPC:
      NAME: POPC
      MAPPING: mappingPOPCcharmm.txt
     SOL:
      NAME: TIP3
      MAPPING: mappingTIP3PCHARMMgui.txt
     SOD:
      NAME: SOD
      MAPPING: mappingSOD.txt
     CLA:
      NAME: CLA
      MAPPING: mappingCLA.txt

When running AddData.py, the numbers of molecules are added in additional COUNT keys into dictionaries of each molecule, see COMPOSITION (ouput) below.

8. DIR_WRK (deprecated)
   Give the path of the working directory in your local computer. The trajectory and topology files will be downloaded to this trajectory, and temporary files created during processing will be stored here.

9. UNITEDATOM_DICT (compulsory for united atom trajectories)
   Order parameters from united atom simulations are calculated using the buildH code. For united atom simulations, you need to tell how hydrogens are added based on definitions in the JSON UA dictionary. In the case of an all atom simulation, UNITEDATOM is left empty.

10. TYPEOFSYSTEM (compulsory)
    Tell whether the system is lipid bilayer or something else. Only lipid bilayers are currently supported, but other systems will be included in the future.

11. SYSTEM (compulsory)
    Give description of system in free format. For example ‘’POPC with cholesterol at 301K’’.

12. PUBLICATION
    Give reference to a publication(s) related to the data.

13. AUTHORS_CONTACT
    Give the name and email of the main author(s) of the data.

14. BATCHID
    Give an identifier for a series of related simulations e.g. NVT simulations with the same composition but different volume carried out to determine a surface pressure-area per lipid isotherm.

15. SOFTWARE_VERSION
    Give the version of the software used.

16. FF
    Give the name of the force field used used in the simulation.

17. FF_SOURCE
    Describe the source of the force field parameters. For example, CHARMM-GUI, link to webpage where parameters were downloaded, or citation to a paper.

18. FF_DATE
    Give the date when parameters were accessed or created. The format is day/month/year.

19. Individual force field names for molecules TODO: probably doesn’t work currently! In some cases special force fields are used for certain molecules. For example, non-standard parameters for ions or other molecules have been used. These can be specified giving forcefield names separately for individual molecules. These can be given as parameters named as FF+{abbreviation from table above}, i.e., FFPOPC, FFPOT, FFSOL etc.

20. CPT (Gromacs)
    Give the name of the Gromacs checkpoint file that is found from the DOI given above. CPT stands for the name of the cpt file.

21. LOG (Gromacs)
    Give the name of the Gromacs log file that is found from the DOI given above.

22. TOP (Gromacs)
    Give the name of the Gromacs top file that is found from the DOI given above.

23. EDR (Gromacs)
    Give the name of the Gromacs edr file that is found from the DOI given above.

24. TRAJECTORY_SIZE Size of the trajectory file in bytes.

25. TRJLENGTH
    Lenght of the trajectory (ps).

26. TEMPERATURE
    Temperature of the simulation.

27. NUMBER_OF_ATOMS
    Total number of atoms in the simulation.

28. DATEOFRUNNIG
    Date when added into the databank.

29. EXPERIMENT
    Potentially connected experimental data.

30. COMPOSITION (output)
    When adding a simulation into NMRlipids databank with the AddData.py, numbers of molecules are automatically calculated and stored into COUNT keys for each molecule in the COMPOSITION dictionary. Number of lipids are calculated separately for both membrane leaflets. For example, the result for the simulation with COMPOSITION input exemplified above is:

        COMPOSITION:
         CHOL:
          NAME: CHL1
          COUNT:
           - 25
           - 25
          MAPPING: mappingCHOLESTEROLcharmm.yaml
         POPC:
          NAME: POPC
          COUNT:
           - 100
           - 100
          MAPPING: mappingPOPCcharmm.yaml
         SOL:
          NAME: TIP3
          COUNT: 9000
          MAPPING: mappingTIP3PCHARMMgui.yaml
         SOD:
          NAME: SOD
          COUNT: 21
          MAPPING: mappingSOD.yaml
         CLA:
          NAME: CLA
          COUNT: 21
          MAPPING: mappingCLA.yaml

31. ID
    Unique numeric identifier assigned to the simulation. It is generated by the CI/CD pipelines of the databank.