.. role:: python(code)
   :language: python

.. |Ex| replace:: E\ :sub:`x`
.. |Ey| replace:: E\ :sub:`y`
.. |Hx| replace:: H\ :sub:`x`
.. |Hy| replace:: H\ :sub:`y`
.. |Hz| replace:: H\ :sub:`z`
.. |Zxy| replace:: Z\ :sub:`xy`
.. |Zxx| replace:: Z\ :sub:`xx`
.. |Zyx| replace:: Z\ :sub:`yx`
.. |Zyy| replace:: Z\ :sub:`yy`
.. |fs| replace:: f\ :sub:`s`

Using configuration files
-------------------------

Configuration files are a powerful way to set multiple parameters. For more information about the parameters in configuration files, please see :doc:`Configuration files <../features/configuration>`. 

A user supplied configuration only needs to include non-default parameters (those where the values are changed). Details on the easiest way to create a configuration file are provided :doc:`here <../features/configuration>`.

To use configuration files, they should be specified when loading in a project. An example configuration file is shown below. 

.. literalinclude:: ../_static/examples/tutorial/tutorialconfig.ini
    :linenos:
    :language: text

This configuration has been named *dec8_5* because it uses a decimation scheme of 8 decimation levels with 5 evaluation frequencies per level. Configuration names should be meaningful and unique to allow disambiguation and easy repeatability. Configuration file names are stored in dataset comments to ensure transparency.

The below shows how to load a project with a configuration specified by a configuration file.

.. literalinclude:: ../../../examples/tutorial/usingConfigFiles.py
    :linenos:
    :language: python
    :lines: 1-6
    :lineno-start: 1

The configuration file above specifies a spectra directory to use. For more on what this means, please see the :doc:`Multiple spectra <multiple-spectra>` page. The result is that all project methods which use the :class:`~resistics.project.data.ProjectData` instance loaded with the configuration file will pick up the configuration parameters.

Calculating spectra is now straightforward. When passing the :class:`~resistics.project.data.ProjectData` instance loaded with the tutorialConfig.ini configuration file to :meth:`~resistics.project.spectra.calculateSpectra`, the **specdir** option in the configuration file will automatically be picked up.

.. literalinclude:: ../../../examples/tutorial/usingConfigFiles.py
    :linenos:
    :language: python
    :lines: 8-12
    :lineno-start: 8

The spectra will be stored in the following location:

.. code-block:: text

    exampleProject
    ├── calData 
    ├── timeData   
    │   └── site1
    |       |── dataFolder1
    │       |── dataFolder2
    |       |──     .     
    |       |──     .
    |       |──     .
    |       └── dataFolderN     
    ├── specData
    │   └── site1
    |       |── dataFolder1
    |       |   └── dec8_5
    |       |   
    │       |── dataFolder2
    |       |   └── dec8_5    
    |       |──     .     
    |       |──     .
    |       |──     .
    |       └── dataFolderN
    |           └── dec8_5        
    ├── statData
    ├── maskData   
    ├── transFuncData 
    ├── images
    └── mtProj.prj

To process these spectra, it's a similar situation. Passing the :class:`~resistics.project.data.ProjectData` instance loaded with the tutorialConfig.ini configuration file to :meth:`~resistics.project.transfunc.processProject`, the **specdir** option in the configuration file will automatically be picked up.

.. literalinclude:: ../../../examples/tutorial/usingConfigFiles.py
    :linenos:
    :language: python
    :lines: 14-19
    :lineno-start: 14

Now the plot using the new configuration parameters (8 decimation levels with 5 evaluation frequencies per decimation level) can be compared to the default parameterisation.

.. figure:: ../_static/examples/tutorial/usingConfigFiles_viewimp.png
    :align: center
    :alt: alternate text
    :figclass: align-center

    Using the customised configuration

.. figure:: ../_static/examples/tutorial/simpleRun_viewimp_multplot.png
    :align: center
    :alt: alternate text
    :figclass: align-center

    Using the default configuration

Complete example script
~~~~~~~~~~~~~~~~~~~~~~~
For the purposes of clarity, the complete example script is provided below.

.. literalinclude:: ../../../examples/tutorial/usingConfigFiles.py
    :linenos:
    :language: python