Configuration files¶

Resistics allows users to set various parameters through configuration files. The package itself comes with its default configuration. Users can change certain parameters by specifying them in a separate configuration file. Below is the default configuration:

name = global copy

[Calibration]
extend = True
usetheoretical = False

[Decimation]
numlevels = 7
minsamples = 100

[Frequencies]
frequencies = ,
perlevel = 7

[Window]
minwindows = 5
windowfactor = 2.0
minwindowsize = 512
minoverlapsize = 128
overlapfraction = 0.25
windowsizes = ,
overlapsizes = ,

[Spectra]
specdir = spectra
applywindow = True
windowfunc = hamming

[Statistics]
stats = coherence, transferFunction
remotestats = RR_coherence, RR_transferFunction

[Solver]
intercept = False
boostrap = True
windowfunc = hamming

Configuration files are separated into several sections which describe which part of the process the parameters affect. The parameters are detailed in the Configuration parameters section. The first thing to note is that all configuration files have a name. This is to help traceability. Configuration names are always entered into dataset comments.

A good way to begin creating a custom configuration file is to copy the default parameterisation. This can be done by using the inbuilt copyDefaultConfig() functionality:

# copy the default configuration file
from resistics.config.defaults import copyDefaultConfig
copyDefaultConfig("resisticsDefaultConfig.ini")

When providing a custom configuration file, only the settings which will be changed need to be entered. Below is an example of a user specified configuration file

name = example1

[Decimation]
numlevels = 6
minsamples = 256

[Frequencies]
perlevel = 8

[Window]
minwindows = 5
minwindowsize = 256
minoverlapsize = 64

[Spectra]
specdir = example1
windowfunc = parzen

[Statistics]
stats = coherence, transferFunction
remotestats = RR_coherence, RR_transferFunction

In the above configuration file, several paramters have been changed from the default. Resistics will now try and create 6 decimation levels with 8 evaluation frequencies per level. Once decimated, timeseries will need to have at least 256 samples to be a valid decimation level. The minimum allowable window size is 256 samples, with a minimum overlap of 64 samples. Spectra calculated using this configuration file will be saved under the example1 spectra directory (to understand more about this, see the tutorial multiple spectra and the tutorial configuration files sections). For calculating the frequency data, a parzen window will be used. And finally, the standard statistics to calculate are coherence and transferFunction and the remote statistics are RR_coherence and RR_transferFunction.

A second example is shown below which has slightly different parameters.

name = example2

[Decimation]
numlevels = 8

[Frequencies]
perlevel = 5

[Window]
windowsizes = 1024, 512, 512, 256, 256, 256, 256, 256
overlapsizes = 256, 128, 128, 64, 64, 64, 64, 64

[Spectra]
specdir = example2
windowfunc = parzen

[Statistics]
stats = coherence, transferFunction
remotestats = RR_coherence, RR_transferFunction

For this configuration file, there are 8 decimation levels with 5 evaluation frequencies per level. The window and overlap sizes are defined explicitly with a window size of:

1024 samples for decimation level 0 (non-decimation timeseries data) with 256 sample overlap
512 for decimation level 1 with 128 sample overlap
512 for decimation level 2 with 128 sample overlap
256 for decimation level 3 with 64 sample overlap
256 for decimation level 4 with 64 sample overlap
256 for decimation level 5 with 64 sample overlap
256 for decimation level 6 with 64 sample overlap
256 for decimation level 7 with 64 sample overlap

Note

When specifying window and overlap sizes manually, a window and overlap size must be defined for each decimation level.

When using resistics, information about the configuraiton being used can be printed to the terminal. This will detail which parameters have been specified by the user and which ones are being defaulted.

17:45 ConfigData: Configuration file = Default configuration
17:45 ConfigData: Configuration name = default
17:45 ConfigData: Flags:
17:45 ConfigData: customfrequencies = False
17:45 ConfigData: customwindows = False
17:45 ConfigData: Configuration Parameters:
17:45 ConfigData: Name = default
17:45 ConfigData: Calibration:
17:45 ConfigData:    extend = True
17:45 ConfigData:    usetheoretical = False
17:45 ConfigData:    Defaulted options = extend, usetheoretical
17:45 ConfigData: Decimation:
17:45 ConfigData:    numlevels = 7
17:45 ConfigData:    minsamples = 100
17:45 ConfigData:    Defaulted options = numlevels, minsamples
17:45 ConfigData: Frequencies:
17:45 ConfigData:    frequencies = []
17:45 ConfigData:    perlevel = 7
17:45 ConfigData:    Defaulted options = frequencies, perlevel
17:45 ConfigData: Window:
17:45 ConfigData:    minwindows = 5
17:45 ConfigData:    windowfactor = 2.0
17:45 ConfigData:    minwindowsize = 512
17:45 ConfigData:    minoverlapsize = 128
17:45 ConfigData:    overlapfraction = 0.25
17:45 ConfigData:    windowsizes = []
17:45 ConfigData:    overlapsizes = []
17:45 ConfigData:    Defaulted options = minwindows, windowfactor, minwindowsize, minoverlapsize, overlapfraction, windowsizes, overlapsizes
17:45 ConfigData: Spectra:
17:45 ConfigData:    specdir = spectra
17:45 ConfigData:    applywindow = True
17:45 ConfigData:    windowfunc = hamming
17:45 ConfigData:    Defaulted options = specdir, applywindow, windowfunc
17:45 ConfigData: Statistics:
17:45 ConfigData:    stats = ['coherence', 'transferFunction']
17:45 ConfigData:    remotestats = ['RR_coherence', 'RR_transferFunction']
17:45 ConfigData:    Defaulted options = stats, remotestats
17:45 ConfigData: Solver:
17:45 ConfigData:    intercept = False
17:45 ConfigData:    boostrap = True
17:45 ConfigData:    windowfunc = hamming
17:45 ConfigData:    Defaulted options = intercept, boostrap, windowfunc

Configuration parameters¶

A detailed explanation of parameters available for configuration is given below.

General¶

These parameters are general and not tied to any specific section.

name

Type: string
Default value: “default”
Description: A name for the configuration. This will be saved in comment files.

Calibration¶

Parameters related to calibration data and calibrating of time data.

extend

Type: bool (True or False)
Default value: True
Description: Extrapolate out calibration data to cover a greater range of frequencies.

usetheoretical

Type: bool (True or False)
Default value: False
Description: Use a theoretical calibration for magnetic channels when a matching calibration file is not found.

Decimation¶

Parameters to define the decimation scheme to use. Note that depending on the length of timeseries recording, not all decimation levels may be calculated.

numlevels

Type: int
Default value: 7 (min=1, max=10)
Description: Number of decimation levels.

minsamples

Type: int
Default value: 100 (min=50)
Description: Minimum number of samples required to continue decimation.

Frequencies¶

Evaluation frequency related parameters. If evaluation frequencies are not explicitly supplied, then they are automatically selected internally.

frequencies

Type: List[float] (comma separated list of floats)
Default value: None
Description: Evaluation frequencies specified as a comma separated list of floats.

perlevel

Type: int
Default value: 7 (min=1, max=10)
Description: Number of evaluation frequencies per decimation level.

Window¶

Timeseries windowing parameters. This defines how the timeseries data will be windowed and the overlap between windows. Resistics will automatically calculate window sizes using windowfactor and overlapfraction. If for any decimation level, the calculation results in a window size less than minwindowsize or overlap lower than the minoverlapsize, the window and overlap sizes will be set to their minimum allowable values.

Window and overlap sizes can be set explicitly using the windowsizes and overlap sizes. If windowsizes are explicitly set, overlapsizes needs to be set too.

minwindows

Type: int
Default value: 5 (min=1)
Description: Minimum windows required for a decimation level before decimation is ended.

windowfactor

Type: int
Default value: 2 (min=1)
Description: The factor which defines window size. The window size is calculated as: sampling frequency at decimation level / windowfactor.

minwindowsize

Type: int
Default value: 512 (min=32)
Description: The minimum allowable size of a window in samples.

minoverlapsize

Type: int
Default value: 128 (min=8)
Description: The minimum allowable overlap size.

overlapfraction

Type: float
Default value: 0.25 (min=0, max=0.5)
Description: The fraction of the windowsize to use as overlap size.

windowsizes

Type: List[int] of size equal to number of decimation levels
Default value: None
Description: Explicitly specify the window sizes as a comma separated list.

overlapsizes

Type: List[int] of size equal to number of decimation levels
Default value: None
Description: Explicitly specify the overlap sizes as a comma separated list.

Spectra¶

Parameters related to calculating timeseries fourier spectra.

specdir

Type: string
Default value: “spectra”
Description: The spectra directory to write out to. This allows each configuration file to be related to a different run of the data.

applywindow

Type: bool (True or False)
Default value: True
Description: Window the data before performing the fourier transform.

windowfunction

Type: string. One of “barthann”, “bartlett”, “blackman”, “blackmanharis”, “bohman”, “chebwin”, “hamming”, “hann”, “nuttall”, “parzen”.
Default value: “hamming”
Description: Window function to apply before doing the fourier transform

Statistics¶

Parameters related to calculating timeseries fourier spectra.

stats

Type: List[str]
Default value: “coherence”, “transferFunction”
Description: Comma separated list of statistics to calculate.

remotestats

Type: List[str]
Default value: “RR_coherence” , “RR_transferFunction”
Description: Comma separated list of remote reference statistics to calculate

Solver¶

Solution parameters

intercept

Type: bool (True or False)
Default value: False
Description: Boolean flag for including an intercept in the least squares problem.

windowfunc

Type: str. One of “barthann”, “bartlett”, “blackman”, “blackmanharis”, “bohman”, “chebwin”, “hamming”, “hann”, “nuttall”, “parzen”.
Default value: “hamming”
Description: Window function used for