nafuma/docs/modules/xrd.md

# XRD

This module contains functions to view diffractogram data from several different sources. The Some features include:

- Allows the user to plot the data in wavelength independent parameters (d, 1/d, q, q{math}`^2`, q{math}`^4`), or translated to CuK{math}`\alpha` or MoK{math}`\alpha` allowing comparison between diffractograms obtained with different wavelengths
- Plotting in interactive mode within Jupyter Notebook using the `ipywidgets`-package allowing real-time change of (certain) parameters
- Plotting reflection ticks and/or reflection indices from multiple simulated reflection tables (generated by VESTA) for comparison
- Plotting series of diffractograms in stacked mode (including ability to rotate the view for a 3D-view) or as a heatmap



## 1 Compatible file formats

The module is partially built as a wrapper around [pyFAI](https://github.com/silx-kit/pyFAI) (Fast Azimuthal Integrator) developed at the ESRF for integrating 2D diffractograms from the detectors they have. Given a suitable calibration file (`.poni`), the XRD-module will automatically integrate any file pyFAI can integrate. Upon running in interactive mode, the integration is only done once, but it is advised to perform integration of many diffractograms in a separate processing step and saving the results as `.xy`-files, as the integration will run again each time the function is called.

In addition to this, it can also read the `.brml`-files produced by Bruker-instruments in the RECX-lab at the University of Oslo.

## 2 Basic usage

Plotting diffractograms is done by calling the `xrd.plot.plot_diffractogram()`-function, which takes two dictionaries as arguments: `data`, containing all data specific information and `options` which allows customisation of a range of different parameters. The `options`-argument is optional, and the function will contains a bunch of default values to make an as good plot as possible to begin with.

**Example #1: Single diffractogram**

```py
import nafuma.xrd as xrd

data = {
    'path': 'path/to/data/diffractogram.brml'
}

options = {
    'reflections_data': [
        {'path': 'reflections_phase_1.txt', 'min_alpha': 0.1, 'reflection_indices': 4, 'label': 'Phase 1', 'text_colour': 'black'},
	{'path': 'reflections_phase_2.txt', 'min_alpha': 0.1, 'reflections_indices': 4, 'label': 'Phase 2', 'text_colour': 'red'}
    ],
    'hide_y_ticklabels': True,
    'hide_y_ticks': True
} 


diff, fig, ax = xrd.plot.plot_diffractogram(data=data, options=options)
```

The return value `diff` is a list containing one `pandas.DataFrame` per diffractogram passed, in the above example only one. `fig` and `ax` are `matplotlib.pyplot.Figure`- and `matplotlib.pyplot.Axes`-objects, respectively.

**Example #2: 2D diffractogram from ESRF requiring integration**

```py
import nafuma.xrd as xrd

data = {
    'path': 'path/to/data/2d_diffractogram.edf',
    'calibrant': 'path/to/calibrant/calibrant.poni',
    'nbins': 3000
}

diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
```

In this case we did not specify any options and will thus only use default values, and we stored both `fig` and `ax` in the variable `_` as we do not intend to use these.

**Example #3: Plotting with interactive mode**

This will can be done within a Jupyter Notebook, and will allow the user to tweak certain parameters real-time instead of having to recall the function every time.

```py
import nafuma.xrd as xrd

data = {
    'path': 'path/to/data/diffractogram.brml'
}

options = {
    'interactive': True
}


diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
```

**Example #4: Plotting multiple diffractograms as stacked plots**

Instead of passing just a string, you can pass a lsit of filenames. This will be plotted sequentially, with offsets, if desired (`offset_x` and `offset_y`). Default values of `offset_y` is 1 if less than 10 diffractograms have been passed, and 0.1 if more than 10 diffractograms are passed. When plotting series data (e.g. from *in situ* or *operando* measurements), a smaller offset is suitable. Keep in mind that these values only makes sense when the diffractograms are normalised (`'normalise': True`) - if not, the default offsets will be way too small to be noticeable.

```py
import nafuma.xrd as xrd

data = {
    'path': ['path/to/data/diffractogram_1.brml', 'path/to/data/diffractogram_2.brml']
}


options = {
    'offset_y': 0.1,
    'offset_x': 0.05,
}


diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
```


**Example #5: Plotting series data as heatmap**

This differs very little from above, except that heatmaps are probably nonesense if not used on series data, and that you don't want offset in heatmaps. 

```py
import nafuma.xrd as xrd

list_of_data = ['data_1.brml', 'data_2.brml'. ...., 'data_n.brml']

data = {
    'path': lists_of_data
}


options = {
    'heatmap': True
}


diff, _ = xrd.plot.plot_diffractogram(data=data, options=options)
```