Data Classes

The package provides several classes for storing frequency-domain EM sensor data.

Channel Data

The sitem1d.ChannelData class provides the basic representation of complex relative magnetic field data of one EM channel. More on the definition of a channel below. ChannelData contains only an array of complex values, but provides an interface to the typical inphase/quadrature and amplitude/phase representations of EM data.

Input

The class is initialized by arrays or scalars of inphase and quadrature values. These must be of type float and any arrays must have only one dimension.

>>> sitem1d.ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
sitem1d.ChannelData object:
   [1.+1.j 2.+2.j 3.+3.j] (3 records)

The instance can also be initialized from a complex object and the following statement will result in an identical instance:

>>> sitem1d.ChannelData.from_complex([1.0+1.0j, 2.0+2.0j, 3.0+3.0j])
sitem1d.ChannelData object:
  [1.+1.j 2.+2.j 3.+3.j] (3 records)

An optional unit and label can be added to the instance:

>>> ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0], unit="ppm", label="Label")
sitem1d.ChannelData object:
  [1.+1.j 2.+2.j 3.+3.j] (3 records)
  label: Label
  unit: ppm

While scalar input is allowed, the value will be converted to an array.

>>> hshp = ChannelData(1.0, 1.0)
>>> hshp.iq
array([1.+1.j])

Properties

The instance contains the properties for the all representations of the complex values of one EM channel (e.g. one frequency + transmitter/receiver configuration). The data is traditionally represented by the inphase (real) and quadrature (imaginary) compents of the

hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0], unit="ppm", label="Label")

sitem1d.ChannelData properties
Property	Value
`hshp.iq`	array([1.+1.j, 2.+2.j, 3.+3.j])
`hshp.z`	array([1.+1.j, 2.+2.j, 3.+3.j])
`hshp.inphase`	array([1., 2., 3.])
`hshp.quadrature`	array([1., 2., 3.])
`hshp.amplitude`	array([1.41421356, 2.82842712, 4.24264069])
`hshp.phase`	array([45., 45., 45.])
`hshp.phase_radian`	array([0.78539816, 0.78539816, 0.78539816])
`hshp.n_records`	3
`hshp.unit`	ppm
`hshp.label`	Label

Note

Note that the properity z is an alias of iq and kept for historical reasons.

The data content in ChannelData is protected against modification by any means other than the intented operators.

Properties are immutable

>>> hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> hshp.inphase = 0.0
Traceback (most recent call last):
  File "C:\python\anaconda3\envs\py3p8\lib\code.py", line 90, in runcode
    exec(code, self.locals)
  File "<input>", line 1, in <module>
AttributeError: can't set attribute

Properties return copies of the variables and not references

>>> hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> inphase = hshp.inphase
>>> inphase[0] = 1000
>>> hshp.inphase
array([1., 2., 3.])

Operators

The ChannelData object allows operators:

Slicing [Iterable]: Selecting a subset of the data container.

>>> hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> hshp[1:]
sitem1d.ChannelData object:
  [2.+2.j 3.+3.j] (2 records)

Addition +: Complex addition of two data sets

>>> a = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> b = ChannelData([1.0, 1.0, 1.0], [1.0, 1.0, 1.0])
>>> a + b
sitem1d.ChannelData object:
  [2.+2.j 3.+3.j 4.+4.j] (3 records)

Subtraction -: Complex subtraction of two data sets

>>> a = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> b = ChannelData([1.0, 1.0, 1.0], [1.0, 1.0, 1.0])
>>> a - b
sitem1d.ChannelData object:
  [0.+0.j 1.+1.j 2.+2.j] (3 records)

Calibration Operator *

The * operator is reserved for modification of the content by appropriate other classes. . It can be used between ChannelData and any class that has a calibrate_channel_data method, which returns a calibrated ChannelData object. One example of such a functionality is given by
```
>>> from sitem1d.cal import GainPhaseOffsetCal
>>> hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> cal = GainPhaseOffsetCal(gain=2)
>>> hshp * cal
sitem1d.ChannelData object:
   [2.+2.j 4.+4.j 6.+6.j] (3 records)
```

Methods

ChannelData only contains three methods.

clone(): Return a full copy of the ChannelData instance.

>>> hshp = ChannelData([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> hshp.clone()
sitem1d.ChannelData object:
  [1.+1.j 2.+2.j 3.+3.j] (3 records)

Note: hshp.clone() is equivalent to hshp[:]

ChannelData.iq2ap(inphase, quadrature): Class method to convert inphase/quadrature to amplitude/phase notation.

>>> amplitude, phase = ChannelData.iq2ap([1.0, 2.0, 3.0], [1.0, 2.0, 3.0])
>>> amplitude, phase
(array([1.41421356, 2.82842712, 4.24264069]), array([45., 45., 45.]))

The method return phase as degree by default, but this can be changed:

>>> ChannelData.iq2ap([1.0, 2.0, 3.0], [1.0, 2.0, 3.0], degree=False)
(array([1.41421356, 2.82842712, 4.24264069]), array([0.78539816, 0.78539816, 0.78539816]))

ChannelData.iq2ap(amplitude, phase): Inverse transformation from amplitude/phase to inphase/quadrature. The methods assumes that phase in given in degree, which can be changed by passing degree=False keyword.
```
>>> ChannelData.ap2iq(amplitude, phase)
(array([1., 2., 3.]), array([1., 2., 3.]))
```

Channel Definition

The class sitem1d.ChannelDefinition is a light data class that contains metadata of a given channel. The metadata contains the following properties:

transmitter frequency in Hz
separation (spacing) between the transmitter (tx) and receiver (rx) coils in meter
a string describing the transmitter/receiver coil configuration. Currently supported are hcp (horizontal coplanar) and vpc vertical coplanar.
[Optional] separation (spacing) between the transmittter (tx) and bucking (bx) coils in meter.

>>> from sitem1d import ChannelDefinition
>>> ChannelDefinition(18325., 1.660, "hcp")
Channel Definition (f18325r1p66hcp):
  Transmitter frequency: 18325.0 Hz
  Rx-Tx coil separation: 1.66 m
  Rx-Tx coil mode      : hcp (flag: 0)
  Bx-Tx coil separation: N/A

respectively with bucking coil:

>>> ChannelDefinition(18325., 1.660, "hcp", 1.035)
Channel Definition (f18325r1p66hcpbx):
  Transmitter frequency: 18325.0 Hz
  Rx-Tx coil separation: 1.66 m
  Rx-Tx coil mode      : hcp (flag: 0)
  Bx-Tx coil separation: 1.035 m

The class creates a unique id based on the properties (in this case f18325r1p66hcp/f18325r1p66hcpbx without/with the bucking coil definition).