API reference

Magnetometer data

class magSonify.MagnetometerData

Class providing a high level api for data import and processing

_importAsync(funcs, startDatetime, endDatetime, *args) → None

Runs the CDAS imports defined in funcs asyncronously.

eg.

# User defines each of these methods for data from a particular satellite
funcs = (self._importCdasMagneticField,self._importCdasPosition,self._importCdasPeem)
self._importAsync(funcs,startDatetime,endDatetime,*args)

Parameters

funcs –
Tuple of functions to execute. Each function should be of the form func(startDatetime,endDatetime,*args) -> None. Any imported data should be written to a class attribute.

Warning

These functions should not read data from the class or modify the same attributes as there is no prevention of a race condition. The functions are run simulataneously using threading library.
startDatetime – Start of data range as datetime.datetime or numpy.datetime64
endDatetime – End of data range as datetime.datetime or numpy.datetime64
*args – Arbitrary arguments to be passed to the functions.

_importCdasItemWithExceptions(cdasArgs: tuple, timeSeriesKey: str, targetKeys: dict, returnClassType: type = <class 'magSonify.DataSet.DataSet'>)

Imports cdas data for the given cdasArgs, extracting a dataset.

Parameters

cdasArgs (tuple) – Arguments for data to get, as specified for ai.cdas.get_data(). (str dataview, str dataset, datetime startTime, datetime stopTime, list str variables)
timeSeriesKey (str) – The key that the times are refered to as in CDAS data return
targetKeys (dict) – Dictionary where its values are the keys in CDAs data to include in the data set, and its keys are the keys that should be used to reference these within the data set.
returnClassType (type) – Class used to construct the returned data set, eg. DataSet, DataSet_3D

_interpolateReference(refTimeSeries: magSonify.TimeSeries.TimeSeries) → None: Removes duplicate times, then interpolates data sets magneticField, position and peemIdentifyMagnetosheath to match the specified time series, if the data sets are not None.

convertToMeanFieldCoordinates() → None: Converts the magnetic field data in magneticField to mean field coordinates, saving the output in magneticFieldMeanFieldCoordinates.

Warning

meanField must be specified and contain a 3D dataset with the mean magnetic field.

magneticField must be specified

fillLessThanRadius(radiusInEarthRadii, const=0) → None: Fills all values in the magnetic field with const when the radius is below the specified value.

magneticField: magSonify.DataSet.DataSet_3D: The magnetic field at the satellite

magneticFieldMeanFieldCoordinates: magSonify.DataSet.DataSet_3D: The magnetic field in mean field align coordinates

meanField: magSonify.DataSet.DataSet_3D: The mean magnetic field after a rolling average

peemIdentifyMagnetosheath: magSonify.DataSet.DataSet

Required information for removal of magnetosheath

keys: 'density','velocity_x','flux_x',flux_y'

position: magSonify.DataSet.DataSet_3D: The position of the satellite

removeMagnetosheath() → None

Removes portions of magnetic field data while the satellite is in the magnetosheath.

peemIdentifyMagnetosheath must be specified, otherwise no action is taken.

THEMIS data

class magSonify.THEMISdata

Bases: magSonify.MagnetometerData.MagnetometerData

defaultProcessing(removeMagnetosheath=False, minRadius=4, allowSkipMagnetosheathRemovalIfInsufficientData=True) → None

Performs a standard processing procedure on THEMIS data.

Parameters

removeMagnetosheath – Whether to remove data while in the magnetosheath
minRadius – Radius in earth radii below which to remove magnetic field data

The processing is completed by the following code:

self.interpolate()
self.magneticField.constrainAbsoluteValue(400)
self.meanField = self.magneticField.runningAverage(timeWindow=np.timedelta64(35,"m"))
self.magneticField = self.magneticField - self.meanField
self.fillLessThanRadius(minRadius)
if removeMagnetosheath:
    self.removeMagnetosheath()
self.convertToMeanFieldCoordinates()
self.magneticFieldMeanFieldCoordinates.fillNaN()

importCDAS(startDatetime, endDatetime, satellite='D') → None: Imports magnetic field, position, radial distance and peem data for the designated THEMIS satellite and datetime range. The possible satellite letters are: “A”, “B”, “C”, “D” or “E”. See also: MagnetometerData._importAsync()

interpolate(spacingInSeconds=3) → None

Interpolates data sets magneticField, position and peemIdentifyMagnetosheath to the specified spacing, if they are not None.

A default spacing of 3s is chossen for THEMIS data. This is slightly smaller than the mean sample spacing in the raw magnetometer data of ~3.17 s. Using a consistent value aids in establishing the correspondence between frequencies in sonified audio and the raw data.

DataSet

class magSonify.DataSet(timeSeries: magSonify.TimeSeries.TimeSeries, data)

Represents a data set with multiple data series sampled at common time points.

Parameters

timeSeries – Time series representing the sampling times.
data – Dictionary of numpy arrays containing the data. Convention is for ‘x’, ‘y’ and ‘z’ axes to be represented under the keys int 0, 1 and 2 respectively if they are present. Array should be 1D.

_iterate(lamb: function, replace=False) → dict

Execute function lamb on each component in data

Parameters: lamb (function) – Function to perform on each component, should accept a single parameter which is a 1D numpy array and return an array of the same shape as output.
Returns: A dictionary of numpy arrays with the same keys as in data, unless replace=True, in which case returns None.
Return type: dict | None

Example of how _iterate() is used in SimulateData.applyGaussianWhiteNoise():

def applyGaussianWhiteNoise(self,dataSet:DataSet,noiseMagnitude=1) -> None:
    """Apply gaussian white noise to the input data set"""
    def _applyNoise(inputArray:np.array) -> np.array:
        global rng
        noiseData = rng.normal(0,noiseMagnitude,inputArray.shape)
        return inputArray + noiseData
    
    return type(dataSet)(dataSet.timeSeries,dataSet._iterate(_applyNoise))

_iteratePair(other: DataSet, lamb: function) → DataSet

Execute function lamb on each component pair in self.data and other.data with the same keys. self and other must have the same time series and same keys in data.

Parameters: lamb (function) – Performed on each component, should accept two parameters which are 1D numpy arrays of the same shape and return an array of the same shape as output.

__add__(other) → magSonify.DataSet.DataSet

Supports addition: sumDataSet = firstDataSet + secondDataSet

Requires: firstDataSet.timeSeries == secondDataSet.timeSeries

__getitem__(subscript)

Supports using slices to extract a subsection along the time axis:

myNewDataSet   = myDataSet[100:200]
myOtherDataSet = myDataSet[200:None:3]

__neg__() → magSonify.DataSet.DataSet: Supports negation: negDataSet = - DateSet

__sub__(other) → magSonify.DataSet.DataSet: Supports subtraction: diffDataSet = firstDataSet - secondDataSet`

constrainAbsoluteValue(max) → None: Limits the data to within bounds of -max to +max, values outside are set to -max or +max respectively.

copy() → magSonify.DataSet.DataSet: Returns a copy of the data set

data: dict: Dictionary of numpy arrays containing the data.

extractKey(key) → magSonify.DataSet_1D.DataSet_1D: Extract element from self.data[key] in new data set

fillFlagged(flags: numpy.array, const=0) → None

Fill values according to an array of flags, across all components

Parameters

flags – Boolean array index of same length as the data set, identifying the indicies to fill.
const – The value to fill with.

fillNaN(const=0) → None: Fills NaN values in the data with the constant const

genMonoAudio(key, file, sampleRate=44100) → None

Generate a mono audio file from data in the series self.data[key]

Parameters: sampleRate (int) – The sample rate of the output audio, default is 44100.

interpolateFactor(factor: float) → None: Interpolates the data set, increasing the sample time resolution by factor times and evenly spacing the samples. If factor < 1, reduces sample resolution.

interpolateReference(ref: magSonify.TimeSeries.TimeSeries) → None: Interpolates the data set such that the new sample times are those of the time series ref.

Note

This can extrapolate outside the data range - there is no range checking. This extrapolation is not reliable and should only be allowed for points very slightly outside the data range.

items() → enumerate: Returns an iterable containing all key-value pairs in data. Equivalent to self.data.items()

keys() → enumerate: Returns an iterable containing all keys in data. Equivalent to self.data.keys()

removeDuplicateTimes() → None: Removes duplicate values in the time series by deleting all but the first occurence. Removes correspoinding points in each component.

runningAverage(samples=None, timeWindow=None) → magSonify.DataSet.DataSet: Returns a running average of the data with window size samples or period timeWindow. Pass only samples OR timeWindow exculsively.

timeSeries: magSonify.TimeSeries.TimeSeries: TimeSeries represeting the sampling times for the dataset

DataSet_3D

class magSonify.DataSet_3D(timeSeries: magSonify.TimeSeries.TimeSeries, data)

Bases: magSonify.DataSet.DataSet

Represents a data set with multiple data series sampled at common time points.

Parameters

timeSeries – Time series representing the sampling times.
data – Dictionary of numpy arrays containing the data. The dictionary must have the keys int 0, 1 and 2 which represent the ‘x’, ‘y’ and ‘z’ axes respectively. Array should be 1D. Other keys may be included, although these will be ignored by vector specific methods, eg. cross(), dot().

coordinateTransform(xBasis, yBasis, zBasis) → magSonify.DataSet.DataSet_3D

Performs a coordinate transform to a system with the specified basis vectors.

Parameters: '_Basis' (DataSet_3D) – A basis vector, specified as a unit vectior which varies over time. Must be expressed in the original coordinate system.

cross(other) → magSonify.DataSet.DataSet_3D: Computes the cross product of 3D datasets

dot(other) → magSonify.DataSet.DataSet_3D: Computes the dot product of 3D datasets

genStereoAudio(file, sampleRate=44100) → None: Generates a stereo audio output in the specified file

makeUnitVector() → None: Normalises the 3D vector to length 1, giving the unit vector

DataSet_1D

class magSonify.DataSet_1D(timeSeries: magSonify.TimeSeries.TimeSeries, x)

Bases: magSonify.DataSet.DataSet

Represents a data set with one component, ie. where the samples are scalars. Supports a series of time stretching methods.

Parameters

timeSeries – Time series representing the sampling times.
x –
The single data series as type numpy.array. The length of the array should be the same as that of timeSeries.

Can also pass a dict with the single key 0, in which case the corresponding value should be populated with a numpy array. This is used allow compatibility with inherited methods from DataSet.

genMonoAudio(file, sampleRate=44100) → None

Generate a mono audio file from data in the series self.data[key]

Parameters: sampleRate (int) – The sample rate of the output audio, default is 44100.

normalise(maxAmplitude=1) → None: Normalises the data set to within a maximum amplitude. Should be used before attempting to output audio.

paulStretch(stretch, window=0.015) → None

Stretches the data according the paulstretch algorithm.

Parameters

stretch – The factor by which to stretch the data.
window – The window size to be used by the paulstrtch algorithm. A window of 0.1 is equivalent to 4410 data points.

Note

Some samples may be clipped at the end of the data set.

phaseVocoderStretch(stretch, frameLength=512, synthesisHop=None) → None

Time stretches the data using a phase vocoder

TimeSeries

class magSonify.TimeSeries(times, timeUnit=numpy.timedelta64(1, 's'), startTime=None)

Represents a series of time points and allows for manipulation.

Parameters

timeData – Array of float, np.datetime64, datetime.datetime or np.timedelta64 represeting the time data
timeUnit – The time unit to use, must be np.timedelta64
startTime – Datetime to construct the series relative to

__eq__(other: magSonify.TimeSeries.TimeSeries) → bool

Supports equality testing:

firstTimeSeries == secondTimeSeries

__getitem__(subscript: slice) → magSonify.TimeSeries.TimeSeries

Supports getting a subset of times using a slice:

myNewTimeSeries = myTimeSeries[100:200]

argFirstAfter(datetime) → int: Returns the argument of the first time point occuring after datetime

asDatetime()

Return type: np.array(dtype = np.datetime64)

asFloat()

Return type: np.array(dtype = np.float)

asNumpy() → numpy.array

Returns the most suitable numpy represenation

Return type: np.array(dtype = np.datetime64) | np.array(dtype = np.timedelta64)

asTimedelta()

Return type: np.array(dtype = np.timedelta64)

changeUnit(newTimeUnit: numpy.timedelta64) → None: Change the units of time that the time series is expressed in to newTimeUnit

copy() → magSonify.TimeSeries.TimeSeries: Returns a copy of the time series

getEnd() → numpy.datetime64

getMeanInterval() → numpy.timedelta64

getMeanIntervalFloat() → float

getStart() → numpy.datetime64

interpolate(factor) → None: Interpolates the time series, increasing the density of points by factor times and evenly spacing the points. If factor < 1, reduces density of points.

startTime: The starting time of the series stored as np.datetime64

timeUnit: The time unit used stored as np.timedelta64

times: A numpy array of times stored as np.float

generateTimeSeries

magSonify.generateTimeSeries(start: numpy.datetime64, end: numpy.datetime64, timeUnit: numpy.timedelta64 = numpy.timedelta64(1, 's'), number: Optional[int] = None, spacing: Optional[numpy.timedelta64] = None)

Generates a time series. Specify only num OR spacing exclusively.

Parameters

start (datetime64) – Datetime of start time
end (datetime64) – Datetime of end time
timeUnit (timedelta64) – Unit of time to use. Default is 1 second.
number (int) – Number of points in time series.
spacing (timedelta64) – Spacing of points in time series.

Simulate Data

class magSonify.SimulateData

applyGaussianWhiteNoise(dataSet: magSonify.DataSet.DataSet, noiseMagnitude=1) → None: Apply gaussian white noise to the input data set

genHarmonic(timeSeries: magSonify.TimeSeries.TimeSeries, frequencies, amplitude=1, phase=0): Generates a set of overlapped sine waves

genHarmonicExpectation(timeSeries: magSonify.TimeSeries.TimeSeries, stretch, frequencies, amplitude=1, phase=0)

genSine(timeSeries: magSonify.TimeSeries.TimeSeries, frequency, amplitude=1, phase=0): Generates a sine wave signal

genSineExpectation(timeSeries: magSonify.TimeSeries.TimeSeries, stretch, frequency, amplitude=1, phase=0): Generates the expected output after sine wave signal is time stretched by a factor of stretch

genSweep(timeSeries: magSonify.TimeSeries.TimeSeries, f0, f1, amplitude=1, method='linear')

genSweepExpectation(timeSeries: magSonify.TimeSeries.TimeSeries, stretch, f0, f1, amplitdue=1, method='linear')

waveOrientOffset(waveform, direction=(1, 0, 0), offset=(0, 0, 0))

Rotate and offset a given waveform in 3D space, returning a list with the series for the 3 components

Parameters

direction – The axis the field amplitude oscillates in as a vector. This will be normalised to a unit vector.
offset – The offset of the origin of the wave.

Utilities

magSonify.Utilities.ensureFolder(directory): Checks that a directory is present, creating if it is not. Cannot handle cases where the parent directory doesn’t exist either.