.. _metadata:

=========
Metadata
=========

Each instance of the LocData class carries metadata that give details about the data history and allows the addition of
further comments.

Each instance of an analysis class carries metadata that includes input parameters for reprocessing and allows the
addition of further comments.

Metadata is saved together with data or analysis results in order to provide serialized human- and machine-readable
information and serve information exchange between methods.

All metadata is structured as (nested) key:value pairs and implemented through Google's protobuf format.


Structure of metadata for LocData
==================================

A standard set of metadata elements is implemented into the metadata classes that are accessible by the `meta` attribute.
The current structure for metadata of the LocData class is defined in :obj:`locan/data/metadata.proto`
and can be accessed through :mod:`locan/data/metadata_pb2`.
It includes the following keys:

* identifier: ``str``
    Some short name.

* comment: ``str``
    A user comment.

* production_date: ``str`` (ISO standard)
    Date and time when the data was initially generated by experiment or simulation.

* creation_date: ``str`` (ISO standard)
    Date and time when the current dataset was created from original data.

* modification_date: ``str`` (ISO standard)
    Date and time when the data was last modified.

* source: ``enum``
    Describes where the data is from. Must be one of the following:

    \[unknown_source, design, experiment, simulation, import (from some other program)]

* state: ``enum``
    Indicator if data is original (as recorded) or has been modified.

    \[unknown_state, raw, modified]

* history: ``Operation``
    Operation that was applied to the original data containing a
    function name and parameter for the applied method.

* ancestor_identifiers: ``str``
    Identifier of locdata from which this locdata object is derived.

* units: ``Unit``
    Units for localization properties containing `property` and `unit` keys.

* element_count: ``int``
    Number of elements in locdata.

* frame_count: ``int``
    Number of frames in locdata.

* file_type: ``enum``
    Name of the file or program that produced the data (a fitter or simulation program).

    \[unknown_file_Type, custom, rapidstorm, elyra, thunderstorm, asdf, nanoimager]

* file_path: ``str``
    Path and name of data file.

* experimental_setup: ``map(str, str)``
    Information about the setup on which the data was generated in form of variable key-value pairs.

* experimental_sample: ``map(str, str)``
    Information about the sample that was imaged in form of variable key-value pairs.

* map: ``map(str, str)``
    Miscellaneous information in form of variable key-value pairs.


Structure of metadata for analysis classes
===========================================

The current structure for metadata of Analysis classes is defined in `locan/analysis/metadata_analysis.proto`
and can be accessed through :mod:`locan/analysis/metadata_analysis_pb2`.
It includes the following keys:

* identifier: ``str``
    Some short name.

* comment: ``str``
    A user comment.

* creation_date: ``str`` (ISO standard)
    Date and time when the results were created.

* modification_date: ``str`` (ISO standard)
    Date and time when the results were last recreated.

* method: ``Analysis_routine``
    A dictionary with 'name' and 'parameter' describing the applied analysis procedure. This data can be used
    to programmatically rerun the procedure.

* map: ``map(str, str)``
    Miscellaneous information in form of variable key-value pairs.
