.. include:: <isonum.txt>

.. _calibration:

********************
Import a Calibration
********************

Purpose of this Chapter
=======================

The aim of this chapter is to explain how you can create a calibration. This
will be presented by taking a fictional example.

.. figure:: ../../graphics/calibration.svg
   :width: 100%

Overview
========

During a deployment, the efficiency of the instruments decreases, which also influences
the data quality. Thus a pre-calibration and a post-calibration will be performed to
analyze this effect. These calibrations will be used to create calibration functions
that will be applied on the data to improve the data quality. These calibration functions
have to be stored in the database to retrace the process chain. A calibration function
has a function type and several calibration parameters that are required for calculations.

Create a Calibration
====================

In this chapter, we will create a pre and post-calibration for the ICH unit. The database
allows you to create calibrations for single components (e.g., PT100 sensor) or assembled
components (e.g., ICH unit). Depending on the deployment, it will be determined if the
calibration is a pre- or post-calibration. For example, suppose your instrument was deployed
from 01.01.2020 to 01.01.2021. In that case, the calibration with the latest timestamp before
01.01.2020 is the pre-calibration, and the calibration with the earliest timestamp after
01.01.2021 is the post-calibration. If a calibration was performed over several days, it’s
recommended to use the last timestamp and to create only one entry for it instead of
creating an entry for each day.

Create Parameters
-----------------

Via Python
^^^^^^^^^^

First, we define the metadata in the dictionary **METADATA**. After it, we iterate
over the dictionary and create database entries for the parameters. The created
entries will be stored in the dictionary *parameters* for later purposes.

.. code-block:: python

    from IAGOS.apps.database.components import models as components

    METADATA = {"A": "ppm", "B": "ppm"}
    parameters = {}
    for name in METADATA:
        unit = METADATA[name]
        parameters[name], _ = components.Parameter.objects.get_or_create(name=name, unit=unit)

Via Web Interface
^^^^^^^^^^^^^^^^^

1. Make sure that you have the permissions to create new entries *(admin)*
2. Go to the menu *Components* |rarr| *Parameters*
3. Create the parameters **A** (Unit: **ppm**) and **B** (Unit: **ppm**) by clicking the button *create**

Create Calibrations
-------------------

After we created the parameters, we will create metadata of the calibrations.
Each calibration has to be assigned to a component and has a timestamp. Optional, you
can set a name and a description for better identification.

Via Python
^^^^^^^^^^

.. code-block:: python

    from datetime import datetime
    from IAGOS.apps.database.components import models as components

    pre_calibration, _ = components.Calibration.objects.get_or_create(
        component=instances["ICH"], name="Calibration X", timestamp=datetime(2019, 12, 24)
    )
    post_calibration, _ = components.Calibration.objects.get_or_create(
        component=instances["ICH"], name="Calibration Y", timestamp=datetime(2022, 1, 6)
    )

Via Web Interface
^^^^^^^^^^^^^^^^^

1. Make sure that you have the permissions to create new entries *(admin)*
2. Go to the menu *Components*  |rarr| *Calibration*
3. Create the calibrations *Calibration X* and *Calibration Y* by clicking the button on the top right.

    * Name: **Calibration X**, Component: **ICH**, Timestamp: **2019-12-24**
    * Name: **Calibration Y**, Component: **ICH**, Timestamp: **2022-01-06**

Assign Calibration Parameters
-----------------------------

Each calibration parameter refers to the calibration and to the metadata of the
parameter which we already created in the last sections. Based on it, we can
create the calibration parameters. We create the two parameters **A** and
**B** for the pre-calibration and two parameters for the post-calibration.

Via Python
^^^^^^^^^^

.. code-block:: python

    from IAGOS.apps.database.components import models as components

    pre_a, _ = components.CalibrationParameter.objects.get_or_create(
        parameter=parameters["A"], calibration=pre_calibration, value=42
    )
    post_a, _ = components.CalibrationParameter.objects.get_or_create(
        parameter=parameters["A"], calibration=post_calibration, value=40.5
    )
    pre_b, _ = components.CalibrationParameter.objects.get_or_create(
        parameter=parameters["B"], calibration=pre_calibration, value=666
    )
    post_b, _ = components.CalibrationParameter.objects.get_or_create(
        parameter=parameters["B"], calibration=post_calibration, value=642
    )

Via Web Interface
^^^^^^^^^^^^^^^^^

1. Make sure that you have the permissions to create new entries *(admin)*
2. Go to the menu *Components* |rarr| *Calibrations*
3. Click on *Details* to see the detail view of the calibration.
4. Click on the button **Parameter** to assign a new parameter
5. Select the parameter and enter the value.

Create a Calibration Function
=============================

.. important::
    The calibration functions can't be handled via the web interface. You have
    to create them during the import process.

.. code-block:: python

    from IAGOS.apps.database.components import models as components

    function_type, _ = components.FunctionType.objects.get_or_create(
        name="Linear interpolation"
    )
    function, _ = components.Function.objects.get_or_create(
        function_type=function_type, name="Function"
    )
    function.calibration_parameters.add(pre_a)
    function.calibration_parameters.add(post_a)
    function.save()