resistics.calibrate module¶

Functions and classes for instrument and sensor calibration of data

Calibration data should be given in the frequency domain and has a magnitude and phase component (in radians). Calibration data is the impulse response for an instrument or sensor and is usually deconvolved (division in frequency domain) from the time data.

Notes

Calibration data for induction coils is given in mV/nT. Because this is deconvolved from magnetic time data, which is in mV, the resultant magnetic time data is in nT.

pydantic model resistics.calibrate.CalibrationData[source]¶

Bases: resistics.common.WriteableMetadata

Class for holding calibration data

Calibration is usually the transfer function of the instrument or sensor to be removed from the data. It is expected to be in the frequency domain.

Regarding units:

Magnitude units are dependent on use case
Phase is in radians

Show JSON schema

{
   "title": "CalibrationData",
   "description": "Class for holding calibration data\n\nCalibration is usually the transfer function of the instrument or sensor\nto be removed from the data. It is expected to be in the frequency domain.\n\nRegarding units:\n\n- Magnitude units are dependent on use case\n- Phase is in radians",
   "type": "object",
   "properties": {
      "file_info": {
         "$ref": "#/definitions/ResisticsFile"
      },
      "file_path": {
         "title": "File Path",
         "type": "string",
         "format": "path"
      },
      "sensor": {
         "title": "Sensor",
         "default": "",
         "type": "string"
      },
      "serial": {
         "title": "Serial",
         "anyOf": [
            {
               "type": "integer"
            },
            {
               "type": "string"
            }
         ]
      },
      "static_gain": {
         "title": "Static Gain",
         "default": 1,
         "type": "number"
      },
      "magnitude_unit": {
         "title": "Magnitude Unit",
         "default": "mV/nT",
         "type": "string"
      },
      "frequency": {
         "title": "Frequency",
         "type": "array",
         "items": {
            "type": "number"
         }
      },
      "magnitude": {
         "title": "Magnitude",
         "type": "array",
         "items": {
            "type": "number"
         }
      },
      "phase": {
         "title": "Phase",
         "type": "array",
         "items": {
            "type": "number"
         }
      },
      "n_samples": {
         "title": "N Samples",
         "type": "integer"
      }
   },
   "required": [
      "serial",
      "frequency",
      "magnitude",
      "phase"
   ],
   "definitions": {
      "ResisticsFile": {
         "title": "ResisticsFile",
         "description": "Required information for writing out a resistics file",
         "type": "object",
         "properties": {
            "created_on_local": {
               "title": "Created On Local",
               "type": "string",
               "format": "date-time"
            },
            "created_on_utc": {
               "title": "Created On Utc",
               "type": "string",
               "format": "date-time"
            },
            "version": {
               "title": "Version",
               "type": "string"
            }
         }
      }
   }
}

field file_path: Optional[pathlib.Path] [Required]¶: Path to the calibration file

field sensor: str = ''¶: Sensor type

field serial: Union[int, str] [Required]¶: Serial number of the sensor

field static_gain: float = 1¶: Static gain to apply

field magnitude_unit: str = 'mV/nT'¶: Units of the magnitude

field frequency: List[float] [Required]¶: Frequencies in Hz

field magnitude: List[float] [Required]¶: Magnitude

field phase: List[float] [Required]¶: Phase

field n_samples: Optional[int] = None¶

Number of data samples

Validated by

validate_n_samples

plot(fig: Optional[plotly.graph_objs._figure.Figure] = None, color: str = 'blue', legend: str = 'CalibrationData') → plotly.graph_objs._figure.Figure[source]¶

Plot calibration data

Parameters

fig (Optional[go.Figure], optional) – A figure if adding the calibration data to an existing plot, by default None
color (str, optional) – The color for the plot, by default “blue”
legend (str, optional) – The legend name, by default “CalibrationData”

Returns

Plotly figure with the calibration data added

Return type

go.Figure

to_dataframe()[source]¶: Convert to pandas DataFrame

pydantic model resistics.calibrate.CalibrationReader[source]¶

Bases: resistics.common.ResisticsProcess

Parent class for reading calibration data

Show JSON schema

{
   "title": "CalibrationReader",
   "description": "Parent class for reading calibration data",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "extension": {
         "title": "Extension",
         "type": "string"
      }
   }
}

field extension: Optional[str] = None¶

pydantic model resistics.calibrate.InstrumentCalibrationReader[source]¶

Bases: resistics.calibrate.CalibrationReader

Parent class for reading instrument calibration files

Show JSON schema

{
   "title": "InstrumentCalibrationReader",
   "description": "Parent class for reading instrument calibration files",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "extension": {
         "title": "Extension",
         "type": "string"
      }
   }
}

run(metadata: resistics.spectra.SpectraMetadata) → resistics.calibrate.CalibrationData[source]¶

field extension: Optional[str] = None¶

field name: Optional[str] [Required]¶

Validated by

validate_name

pydantic model resistics.calibrate.SensorCalibrationReader[source]¶

Bases: resistics.calibrate.CalibrationReader

Parent class for reading sensor calibration files

Use this reader for induction coil calibration file readers

Examples

A short example to show how naming substitution works

>>> from pathlib import Path
>>> from resistics.testing import time_metadata_1chan
>>> from resistics.calibrate import SensorCalibrationReader
>>> calibration_path = Path("test")
>>> metadata = time_metadata_1chan()
>>> metadata.chans_metadata["chan1"].sensor = "example"
>>> metadata.chans_metadata["chan1"].serial = "254"
>>> calibrator = SensorCalibrationReader(extension=".json")
>>> calibrator.file_str
'IC_$sensor$extension'
>>> file_path = calibrator._get_path(calibration_path, metadata, "chan1")
>>> file_path.name
'IC_example.json'

If the file name has a different pattern, the file_str can be changed as required.

>>> calibrator = SensorCalibrationReader(file_str="$sensor_$serial$extension", extension=".json")
>>> file_path = calibrator._get_path(calibration_path, metadata, "chan1")
>>> file_path.name
'example_254.json'

Show JSON schema

{
   "title": "SensorCalibrationReader",
   "description": "Parent class for reading sensor calibration files\n\nUse this reader for induction coil calibration file readers\n\nExamples\n--------\nA short example to show how naming substitution works\n\n>>> from pathlib import Path\n>>> from resistics.testing import time_metadata_1chan\n>>> from resistics.calibrate import SensorCalibrationReader\n>>> calibration_path = Path(\"test\")\n>>> metadata = time_metadata_1chan()\n>>> metadata.chans_metadata[\"chan1\"].sensor = \"example\"\n>>> metadata.chans_metadata[\"chan1\"].serial = \"254\"\n>>> calibrator = SensorCalibrationReader(extension=\".json\")\n>>> calibrator.file_str\n'IC_$sensor$extension'\n>>> file_path = calibrator._get_path(calibration_path, metadata, \"chan1\")\n>>> file_path.name\n'IC_example.json'\n\nIf the file name has a different pattern, the file_str can be changed as\nrequired.\n\n>>> calibrator = SensorCalibrationReader(file_str=\"$sensor_$serial$extension\", extension=\".json\")\n>>> file_path = calibrator._get_path(calibration_path, metadata, \"chan1\")\n>>> file_path.name\n'example_254.json'",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "extension": {
         "title": "Extension",
         "type": "string"
      },
      "file_str": {
         "title": "File Str",
         "default": "IC_$sensor$extension",
         "type": "string"
      }
   }
}

field file_str: str = 'IC_$sensor$extension'¶

run(dir_path: pathlib.Path, metadata: resistics.spectra.SpectraMetadata, chan: str) → resistics.calibrate.CalibrationData[source]¶

Run the calibration file reader

Parameters

dir_path (Path) – The directory with calibration files
metadata (SpectraMetadata) – TimeData metadata
chan (str) – The channel for which to search for a calibration file

Returns

The calibration data

Return type

CalibrationData

Raises

CalibrationFileNotFound – If the calibration file does not exist

read_calibration_data(file_path: pathlib.Path, chan_metadata: resistics.time.ChanMetadata) → resistics.calibrate.CalibrationData[source]¶

Read calibration data from a file

The is implemented as a separate function for anyone interested in reading a calibration file separately from the run function.

Parameters

file_path (Path) – The file path of the calibration file
chan_metadata (ChanMetadata) – The channel metadata

Raises

NotImplementedError – To be implemented in child classes

pydantic model resistics.calibrate.SensorCalibrationJSON[source]¶

Bases: resistics.calibrate.SensorCalibrationReader

Read in JSON formatted calibration data

Show JSON schema

{
   "title": "SensorCalibrationJSON",
   "description": "Read in JSON formatted calibration data",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "extension": {
         "title": "Extension",
         "default": ".json",
         "type": "string"
      },
      "file_str": {
         "title": "File Str",
         "default": "IC_$sensor$extension",
         "type": "string"
      }
   }
}

field extension: str = '.json'¶

read_calibration_data(file_path: pathlib.Path, chan_metadata: resistics.time.ChanMetadata) → resistics.calibrate.CalibrationData[source]¶

Read the JSON calibration data

Parameters

file_path (Path) – The file path of the JSON calibration file
chan_metadata (ChanMetadata) – The channel metadata. Note that this is not used but is kept here to ensure signature match to the parent class

Returns

The calibration data

Return type

CalibrationData

pydantic model resistics.calibrate.SensorCalibrationTXT[source]¶

Bases: resistics.calibrate.SensorCalibrationReader

Read in calibration data from a TXT file

In general, JSON calibration files are recommended as they are more reliable to read in. However, there are cases where it is easier to write out a text based calibration file.

The format of the calibration file should be as follows:

Serial = 710
Sensor = LEMI120
Static gain = 1
Magnitude unit = mV/nT
Phase unit = degrees
Chopper = False

CALIBRATION DATA
1.1000E-4       1.000E-2        9.0000E1
1.1000E-3       1.000E-1        9.0000E1
1.1000E-2       1.000E0     8.9000E1
2.1000E-2       1.903E0     8.8583E1

See also

SensorCalibrationJSON: Reader for JSON calibration files

Show JSON schema

{
   "title": "SensorCalibrationTXT",
   "description": "Read in calibration data from a TXT file\n\nIn general, JSON calibration files are recommended as they are more reliable\nto read in. However, there are cases where it is easier to write out a text\nbased calibration file.\n\nThe format of the calibration file should be as follows:\n\n.. code-block:: text\n\n    Serial = 710\n    Sensor = LEMI120\n    Static gain = 1\n    Magnitude unit = mV/nT\n    Phase unit = degrees\n    Chopper = False\n\n    CALIBRATION DATA\n    1.1000E-4       1.000E-2        9.0000E1\n    1.1000E-3       1.000E-1        9.0000E1\n    1.1000E-2       1.000E0     8.9000E1\n    2.1000E-2       1.903E0     8.8583E1\n\nSee Also\n--------\nSensorCalibrationJSON : Reader for JSON calibration files",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "extension": {
         "title": "Extension",
         "default": ".TXT",
         "type": "string"
      },
      "file_str": {
         "title": "File Str",
         "default": "IC_$sensor$extension",
         "type": "string"
      }
   }
}

field extension: Optional[str] = '.TXT'¶

read_calibration_data(file_path: pathlib.Path, chan_metadata: resistics.time.ChanMetadata) → resistics.calibrate.CalibrationData[source]¶

Read the TXT calibration data

Parameters

file_path (Path) – The file path of the JSON calibration file
chan_metadata (ChanMetadata) – The channel metadata. Note that this is not used but is kept here to ensure signature match to the parent class

Returns

The calibration data

Return type

CalibrationData

field file_str: str = 'IC_$sensor$extension'¶

field name: Optional[str] [Required]¶

Validated by

validate_name

pydantic model resistics.calibrate.Calibrator[source]¶

Bases: resistics.common.ResisticsProcess

Parent class for a calibrator

Show JSON schema

{
   "title": "Calibrator",
   "description": "Parent class for a calibrator",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "chans": {
         "title": "Chans",
         "type": "array",
         "items": {
            "type": "string"
         }
      }
   }
}

field chans: Optional[List[str]] = None¶: List of channels to calibrate

run(dir_path: pathlib.Path, spec_data: resistics.spectra.SpectraData) → resistics.spectra.SpectraData[source]¶: Run the instrument calibration

pydantic model resistics.calibrate.InstrumentCalibrator[source]¶

Bases: resistics.calibrate.Calibrator

Show JSON schema

{
   "title": "InstrumentCalibrator",
   "description": "Parent class for a calibrator",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "chans": {
         "title": "Chans",
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "readers": {
         "title": "Readers",
         "type": "array",
         "items": {
            "$ref": "#/definitions/InstrumentCalibrationReader"
         }
      }
   },
   "required": [
      "readers"
   ],
   "definitions": {
      "InstrumentCalibrationReader": {
         "title": "InstrumentCalibrationReader",
         "description": "Parent class for reading instrument calibration files",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "extension": {
               "title": "Extension",
               "type": "string"
            }
         }
      }
   }
}

field readers: List[resistics.calibrate.InstrumentCalibrationReader] [Required]¶: List of readers for reading in instrument calibration files

pydantic model resistics.calibrate.SensorCalibrator[source]¶

Bases: resistics.calibrate.Calibrator

Show JSON schema

{
   "title": "SensorCalibrator",
   "description": "Parent class for a calibrator",
   "type": "object",
   "properties": {
      "name": {
         "title": "Name",
         "type": "string"
      },
      "chans": {
         "title": "Chans",
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "readers": {
         "title": "Readers",
         "type": "array",
         "items": {
            "$ref": "#/definitions/SensorCalibrationReader"
         }
      }
   },
   "required": [
      "readers"
   ],
   "definitions": {
      "SensorCalibrationReader": {
         "title": "SensorCalibrationReader",
         "description": "Parent class for reading sensor calibration files\n\nUse this reader for induction coil calibration file readers\n\nExamples\n--------\nA short example to show how naming substitution works\n\n>>> from pathlib import Path\n>>> from resistics.testing import time_metadata_1chan\n>>> from resistics.calibrate import SensorCalibrationReader\n>>> calibration_path = Path(\"test\")\n>>> metadata = time_metadata_1chan()\n>>> metadata.chans_metadata[\"chan1\"].sensor = \"example\"\n>>> metadata.chans_metadata[\"chan1\"].serial = \"254\"\n>>> calibrator = SensorCalibrationReader(extension=\".json\")\n>>> calibrator.file_str\n'IC_$sensor$extension'\n>>> file_path = calibrator._get_path(calibration_path, metadata, \"chan1\")\n>>> file_path.name\n'IC_example.json'\n\nIf the file name has a different pattern, the file_str can be changed as\nrequired.\n\n>>> calibrator = SensorCalibrationReader(file_str=\"$sensor_$serial$extension\", extension=\".json\")\n>>> file_path = calibrator._get_path(calibration_path, metadata, \"chan1\")\n>>> file_path.name\n'example_254.json'",
         "type": "object",
         "properties": {
            "name": {
               "title": "Name",
               "type": "string"
            },
            "extension": {
               "title": "Extension",
               "type": "string"
            },
            "file_str": {
               "title": "File Str",
               "default": "IC_$sensor$extension",
               "type": "string"
            }
         }
      }
   }
}

field readers: List[resistics.calibrate.SensorCalibrationReader] [Required]¶: List of readers for reading in sensor calibration files

run(dir_path: pathlib.Path, spec_data: resistics.spectra.SpectraData) → resistics.spectra.SpectraData[source]¶: Calibrate Spectra data