pynxtools-apm 0.1__py3-none-any.whl

pynxtools_apm/README.md

@@ -0,0 +1,45 @@
+<!--# APM reader
+
+## Getting started - usage related to NOMAD Oasis
+This parser can be used to map numerical data and metadata inside frequently
+used file formats of atom probe tomography and related field-ion microscopy
+software tools into a NeXus HDF5 file which complies with a specific version
+of the NXapm application definition.
+
+If you are using a NOMAD Oasis, you can use this tool as follows.
+1. Log-in to a NOMAD Oasis and navigate to the *Create Uploads* tab.
+2. Select apm example from the list of available options.
+3. Drag-and-drop the file with your reconstructed dataset via pos, epos, or apt,
+   and add your ranging definitions file via rrng, or rng, or the fig files from
+   Peter Felfer's Erlangen atom-probe-toolbox.
+3. Edit the electronic lab notebook (ELN) schema inside the NOMAD Oasis and click the
+   save button in the NOMAD Oasis GUI to save the data that you have entered into
+   the ELN template. Clicking *save* will trigger the automatic generation
+   of an eln_data.yaml file. Second, the clicking will trigger a run of the
+   dataconverter/apm parser which generates a NXapm NeXus file based on the data
+   in the reconstruction and ranging file and the eln_data.yaml file. Afterwards,
+   the file will be displayed in the GUI and show up in the upload section of your Oasis.
+   By default the converter performs a strong loss-less compression on the input
+   as many of the stack data store integers with a low entropy. The compression may
+   take some time. You can inspect the progress of the conversion in the console from
+   which you started the NOMAD Oasis appworker.
+4. If successful, a NeXus (nxs) file will appear in your upload. You can explore
+   its content with the H5Web tools inside the NOMAD Oasis GUI and click interactively
+   through the data including default plots. For atom probe these are a 3D discretized
+   view of your reconstruction using 1nm rectangular binning and the mass spectrum
+   with a default 0.01 Da binning an no additional corrections.
+   If unsuccessful, the console from where you started the NOMAD appworker can help
+   you with identifying if problems occurred.
+
+## A request to take action by the technology partners
+In fact, while the above-mentioned file formats and corresponding commercial software is routinely
+used by numerous atom probers every day, the actual knowledge about the I/O routines has always
+been on a few developers shoulders. In fact many of the open-source readers for file formats were
+reverse-engineered. This is challenging because the amount of documentation that is available
+for some file formats is neither exhaustive nor documented enough in detail.
+
+This limits developers to decide and design how to best implement possible mappings of
+specific binary numerical data and metadata into specifically named fields. We wish that
+intensified exchange between technology partners like AMETEK/Cameca and the atom probe
+community can help to improve the situation. Everybody is very welcomed to leave us
+comments in the issue list (or drop us an email) to exchange specifically about this topic.-->

pynxtools_apm/concepts/mapping_functors.py

@@ -0,0 +1,345 @@
+#
+# Copyright The NOMAD Authors.
+#
+# This file is part of NOMAD. See https://nomad-lab.eu for further info.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Utilities for working with NeXus concepts encoded as Python dicts in the concepts dir."""
+
+from datetime import datetime
+import pytz
+import flatdict as fd
+import numpy as np
+
+from pynxtools_apm.utils.string_conversions import string_to_number, rchop
+from pynxtools_apm.utils.interpret_boolean import try_interpret_as_boolean
+from pynxtools_apm.utils.get_file_checksum import get_sha256_of_file_content
+
+
+def variadic_path_to_specific_path(path: str, instance_identifier: list):
+    """Transforms a variadic path to an actual path with instances."""
+    if (path is not None) and (path != ""):
+        narguments = path.count("*")
+        if narguments == 0:  # path is not variadic
+            return path
+        if len(instance_identifier) >= narguments:
+            tmp = path.split("*")
+            if len(tmp) == narguments + 1:
+                nx_specific_path = ""
+                for idx in range(0, narguments):
+                    nx_specific_path += f"{tmp[idx]}{instance_identifier[idx]}"
+                    idx += 1
+                nx_specific_path += f"{tmp[-1]}"
+                return nx_specific_path
+    return None
+
+
+def add_specific_metadata(
+    concept_mapping: dict, orgmeta: fd.FlatDict, identifier: list, template: dict
+) -> dict:
+    """Map specific concept src on specific NeXus concept trg.
+
+    concept_mapping: translation dict how trg and src are to be mapped
+    orgmeta: instance data of src concepts
+    identifier: list of identifier to resolve variadic paths
+    template: instance data resulting from a resolved src to trg concept mapping
+    """
+    if "prefix_trg" in concept_mapping:
+        variadic_prefix_trg = concept_mapping["prefix_trg"]
+    elif "prefix" in concept_mapping:
+        variadic_prefix_trg = concept_mapping["prefix"]
+    else:
+        raise KeyError(f"Neither prefix nor prefix_trg found in concept_mapping!")
+
+    if "prefix_src" in concept_mapping:
+        prefix_src = concept_mapping["prefix_src"]
+    else:
+        prefix_src = ""
+
+    # process all mapping functors
+    # (in graphical programming these are also referred to as filters or nodes), i.e.
+    # an agent that gets some input does some (maybe abstract mapping) and returns an output
+    # as the mapping can be abstract we call it functor
+    if "use" in concept_mapping:
+        for entry in concept_mapping["use"]:
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if isinstance(entry[1], str) and entry[1] == "":
+                        continue
+                    trg = variadic_path_to_specific_path(
+                        f"{variadic_prefix_trg}/{entry[0]}", identifier
+                    )
+                    template[f"{trg}"] = entry[1]
+    if "map" in concept_mapping:
+        for entry in concept_mapping["map"]:
+            if isinstance(entry, str):
+                if f"{prefix_src}{entry}" not in orgmeta:
+                    continue
+                if (
+                    isinstance(orgmeta[f"{prefix_src}{entry}"], str)
+                    and orgmeta[f"{prefix_src}{entry}"] == ""
+                ):
+                    continue
+                trg = variadic_path_to_specific_path(
+                    f"{variadic_prefix_trg}/{entry}", identifier
+                )
+                template[f"{trg}"] = orgmeta[f"{prefix_src}{entry}"]
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if isinstance(entry[0], str):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        if (orgmeta[f"{prefix_src}{entry[1]}"], str) and orgmeta[
+                            f"{prefix_src}{entry[1]}"
+                        ] == "":
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = orgmeta[f"{prefix_src}{entry[1]}"]
+    if "map_to_str" in concept_mapping:
+        for entry in concept_mapping["map_to_str"]:
+            if isinstance(entry, str):
+                if f"{prefix_src}{entry}" not in orgmeta:
+                    continue
+                if (
+                    isinstance(orgmeta[f"{prefix_src}{entry}"], str)
+                    and orgmeta[f"{prefix_src}{entry}"] == ""
+                ):
+                    continue
+                trg = variadic_path_to_specific_path(
+                    f"{variadic_prefix_trg}/{entry}", identifier
+                )
+                template[f"{trg}"] = orgmeta[f"{prefix_src}{entry}"]
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if all(isinstance(elem, str) for elem in entry):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        if (
+                            isinstance(orgmeta[f"{prefix_src}{entry[1]}"], str)
+                            and orgmeta[f"{prefix_src}{entry[1]}"] == ""
+                        ):
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = orgmeta[f"{prefix_src}{entry[1]}"]
+    if "map_to_bool" in concept_mapping:
+        for entry in concept_mapping["map_to_bool"]:
+            if isinstance(entry, str):
+                if f"{prefix_src}{entry[0]}" not in orgmeta:
+                    continue
+                trg = variadic_path_to_specific_path(
+                    f"{variadic_prefix_trg}/{entry[0]}", identifier
+                )
+                template[f"{trg}"] = try_interpret_as_boolean(
+                    orgmeta[f"{prefix_src}{entry[0]}"]
+                )
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if all(isinstance(elem, str) for elem in entry):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = try_interpret_as_boolean(
+                            orgmeta[f"{prefix_src}{entry[1]}"]
+                        )
+    if "map_to_real" in concept_mapping:
+        for entry in concept_mapping["map_to_real"]:
+            if isinstance(entry, str):
+                if isinstance(entry[0], str):
+                    if f"{prefix_src}{entry[0]}" not in orgmeta:
+                        continue
+                    if (
+                        isinstance(orgmeta[f"{prefix_src}{entry[0]}"], str)
+                        and orgmeta[f"{prefix_src}{entry[0]}"] == ""
+                    ):
+                        continue
+                    trg = variadic_path_to_specific_path(
+                        f"{variadic_prefix_trg}/{entry[0]}", identifier
+                    )
+                    template[f"{trg}"] = string_to_number(
+                        orgmeta[f"{prefix_src}{entry[0]}"]
+                    )
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if all(isinstance(elem, str) for elem in entry):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        if (
+                            isinstance(orgmeta[f"{prefix_src}{entry[0]}"], str)
+                            and orgmeta[f"{prefix_src}{entry[1]}"] == ""
+                        ):
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = string_to_number(
+                            orgmeta[f"{prefix_src}{entry[1]}"]
+                        )
+                    elif isinstance(entry[0], str) and isinstance(entry[1], list):
+                        if not all(
+                            (
+                                isinstance(value, str)
+                                and f"{prefix_src}{value}" in orgmeta
+                            )
+                            for value in entry[1]
+                        ):
+                            continue
+                        if not all(
+                            (
+                                isinstance(orgmeta[f"{prefix_src}{value}"], str)
+                                and orgmeta[f"{prefix_src}{value}"] != ""
+                            )
+                            for value in entry[1]
+                        ):
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        res = []
+                        for value in entry[1]:
+                            res.append(
+                                string_to_number(orgmeta[f"{prefix_src}{value}"])
+                            )
+                        template[f"{trg}"] = np.asarray(res, np.float64)
+    if "map_to_real_and_multiply" in concept_mapping:
+        for entry in concept_mapping["map_to_real_and_multiply"]:
+            if isinstance(entry, tuple):
+                if len(entry) == 3:
+                    if (
+                        isinstance(entry[0], str)
+                        and isinstance(entry[1], str)
+                        and isinstance(entry[2], float)
+                    ):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        if (
+                            isinstance(orgmeta[f"{prefix_src}{entry[1]}"], str)
+                            and orgmeta[f"{prefix_src}{entry[1]}"] == ""
+                        ):
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = entry[2] * string_to_number(
+                            orgmeta[f"{prefix_src}{entry[1]}"]
+                        )
+    if "map_to_real_and_join" in concept_mapping:
+        for entry in concept_mapping["map_to_real_and_join"]:
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if isinstance(entry[0], str) and isinstance(entry[1], list):
+                        if not all(
+                            (
+                                isinstance(value, str)
+                                and f"{prefix_src}{value}" in orgmeta
+                            )
+                            for value in entry[1]
+                        ):
+                            continue
+                        if not all(
+                            (
+                                isinstance(orgmeta[f"{prefix_src}{value}"], str)
+                                and orgmeta[f"{prefix_src}{value}"] != ""
+                            )
+                            for value in entry[1]
+                        ):
+                            continue
+                        res = []
+                        for value in entry[1]:
+                            res.append(
+                                string_to_number(orgmeta[f"{prefix_src}{value}"])
+                            )
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = np.asarray(res)
+            # we may need to be more specific with the return datatype here, currently default python float
+    if "unix_to_iso8601" in concept_mapping:
+        for entry in concept_mapping["unix_to_iso8601"]:
+            if isinstance(entry, tuple):
+                if (
+                    2 <= len(entry) <= 3
+                ):  # trg, src, timestamp or empty string (meaning utc)
+                    if all(isinstance(elem, str) for elem in entry):
+                        if f"{prefix_src}{entry[1]}" not in orgmeta:
+                            continue
+                        if (
+                            isinstance(orgmeta[f"{prefix_src}{entry[1]}"], str)
+                            and orgmeta[f"{prefix_src}{entry[1]}"] == ""
+                        ):
+                            continue
+                        tzone = "UTC"
+                        if len(entry) == 3:
+                            # if not isinstance(entry[2], str):
+                            #     raise TypeError(f"{tzone} needs to be of type string!")
+                            tzone = entry[2]
+                        if tzone not in pytz.all_timezones:
+                            raise ValueError(
+                                f"{tzone} is not a timezone in pytz.all_timezones!"
+                            )
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        template[f"{trg}"] = datetime.fromtimestamp(
+                            int(orgmeta[f"{prefix_src}{entry[1]}"]),
+                            tz=pytz.timezone(tzone),
+                        ).isoformat()
+    if "join_str" in concept_mapping:  # currently also joining empty strings
+        for entry in concept_mapping["join_str"]:
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if isinstance(entry[0], str) and isinstance(entry[1], list):
+                        if not all(
+                            (
+                                isinstance(value, str)
+                                and f"{prefix_src}{value}" in orgmeta
+                            )
+                            for value in entry[1]
+                        ):
+                            continue
+                        trg = variadic_path_to_specific_path(
+                            f"{variadic_prefix_trg}/{entry[0]}", identifier
+                        )
+                        res = []
+                        for value in entry[1]:
+                            res.append(orgmeta[f"{prefix_src}{value}"])
+                        template[f"{trg}"] = " ".join(res)
+    if "sha256" in concept_mapping:
+        for entry in concept_mapping["sha256"]:
+            if isinstance(entry, tuple):
+                if len(entry) == 2:
+                    if not all(isinstance(elem, str) for elem in entry):
+                        continue
+                    if f"{prefix_src}{entry[1]}" not in orgmeta:
+                        continue
+                    if orgmeta[f"{prefix_src}{entry[1]}"] == "":
+                        continue
+                    trg = variadic_path_to_specific_path(
+                        f"{variadic_prefix_trg}/{entry[0]}", identifier
+                    )
+                    with open(orgmeta[f"{prefix_src}{entry[1]}"], "rb") as fp:
+                        template[f"{rchop(trg, 'checksum')}checksum"] = (
+                            get_sha256_of_file_content(fp)
+                        )
+                        template[f"{rchop(trg, 'checksum')}type"] = "file"
+                        template[f"{rchop(trg, 'checksum')}path"] = orgmeta[
+                            f"{prefix_src}{entry[1]}"
+                        ]
+                        template[f"{rchop(trg, 'checksum')}algorithm"] = "sha256"
+    return template

pynxtools_apm/config/eln_cfg.py

@@ -0,0 +1,189 @@
+#
+# Copyright The NOMAD Authors.
+#
+# This file is part of NOMAD. See https://nomad-lab.eu for further info.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Dict mapping custom schema instances from eln_data.yaml file on concepts in NXapm."""
+
+APM_ENTRY_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]",
+    "prefix_src": "entry/",
+    "map_to_str": [
+        "run_number",
+        "operation_mode",
+        "start_time",
+        "end_time",
+        "experiment_description",
+        ("experiment_alias", "run_number"),
+    ],
+}
+
+
+APM_SAMPLE_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/sample",
+    "prefix_src": "sample/",
+    "map": [
+        ("grain_diameter", "grain_diameter/value"),
+        ("grain_diameter_error", "grain_diameter_error/value"),
+        ("heat_treatment_temperature", "heat_treatment_temperature/value"),
+        ("heat_treatment_temperature_error", "heat_treatment_temperature_error/value"),
+        ("heat_treatment_quenching_rate", "heat_treatment_quenching_rate/value"),
+        (
+            "heat_treatment_quenching_rate_error",
+            "heat_treatment_quenching_rate_error/value",
+        ),
+    ],
+    "map_to_str": [
+        "alias",
+        "description",
+        "method",
+        ("grain_diameter/@units", "grain_diameter/unit"),
+        ("grain_diameter_error/@units", "grain_diameter/unit"),
+        ("heat_treatment_temperature/@units", "heat_treatment_temperature/unit"),
+        (
+            "heat_treatment_temperature_error/@units",
+            "heat_treatment_temperature_error/unit",
+        ),
+        ("heat_treatment_quenching_rate/@units", "heat_treatment_quenching_rate/unit"),
+        (
+            "heat_treatment_quenching_rate_error/@units",
+            "heat_treatment_quenching_rate_error/unit",
+        ),
+    ],
+}
+
+
+APM_SPECIMEN_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/specimen",
+    "prefix_src": "specimen/",
+    "map": [
+        ("initial_radius", "initial_radius/value"),
+        ("shank_angle", "shank_angle/value"),
+    ],
+    "map_to_bool": ["is_polycrystalline", "is_amorphous"],
+    "map_to_str": [
+        "alias",
+        "preparation_date",
+        "description",
+        "method",
+        ("initial_radius/@units", "initial_radius/unit"),
+        ("shank_angle/@units", "shank_angle/unit"),
+    ],
+}
+
+
+APM_INSTRUMENT_STATIC_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/measurement/instrument",
+    "prefix_src": "atom_probe/",
+    "map": [("analysis_chamber/flight_path", "nominal_flight_path/value")],
+    "map_to_str": [
+        "status",
+        "instrument_name",
+        "location",
+        ("FABRICATION[fabrication]/vendor", "fabrication_vendor"),
+        ("FABRICATION[fabrication]/model", "fabrication_model"),
+        ("FABRICATION[fabrication]/identifier", "fabrication_identifier"),
+        ("reflectron/status", "reflectron_status"),
+        ("local_electrode/name", "local_electrode_name"),
+        ("pulser/pulse_mode", "pulser/pulse_mode"),
+        ("analysis_chamber/flight_path/@units", "nominal_flight_path/unit"),
+    ],
+}
+
+
+APM_INSTRUMENT_DYNAMIC_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/measurement/event_data_apm_set/EVENT_DATA_APM[event_data_apm]/instrument",
+    "prefix_src": "atom_probe/",
+    "use": [("control/target_detection_rate/@units", "ions/pulse")],
+    "map": [
+        ("control/target_detection_rate", "target_detection_rate"),
+        ("pulser/pulse_frequency", "pulser/pulse_frequency/value"),
+        ("pulser/pulse_fraction", "pulser/pulse_fraction"),
+        ("analysis_chamber/chamber_pressure", "chamber_pressure/value"),
+        ("stage_lab/base_temperature", "base_temperature/value"),
+    ],
+    "map_to_str": [
+        ("control/evaporation_control", "evaporation_control"),
+        ("pulser/pulse_frequency/@units", "pulser/pulse_frequency/unit"),
+        ("analysis_chamber/chamber_pressure/@units", "chamber_pressure/unit"),
+        ("stage_lab/base_temperature/@units", "base_temperature/unit"),
+    ],
+}
+
+
+APM_RANGE_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/atom_probe/ranging",
+    "prefix_src": "ranging/",
+    "map_to_str": [
+        ("programID[program1]/program", "program"),
+        ("programID[program1]/program/@version", "program_version"),
+    ],
+}
+
+
+APM_RECON_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/atom_probe/reconstruction",
+    "prefix_src": "reconstruction/",
+    "map": [("field_of_view", "field_of_view/value")],
+    "map_to_str": [
+        "protocol_name",
+        "crystallographic_calibration",
+        "parameter",
+        ("programID[program1]/program", "program"),
+        ("programID[program1]/program/@version", "program_version"),
+        ("field_of_view/@units", "field_of_view/unit"),
+    ],
+}
+
+
+APM_WORKFLOW_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/atom_probe",
+    "prefix_src": "workflow/",
+    "sha256": [
+        ("raw_data/SERIALIZED[serialized]/checksum", "raw_dat_file"),
+        ("hit_finding/SERIALIZED[serialized]/checksum", "hit_dat_file"),
+        ("reconstruction/config/checksum", "recon_cfg_file"),
+    ],
+}
+
+# NeXus concept specific mapping tables which require special treatment as the current
+# NOMAD Oasis custom schema implementation delivers them as a list of dictionaries instead
+# of a directly flattenable list of key, value pairs
+
+APM_USER_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/USER[user*]",
+    "map_to_str": [
+        "name",
+        "affiliation",
+        "address",
+        "email",
+        "telephone_number",
+        "role",
+        "social_media_name",
+        "social_media_platform",
+    ],
+}
+
+
+APM_IDENTIFIER_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/USER[user*]",
+    "use": [
+        ("IDENTIFIER[identifier]/is_persistent", False),
+        ("IDENTIFIER[identifier]/service", "orcid"),
+    ],
+    "map_to_str": [
+        ("IDENTIFIER[identifier]/identifier", "orcid"),
+    ],
+}

pynxtools_apm/config/oasis_cfg.py

@@ -0,0 +1,94 @@
+#
+# Copyright The NOMAD Authors.
+#
+# This file is part of NOMAD. See https://nomad-lab.eu for further info.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""Dict mapping values for a specifically configured NOMAD Oasis."""
+
+# currently by virtue of design NOMAD Oasis specific examples show how different tools and
+# services can be specifically coupled and implemented so that they work together
+# currently we assume that the ELN provides all those pieces of information to instantiate
+# a NeXus data artifact which technology-partner-specific files or database blobs can not
+# deliver. Effectively a reader uses the eln_data.yaml generic ELN output to fill in these
+# missing pieces of information while typically heavy data (tensors etc) are translated
+# and written from the technology-partner files
+# for large application definitions this can lead to a practical inconvenience:
+# the ELN that has to be exposed to the user is complex and has many fields to fill in
+# just to assure that all information are included in the ELN output and thus consumable
+# by the dataconverter
+# taking the perspective of a specific lab where a specific version of an ELN provided by
+# or running in addition to NOMAD Oasis is used many pieces of information might not change
+# or administrators do not wish to expose this via the end user ELN in an effort to reduce
+# the complexity for end users and make entering of repetitiv information obsolete
+
+# this is the scenario for which deployment_specific mapping shines
+# parsing of deployment specific details in the apm reader is currently implemented
+# such that it executes after reading generic ELN data (eventually available entries)
+# in the template get overwritten
+
+import datetime as dt
+
+from pynxtools_apm.utils.versioning import NX_APM_ADEF_NAME
+
+
+APM_OASISCONFIG_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]",
+    "use": [
+        ("definition", f"{NX_APM_ADEF_NAME}"),
+        (
+            "start_time",
+            f"{dt.datetime.now(dt.timezone.utc).isoformat().replace('+00:00', 'Z')}",
+        ),
+    ],
+    "map_to_str": [("operation_mode")],
+}
+
+
+APM_CSYS_MCSTASLIKE_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/coordinate_system_set/COORDINATE_SYSTEM[coordinate_system]",
+    "use": [
+        (
+            "alias",
+            "Following the idea of McStas that the z-axis points along the direction of an ion leaving the apex along the longest direction of the specimen",
+        ),
+        ("type", "cartesian"),
+        ("handedness", "right_handed"),
+        (
+            "x_direction",
+            "Direction 1 that is perpendicular to the z_direction for a right_handed cartesian",
+        ),
+        ("x_alias", "x-axis"),
+        (
+            "y_direction",
+            "Direction 2 that is perpendicular to the x_direction and the z_direction for a right_handed cartesian",
+        ),
+        ("y_alias", "y-axis"),
+        (
+            "z_direction",
+            "Direction of an ion travelling hypothetically exactly along the assumed axis that is parallel to the longest direction of the specimen",
+        ),
+        ("z_alias", "z-axis"),
+        (
+            "origin",
+            "E.g. a characteristic point e.g. initial apex or center of the base of the specimen or something else",
+        ),
+    ],
+}
+
+
+APM_EXAMPLE_TO_NEXUS = {
+    "prefix_trg": "/ENTRY[entry*]/CITE[cite*]",
+    "map_to_str": [("doi"), ("description")],
+}