Introduction to Darfix (6.x)
============================

**darfix** is a Python library for the analysis of dark-field microscopy data. darfix is to be used as a workflow, together with a graphical user interface based on `Orange3 <https://github.com/biolab/orange3>`_.

The aim of this tutorial is to guide you into correctly executing darfix into a correct
analysis of your images.

This tutorial will show how to use the 3 main darfix parts:

#. **Load the data** and select the different motors (dimensions). Select a transformation technique (RSM, magnification), if needed.
#. **Pre-analysis of the images** by applying several operations like region of interest, noise removal and shift correction.
#. Apply DFXM analysis to the images. The DFXM techniques currently in darfix are
    * **Rocking curve imaging**: Fits the data along the z-dimension (pixel by pixel) according to a Gaussian distribution. After computation, the maps of the fit parameters will be shown. The fitted data is saved on disk in HDF5 format.
    * **Grain plot**: Several maps are plotted which can be exported into a single file: COM, FWHM, skewness, kurtosis (for every dimension). There is also mosaicity and orientation distribution maps in case of 2D datasets.
    * **Blind source separation**: An experimental technique that uses different blind source separation techniques to find grains along the dataset, tests with different datasets have shown good results with techniques like NMF, NNICA, and NMF+NNICA.

Pre-requisites
--------------

1. The data format should either **HDF5** or **EDF**.

.. warning::
    
    EDF is a legacy format and will no longer be supported natively starting from Darfix 4.0. 
    
    However, it is possible to `convert EDF to HDF5 <./edf_conversion.html>`_ to load the data in Darfix.


2. Motor information should be contained in metadata.
    * For HDF5: a group should contain all positioners datasets.
    * for EDF: headers should contain motors_mne information.
3. The data should be a stack of images (dimensions: `N_frames x W x H`).

Installing darfix
------------------

At ESRF
"""""""

``darfix`` is already installed on the SLURM cluster. To run it, follow these steps:

1. Connect to the cluster

.. code-block:: bash

    ssh -X cluster-access

2. Request an interactive job on a node with appropriate resources

.. code-block:: bash

    salloc -p interactive –x11 srun –pty bash

3. Load the darfix module

.. code-block:: bash

    module load darfix

4. Launch darfix

.. code-block:: bash

    darfix

The following window should then appear:

.. image:: img/introduction/canvas.png

Outside ESRF
""""""""""""

Install ``darfix`` according to the instructions in :ref:`Installation`

Then, you can launch darfix by running

.. code-block:: bash

    darfix

and get the same window as above.

Workflow creation
-----------------

To get a workflow quickly, you can start from one of the **workflow examples**.

**Help > Example Workflows**

.. image:: img/introduction/examples.png

Three example workflows are available.

For quick start, have a look at **EXAMPLE: Process a fake 3D dataset**.

The preprocessing chain is already wired up and the inputs are pre-filled.

You only need to connect the last widget to the analysis widget you want to try (grain plot, rocking curves, z-sum or strain plot).

Draw a link by clicking on the output port of the last connected widget and dragging it to the target widget:

.. image:: img/introduction/link_creation.png

.. tip::

   To navigate through a workflow:

   * After configuring a widget, click **OK** to validate and pass data to the next widget.
   * For preprocessing widgets (*ROI Selection*, *Noise Removal*), click **Apply** first to preview the result, then **OK** to confirm.