.. include:: <isonum.txt>

Measurements subpackage
=======================

Measurements are currently the main user interface to the eprcontrol toolbox. A measurement is defined in a YAML file setting the experiment and display according to the user's needs. Furthermore, parameters and settings for the experiment (and the display) can be put in there.

From the user's perspective, the parameters of the measurement are defined in a YAML file somewhere convenient in a directory of the user. Thus, measurement parameters that need to change according to the specific needs are fully separated from the eprcontrol software and can be stored together with the data, providing a minimal documentation of the setup used and experiment performed.


Performing measurements based on recipes
----------------------------------------

Recipes are a way to define measurements in a user-friendly way, relieving the user from being able to program. All you need to do is to create/modify a simple text file according to the needs of your specific measurement. For the time being, those recipes are the primary user interface to the eprcontrol toolbox. All parameters and settings for an individual measurement are stored in a YAML file. An example for such a measurement YAML file is given below:

.. code:: YAML

   experiment:
       name: DummyExperiment
       parameters:
           filename: my_first_dummy_experiment_run
           number_of_rows: 200
       settings:
   display:
       name: Display


As you can see, thanks to the YAML file format, this is a rather simple and straightforward way of defining measurements. You define an experiment and a display, whose names each need to correspond to classes of the respective subpackages. For the experiment you can provide parameters as well as settings. The main difference between the two: Parameters are the variables of the actual experiment, settings are applied to the setup used, *i.e.*, the underlying hardware components. For further settings of both, experiment and display parameters, see the respective documentation.

To actually perform a measurement, you will need to do two simple steps:

* Create an instance of the :class:`+eprcontrol.+measurements.Measurement` class.

* Perform the actual measurement.

In MATLAB\ |reg| code, this could look like the following:

.. code:: matlab

   measurement = eprcontrol.measurements.Measurement('measurement.yaml');
   measurement.perform();


If you don't like working with objects, there is even a one-liner:

.. code:: matlab

	eprcontrol.measurements.perform('measurement.yaml');


This function will do nothing else than executing the two lines given above, *i.e.*, instantiate an object of the :class:`+eprcontrol.+measurements.Measurement` class and run its :meth:`perform` method.


Why recipes?
------------

Using recipes, *i.e.* simple human-readable and writable text files, to define measurements comes with a number of advantages:

* Simple and straight-forward implementation

* Strict separation of user interface and underlying code performing the real actions

* One step further towards reproducibility: Recipes for measurements can be stored along with the data obtained.

For further discussion, see the :doc:`in-depth discussion of recipe-driven measurements <../recipes>` in the user documentation.


Classes and functions
---------------------

.. toctree::
   :maxdepth: 1


.. automodule:: +eprcontrol.+measurements
    :members:
    :private-members: