Metadata-Version: 2.1
Name: MagnetoResistance-tool
Version: 0.0.4
Summary: Tool to create calibration matrix allowing to correct for magneto-resistance in resisitive sensors.
Author: Nowa Ammerlaan
Author-email: <nowa.ammerlaan@ru.nl>
Maintainer: Nowa Ammerlaan
Maintainer-email: <nowa.ammerlaan@ru.nl>
License: GPL-3.0-or-later
Project-URL: homepage, https://gitlab.science.ru.nl/hfml/MRcalib
Project-URL: repository, https://gitlab.science.ru.nl/hfml/MRcalib
Keywords: magneto-resistance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: numpy
Requires-Dist: pandas
Provides-Extra: plot
Requires-Dist: matplotlib; extra == "plot"

Simple tool to generate a calibration correction matrix for resistive sensors in a magnetic field.

## Installation

`pip install MagnetoResistance-tool` or `pip install --user MagnetoResistance-tool`.

## Usage
```
MRcalib [-h] [-o FILE_OUT] [-p] [-B FIELD_ORDER] [-T TEMP_ORDER] [-v] file_in

Fit magneto-resistance data and create calibration matrix.

positional arguments:
file_in               input file defining the measurement data

options:
-h, --help            show this help message and exit
-o FILE_OUT, --out FILE_OUT
calibration matrix output file
-p, --plot            plot the data and fits
-B FIELD_ORDER, --field FIELD_ORDER
order of polynomial to use for fitting with respect to the magnetic field
-T TEMP_ORDER, --temperature TEMP_ORDER
order of polynomial to use for fitting with respect to the measured temperature
-v, --verbose         print values while calculating
```

The input file `file_in` describes the data files to use.
It should be a tab delimited file specifying first the path of the data file to use, next the names of the field and temperature columns to use, and finally the parameters for the outlier rejection algorithm.
Here's an example:

```
SD-3-7_V1-1-5_V2-20-6_BSweep_1,33K.001.dat	Field	Probe_Temp	 0	0	0	0
SD-3-7_V1-1-5_V2-20-6_BSweep_2,17K.001.dat	Field	Probe_Temp	 0	0	0	0
SD-3-7_V1-1-5_V2-20-6_BSweep-1,3K.001.dat	Field	Probe_Temp	 0	0	0	0
SD-3-7_V1-1-5_V2-20-6_BSweep-1,89K.001.dat	Field	Probe_Temp	 50	5	50	0.04
SD-3-7_V1-1-5_V2-20-6_BSweep-2,6K.001.dat	Field	Probe_Temp	 25	0.8	0	0
d3_mag_sweep_4p2K.001.dat	B	T-A-K	 0	0	150	0.5
d3_mag_sweep_10K.001.dat	B	T-A-K	 0	0	20	0.04
d3_mag_sweep_15K.001.dat	B	T-A-K	 0	0	20	0.06
d3_mag_sweep_20K.002.dat	B	T-A-K	 0	0	20	0.06
d3_mag_sweep_25K.001.dat	B	T-A-K	 0	0	30	0.06
```

The outlier rejection algorithm takes a rolling median of the data and rejects any points outside of this rolling median.
The first two parameters control the outlier rejection in terms of field, the second set of two parameters does the same in terms of temperature.
In each set the first parameter specifies the size of the window to take the rolling median over, and the second specifies how big the difference has to be for a point to be considered an outlier.
Setting either of these two parameters to zero disables outlier rejection for this variable.
To summarize, the syntax of the input file is:
```
<PATH>	<FIELD COLUMN NAME>	<TEMPERATURE COLUMN NAME> <FIELD ROLLING MEDIAN WINDOW> <FIELD REJECTION THRESHOLD> <TEMPERATURE ROLLING MEDIAN WINDOW> <TEMPERATURE REJECTION THERSHOLD>
```

Once the input file is created the calibration matrix creation tool can be called:
```
MRcalib <PATH TO INPUT FILE>
```

All data is sliced up in slices of equal field. For each field the actual temperature is fitted against the measured temperature using the order specified by the `--temperature` or `-T` argument (defaults to 1 if unspecified).
Next each of these fitting parameters is fitted against field using the order specified by the `--field` or `-B` argument (defaults to 3 if unspecified).
The optional arguments `--verbose` (`-v`) and `--plot` (`-p`) allow to check and visualize each step.
Plotting requires matplotlib.

When plotting is enabled the first set of plots visualizes which points are accepted by the outlier rejection algorithm and which ones are rejected.
This allows to fine tune the parameters of the algorithm to achieve the desired result.
The second set of plots visualizes the first round of fitting (actual temperature versus measured temperature) for a maximum of 10 different fields.
The final plot allows for performing a sanity check.
The calculated correction is applied to the initial set of input files.
This should create a series of more or less flat lines since the actual temperature for each input data file is the same.
If this is not the case than this can indicate that the actual temperature was drifting in one of the input data files.
Increasing or decreasing the order of the fitting polynomials (`--field`) and `(--temperature`) can help to achieve a better result.
In general higher is better, but requires more computation and therefore more time and the improvement return tends to diminish the higher the order becomes.

The generated calibration matrix is written as `calib.txt` into the same directory as the input file was read from.
This can be overridden using the `--out` or `-o` argument.

To apply the calculated calibration matrix to your actual data, call the correction function from your python data analysis script as follows:
```
from MRcalib import MRcorrect

<YOUR CODE GOES HERE>

MRcorrect(<PATH TO CALIBRATION FILE>, <FIELD DATA>, <TEMPERATURE DATA>)

<YOUR CODE GOES HERE>
```

This function will return the actual temperature and its uncertainty for a given field and measured temperature. The field and temperature data can be provided as an integer, float, list, numpy array, pandas dataframe or pandas series.

## Bugs and contributions

If you found a problem, please open a new ticket in the issues pane of our GitLab page.
And if you want to contribute than merge requests are also welcome on our GitLab page.

## License

The code in this repository is licensed under the GPL-3+ license
