Add naming.yaml for molecule (#470)

* Start molecule refactoring. First failed fragments test.

(cherry picked from commit 2d9b53b726560251dfdc7fdb8398dc5b07da58ac)

* molecule can live with old-style mapping or with mapping divided into mapping and naming. It will allow us to migrate gradually to new mapping structure.

(cherry picked from commit 453170de7b67f3444052b802602f0fa82a30aac4)

Author: comcon1

src/fairmd/lipids/data/ToyData/Molecules/membrane/BOG/metadata.yaml

@@ -0,0 +1,27 @@
+NMRlipids:
+  id: BOG
+  name: beta-octyl D-glucopyranoside
+  charge: 0
+sameAs:
+  ChEBI: CHEBI:41128
+  pubchem.compound: 62852
+  metabolights: MTBLC41128
+  pdb.ligand: BOG
+  ChEMBL: CHEMBL446037
+bioschema_properties:
+  iupacName: (2R,3S,4S,5R,6R)-2-(hydroxymethyl)-6-octoxyoxane-3,4,5-triol
+  smiles: CCCCCCCCO[C@H]1[C@@H]([C@H]([C@@H]([C@H](O1)CO)O)O)O
+  inChI: InChI=1S/C14H28O6/c1-2-3-4-5-6-7-8-19-14-13(18)12(17)11(16)10(9-15)20-14/h10-18H,2-9H2,1H3/t10-,11-,12+,13-,14-/m1/s1
+  inChIKey: HEGSGKPQLMEBJL-RKQHYHRCSA-N
+  molecularFormula: C14H28O6
+  molecularWeight: 292.37
+  name: (2R,3S,4S,5R,6R)-2-(hydroxymethyl)-6-octoxyoxane-3,4,5-triol
+  image: https://www.ebi.ac.uk/chembl/api/data/image/CHEMBL446037?dimensions=200
+  alternateName:
+  - β-octylglucoside
+  - 1-octyl-β-D-glucopyranoside
+  - 1-O-n-octyl-β-D-glucopyranoside
+  - β-D-octyl glucoside
+  - 1-O-octyl-β-D-glucopyranoside
+  - octyl-β-D-glucoside
+  - Oct β-Glc

src/fairmd/lipids/data/ToyData/Molecules/membrane/BOG/naming.yaml

@@ -0,0 +1,116 @@
+M_G0C1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 9
+M_G0C1H1_M:
+  FRAGMENT: glucose
+M_G0C1O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 8
+M_G0C2_M:
+  FRAGMENT: glucose
+  SMILEIDX: 10
+M_G0C2H1_M:
+  FRAGMENT: glucose
+M_G0C2O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 19
+M_G0C2O1H1_M:
+  FRAGMENT: glucose
+M_G0C3_M:
+  FRAGMENT: glucose
+  SMILEIDX: 11
+M_G0C3H1_M:
+  FRAGMENT: glucose
+M_G0C3O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 18
+M_G0C3O1H1_M:
+  FRAGMENT: glucose
+M_G0C4_M:
+  FRAGMENT: glucose
+  SMILEIDX: 12
+M_G0C4H1_M:
+  FRAGMENT: glucose
+M_G0C4O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 17
+M_G0C4O1H1_M:
+  FRAGMENT: glucose
+M_G0C5_M:
+  FRAGMENT: glucose
+  SMILEIDX: 13
+M_G0C5H1_M:
+  FRAGMENT: glucose
+M_G0C5O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 14
+M_G0C6_M:
+  FRAGMENT: glucose
+  SMILEIDX: 15
+M_G0C6H1_M:
+  FRAGMENT: glucose
+M_G0C6H2_M:
+  FRAGMENT: glucose
+M_G0C6O1_M:
+  FRAGMENT: glucose
+  SMILEIDX: 16
+M_G0C6O1H1_M:
+  FRAGMENT: glucose
+M_C1_M:
+  FRAGMENT: tail
+  SMILEIDX: 7
+M_C1H1_M:
+  FRAGMENT: tail
+M_C1H2_M:
+  FRAGMENT: tail
+M_C2_M:
+  FRAGMENT: tail
+  SMILEIDX: 6
+M_C2H1_M:
+  FRAGMENT: tail
+M_C2H2_M:
+  FRAGMENT: tail
+M_C3_M:
+  FRAGMENT: tail
+  SMILEIDX: 5
+M_C3H1_M:
+  FRAGMENT: tail
+M_C3H2_M:
+  FRAGMENT: tail
+M_C4_M:
+  FRAGMENT: tail
+  SMILEIDX: 4
+M_C4H1_M:
+  FRAGMENT: tail
+M_C4H2_M:
+  FRAGMENT: tail
+M_C5_M:
+  FRAGMENT: tail
+  SMILEIDX: 3
+M_C5H1_M:
+  FRAGMENT: tail
+M_C5H2_M:
+  FRAGMENT: tail
+M_C6_M:
+  FRAGMENT: tail
+  SMILEIDX: 2
+M_C6H1_M:
+  FRAGMENT: tail
+M_C6H2_M:
+  FRAGMENT: tail
+M_C7_M:
+  FRAGMENT: tail
+  SMILEIDX: 1
+M_C7H1_M:
+  FRAGMENT: tail
+M_C7H2_M:
+  FRAGMENT: tail
+M_C8_M:
+  FRAGMENT: tail
+  SMILEIDX: 0
+M_C8H1_M:
+  FRAGMENT: tail
+M_C8H2_M:
+  FRAGMENT: tail
+M_C8H3_M:
+  FRAGMENT: tail

src/fairmd/lipids/molecules.py

@@ -1,10 +1,8 @@
 """
-:module: settings/molecules.py
+Define classes for molecules (lipids, ions, etc.) and their sets.
 
-:description: Module file with definition of different global-level dictionaries.
-
-There is a dictionary of lipids, ions, etc. If you add a lipid which is not yet
-in the databank, you have to add it here!
+File defines crucial API classes for working with molecules.
+There is a dictionary of lipids, ions, etc. with their metadata and mapping files.
 """
 
 import fnmatch
@@ -42,10 +40,14 @@ class MoleculeMappingError(MoleculeError):
     def __init__(self, message: str, mol=None) -> None:
         if mol is None:
             msg = message
-        elif mol.mapping_file is None:
+        elif not mol._can_load_mapping():
             msg = f"From {mol}: {message}"
         else:
-            msg = f"From {mol}[{mol.mapping_file}]: {message}" if mol is not None else message
+            if mol._mapping_fpath is None:
+                disp_name = "naming.yaml"
+            else:
+                disp_name = os.path.relpath(mol._mapping_fpath, FMDL_MOL_PATH)
+            msg = f"From {mol}[{disp_name}]: {message}" if mol is not None else message
         super().__init__(msg, mol=mol)
 
 
@@ -85,7 +87,6 @@ def register_mapping(self, fname: str | None = None) -> None:
                 raise MoleculeMappingError(msg, mol=self)
             fname = _possible_mfiles[0]  # take the first one
         # set mapping file path
-        self._disp_mapping = fname
         self._mapping_fpath = os.path.join(self._get_path(), fname)
         if not os.path.isfile(self._mapping_fpath):
             msg = f"Cannot find '{self._mapping_fpath}' mapping for molecule {self.name}"
@@ -116,18 +117,22 @@ def check_mapping(self, u: mda.Universe, name: str) -> bool:
     @property
     def mapping_dict(self) -> dict:
         """Return mapping dictionary (load on first call)"""
-        if self._mapping_fpath is None:
+        if not self._can_load_mapping():
             msg = "Mapping file is not registered!"
             raise MoleculeError(msg, mol=self)
-        if self._mapping_dict is None:
-            try:
-                with open(self._mapping_fpath) as yaml_file:
-                    self._mapping_dict = yaml.safe_load(yaml_file)  # yaml.load(yaml_file, Loader=yaml.FullLoader)
-            except OSError as e:
-                msg = "Error opening mapping-file!"
-                raise MoleculeError(msg, mol=self) from e
+        if self._mapping_dict is None:  # load on first request
+            self._load_mapping_dict()
         return self._mapping_dict
 
+    def _load_mapping_dict(self) -> None:
+        """Load mapping dictionary from the registered mapping file."""
+        try:
+            with open(self._mapping_fpath) as yaml_file:
+                self._mapping_dict = yaml.safe_load(yaml_file)  # yaml.load(yaml_file, Loader=yaml.FullLoader)
+        except OSError as e:
+            msg = "Error opening mapping-file!"
+            raise MoleculeError(msg, mol=self) from e
+
     def md2uan(self, mdatomname: str, mdresname: str | None = None) -> str:
         """
         Convert MD atom name to the Universal Atom Name.
@@ -136,6 +141,12 @@ def md2uan(self, mdatomname: str, mdresname: str | None = None) -> str:
         :return: Universal Atom Name (str)
         """
         for universal_name, mrecord in self.mapping_dict.items():
+            if "ATOMNAME" not in mrecord:
+                msg = (
+                    f"ATOMNAME field is missing for {universal_name} in mapping dictionary."  # !
+                    " MD mapping is not possible."
+                )
+                raise MoleculeMappingError(msg, mol=self)
             mapping_aname = mrecord["ATOMNAME"]
             # MDAnalysis uses fnmatch patterns for selection language
             # https://userguide.mdanalysis.org/stable/selections.html
@@ -155,6 +166,9 @@ def uan2selection(self, uname: str, resname: str) -> str:
         :raises KeyError: if the universal name is not found in the mapping.
         :return: selection string for MDAnalysis
         """
+        if "ATOMNAME" not in self.mapping_dict[uname]:
+            msg = f"ATOMNAME field is missing for {uname} in mapping dictionary. MD mapping is not possible."
+            raise MoleculeMappingError(msg, mol=self)
         anm = self.mapping_dict[uname]["ATOMNAME"]
         selstr = f"name {anm}"
         if "RESIDUE" in self.mapping_dict[uname]:
@@ -172,7 +186,6 @@ def __init__(self, name: str) -> None:
         """
         self.__check_name(name)
         self._molname = name
-        self._disp_mapping = None
         self._mapping_fpath = None
         self._mapping_dict = None
 
@@ -214,10 +227,9 @@ def name(self) -> str:
         """Molecule name"""
         return self._molname
 
-    @property
-    def mapping_file(self) -> str:
-        """Mapping file name"""
-        return self._disp_mapping
+    def _can_load_mapping(self) -> bool:
+        """Is mapping registered for the molecule?"""
+        return self._mapping_fpath is not None
 
     # comparison by name to behave in a set
     # It's case-insesitive as folder structure should work on mac/win
@@ -256,6 +268,40 @@ def _populate_meta_data(self) -> None:
             msg = f"Metadata file not found for {self.name}."
             raise FileNotFoundError(msg)
 
+    def _can_load_mapping(self) -> bool:
+        super_is_reg = super()._can_load_mapping()
+        naming_path = os.path.join(self._get_path(), "naming.yaml")
+        return super_is_reg or os.path.isfile(naming_path)
+
+    def _load_mapping_dict(self) -> None:
+        if super()._can_load_mapping():
+            super()._load_mapping_dict()
+        else:
+            self._mapping_dict = {}
+        self._load_naming_dict()
+
+    def _load_naming_dict(self) -> None:
+        """
+        Load naming dictionary from `naming.yaml` file if it exists.
+
+        Updates existing mapping dictionary.
+        """
+        naming_path = os.path.join(self._get_path(), "naming.yaml")
+        if os.path.isfile(naming_path):
+            with open(naming_path) as yaml_file:
+                _naming_dict = yaml.load(yaml_file, Loader=yaml.FullLoader)
+            for unm, record in _naming_dict.items():
+                self._mapping_dict.setdefault(unm, {}).update(record)
+
+    @property
+    def fragments(self) -> list[str]:
+        """Return list of fragments for the lipid."""
+        frags = set()
+        for mrecord in self.mapping_dict.values():
+            frag = mrecord.get("FRAGMENT", "total")
+            frags.add(frag)
+        return sorted(frags)
+
     @property
     def metadata(self) -> dict:
         """