
.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/Creating_GS_Files/plot_help_I_have_no_variable_metadata.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_Creating_GS_Files_plot_help_I_have_no_variable_metadata.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_Creating_GS_Files_plot_help_I_have_no_variable_metadata.py:


Help! I have no metadata
------------------------

Generate Metadata Templates

This example shows how GSPy can help when you are just getting started with no metadata files at all, only partially complete metadata files, or large data files and need to do the tedious task of filling out the variable metadata.

GSPy provides a ``metadata_template`` function to generate a template YAML file either for ``Survey`` for ``Dataset`` metadata. These templates contain placeholder metadata dictionaries with default values of "not_defined" to help users get started filling in their survey or data variable metadata. Below are multiple example scenarios demonstrating how to generate the desired metadata templates.


.. figure:: /_static/variable_metadata_template_snippet.png
   :width: 50%
   :align: center

   Example snippet of what the output template YAML file contains. For a dataset's metadata template, each variable in the data file (e.g. columns in a CSV file) is given a dictionary of attributes with the default values of "not_defined" that the user can then go through and update.

.. GENERATED FROM PYTHON SOURCE LINES 19-20

.. code-block:: Python
   :dedent: 1









.. GENERATED FROM PYTHON SOURCE LINES 22-28

.. code-block:: Python


    from os.path import join
    from gspy import Survey, Dataset, System
    import matplotlib.pyplot as plt
    from matplotlib import image as img








.. GENERATED FROM PYTHON SOURCE LINES 29-31

Generate the Survey Metadata Template
+++++++++++++++++++++++++++++++++++++

.. GENERATED FROM PYTHON SOURCE LINES 33-34

No existing Survey metadata, start with making a generic Survey template

.. GENERATED FROM PYTHON SOURCE LINES 34-37

.. code-block:: Python

    template = Survey.metadata_template()
    template.dump("template_survey_empty.yml")








.. GENERATED FROM PYTHON SOURCE LINES 38-43

.. literalinclude:: /../../examples/Creating_GS_Files/template_survey_empty.yml
   :language: yaml
   :linenos:
   :caption: Empty Survey YAML file


.. GENERATED FROM PYTHON SOURCE LINES 46-47

Partial existing Survey metadata file, generate a combined template to see what might be missing

.. GENERATED FROM PYTHON SOURCE LINES 47-54

.. code-block:: Python


    # Path to example files
    data_path = '..//data_files//'

    # Pre-existing Survey metadata file
    metadata = join(data_path, "documents//Resolve_survey_incomplete_md.yml")








.. GENERATED FROM PYTHON SOURCE LINES 55-56

Generate the template, passing the pre-existing file

.. GENERATED FROM PYTHON SOURCE LINES 56-60

.. code-block:: Python


    template = Survey.metadata_template(metadata)
    template.dump("template_md_partial_survey.yml")








.. GENERATED FROM PYTHON SOURCE LINES 61-66

.. literalinclude:: /../../examples/data_files/documents/Resolve_survey_incomplete_md.yml
   :language: yaml
   :linenos:
   :caption: Partial incoming Survey YAML file


.. GENERATED FROM PYTHON SOURCE LINES 69-74

.. literalinclude:: /../../examples/Creating_GS_Files/template_md_partial_survey.yml
   :language: yaml
   :linenos:
   :caption: Template with Partial Survey YAML file


.. GENERATED FROM PYTHON SOURCE LINES 77-79

Generate the Variable Metadata Template for My Dataset
++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. GENERATED FROM PYTHON SOURCE LINES 81-82

Zero existing Dataset metadata file, start with making an empty Dataset metadata template

.. GENERATED FROM PYTHON SOURCE LINES 84-86

Pass the data file (in this case a CSV) to make the template variable-specific.
Each column in the CSV file becomes a variable by default.

.. GENERATED FROM PYTHON SOURCE LINES 86-91

.. code-block:: Python

    data_path = '..//data_files//resolve'
    data = join(data_path, 'data//Resolve.csv')
    template = Dataset.metadata_template(data)
    template.dump("template_md_resolve_empty.yml")








.. GENERATED FROM PYTHON SOURCE LINES 92-97

.. literalinclude:: /../../examples/Creating_GS_Files/template_md_resolve_empty.yml
   :language: yaml
   :linenos:
   :caption: Empty Data YAML file


.. GENERATED FROM PYTHON SOURCE LINES 100-101

Combine with a partial existing Dataset metadata file

.. GENERATED FROM PYTHON SOURCE LINES 103-104

Here we have a CSV data file and a partial metadata file (missing the variable attributes)

.. GENERATED FROM PYTHON SOURCE LINES 104-107

.. code-block:: Python


    metadata = join(data_path, 'data//Resolve_data_md_without_variables.yml')








.. GENERATED FROM PYTHON SOURCE LINES 108-110

Generate the template for this CSV dataset by combining the existing
partial file with an empty template based on the dataset's variables

.. GENERATED FROM PYTHON SOURCE LINES 110-114

.. code-block:: Python


    template = Dataset.metadata_template(data, metadata)
    template.dump("template_md_resolve_partial.yml")








.. GENERATED FROM PYTHON SOURCE LINES 115-120

.. literalinclude:: /../../examples/Creating_GS_Files/template_md_resolve_partial.yml
   :language: yaml
   :linenos:
   :caption: Partial Data YAML file


.. GENERATED FROM PYTHON SOURCE LINES 123-125

Generate the Metadata Template for the System that Recorded My Data
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

.. GENERATED FROM PYTHON SOURCE LINES 127-129

A system is described per method, so pick the family that matches how the data
was acquired.

.. GENERATED FROM PYTHON SOURCE LINES 129-131

.. code-block:: Python

    print(System.templates())





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    ('fdem', 'magnetic', 'radiometric', 'tdem')




.. GENERATED FROM PYTHON SOURCE LINES 132-135

The shape of the template comes from how many transmitters and receivers the
system has. A dual moment time domain system read by two coils has four
couplets, and each moment gets its own gate times, named after it.

.. GENERATED FROM PYTHON SOURCE LINES 135-141

.. code-block:: Python

    template = System.metadata_template('tdem',
                                        name='skytem_system',
                                        transmitters=['LM', 'HM'],
                                        receivers=['z', 'x'])
    template.dump("template_md_tdem_system.yml")








.. GENERATED FROM PYTHON SOURCE LINES 142-147

.. literalinclude:: /../../examples/Creating_GS_Files/template_md_tdem_system.yml
   :language: yaml
   :linenos:
   :caption: Dual moment time domain system template


.. GENERATED FROM PYTHON SOURCE LINES 150-152

A frequency domain system pairs each transmitter coil with its own receiver
coil, so one set of labels is enough and the couplets follow one to one.

.. GENERATED FROM PYTHON SOURCE LINES 152-158

.. code-block:: Python

    template = System.metadata_template('fdem',
                                        name='resolve_system',
                                        transmitters=['400Z', '1800Z', '3300X',
                                                      '8200Z', '40000Z', '140000Z'])
    template.dump("template_md_fdem_system.yml")








.. GENERATED FROM PYTHON SOURCE LINES 159-163

Systems belong to the dataset they recorded, so ask for them alongside the
variables. Name each one and describe its shape, or give the family key on its
own where the defaults suffice - a magnetometer is one passive transmitter read
by one sensor.

.. GENERATED FROM PYTHON SOURCE LINES 163-170

.. code-block:: Python

    template = Dataset.metadata_template(data,
                                         systems={'skytem_system': dict(key='tdem',
                                                                        transmitters=['LM', 'HM'],
                                                                        receivers=['z', 'x']),
                                                  'magnetic_system': 'magnetic'})
    template.dump("template_md_resolve_with_systems.yml")








.. GENERATED FROM PYTHON SOURCE LINES 171-174

The placeholders read ``?? what goes here ??``. Delete the fields your system
does not have, and fill in the dimensions - the real gate times or frequencies -
before handing the metadata to a dataset.


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.642 seconds)


.. _sphx_glr_download_examples_Creating_GS_Files_plot_help_I_have_no_variable_metadata.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_help_I_have_no_variable_metadata.ipynb <plot_help_I_have_no_variable_metadata.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_help_I_have_no_variable_metadata.py <plot_help_I_have_no_variable_metadata.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_help_I_have_no_variable_metadata.zip <plot_help_I_have_no_variable_metadata.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_
