`qats.TimeSeries`#

class TimeSeries(name, t, x, parent=None, dtg_ref=None, kind=None, unit=None)#

A class for storage, processing and presentation of time series.

Parameters:

name (str) – time series name/identifier
t (array_like) – time array; floats (seconds) or datetime objects
x (array_like) – data points corresponding to time
parent (str, optional) – Path to file it originates from, absolute or relative. Should not be specified for new (calculated) time series.
dtg_ref (datetime.datetime, optional) – Date-time referring to t=0 (time equal zero). Enables output of entire time array as list of datetime.datetime objects.
kind (str, optional) – Kind/type of signal e.g. ‘force’ or ‘acceleration’
unit (str, optional) – Unit of measure e.g. ‘N’ (Newton), ‘kN’ (kilo Newton), ‘m/s2’

Attributes:

name (str) – Time series name/identifier
x (array_like) – Data points corresponding to time, see property t.
parent (str) – Absolute or relative path to file it originates from.
kind (str) – Kind of signal e.g. ‘force’ or ‘acceleration’.
unit (str) – Unit of measure e.g. ‘N’ (Newton) or ‘m/s2’.

Notes

If time is given as array of datetime objects and dtg_ref is not specified, dtg_ref will be set to time array start value.

Properties

`average_frequency`	Average frequency of mean level crossings
`average_period`	Average period between mean level crossings
`data`	Return dictionary of attributes and properties
`dt`	Average time step
`dtg_end`	End time as datetime object.
`dtg_ref`	Date-time referring to `t=0` (time equal zero).
`dtg_start`	Start time as datetime object.
`dtg_time`	Time array formatted as datetime.datetime objects.
`duration`	Duration of time series.
`end`	End time.
`fullname`	Full name.
`is_constant_dt`	Boolean telling whether the time series is sampled at constant intervals or not.
`n`	Number of time steps
`start`	Start time.
`t`	Time array

Methods

`copy`([newname])	Return copy of this TimeSeries object
`filter`(filtertype, freq[, twin, taperfrac])	Apply FFT filter
`fit_weibull`([twin, method])	Fit Weibull distribution to sample of global maxima.
`get`([twin, resample, window_len, ...])	Return time series processed according to parameters
`interpolate`(time)	Interpolate linearly in data to values a specified time
`kurtosis`([fisher, bias])	Kurtosis of time series
`max`(**kwargs)	Maximum value of time series.
`maxima`([twin, local, threshold, rettime])	Return sorted maxima
`mean`(**kwargs)	Mean value of time series.
`min`(**kwargs)	Minimum value of time series.
`minima`([twin, local, threshold, rettime])	Return sorted minima
`modify`(**kwargs)	Modify TimeSeries object
`plot`([figurename, show, num])	Plot time series trace.
`plot_cycle_range`([n, w, bw, figurename, ...])	Plot cycle range versus number of occurrences.
`plot_cycle_rangemean`([n, w, figurename, ...])	Plot cycle range-mean versus number of occurrences.
`plot_cycle_rangemean3d`([nr, nm, figurename, ...])	Plot cycle range-mean versus number of occurrences as 3D surface.
`plot_psd`([figurename, show, num])	Plot time series power spectral density.
`psd`([nperseg, noverlap, detrend, nfft, ...])	Estimate power spectral density using Welch’s method.
`resample`([dt, t])	Resample with constant sampling interval dt
`rfc`(**kwargs)	Returns a sorted list containing with cycle range, mean and count.
`set_dtg_ref`([new_ref])	Set or adjust the dtg reference.
`skew`([bias])	Skewness of time series
`stats`([statsdur, quantiles, is_minima, ...])	Returns dictionary with time series properties and statistics
`std`(**kwargs)	Unbiased standard deviation of time series.

API

property average_frequency#

Average frequency of mean level crossings

Returns:: average frequency of mean level crossings
Return type:: float

property average_period#

Average period between mean level crossings

Returns:: average period between mean level crossings
Return type:: float

property data#

Return dictionary of attributes and properties

Returns:: Attributes and properties
Return type:: dict

property dt#

Average time step

Returns:: average time step
Return type:: float

Notes

The TimeSeries class does not require equidistant time vector.

property dtg_ref#: Date-time referring to t=0 (time equal zero).

property dtg_time#

Time array formatted as datetime.datetime objects.

Returns:: Time array formatted as array of datetime.datetime objects, provided that dtg_ref is defined. Otherwise, returns None.
Return type:: array

property fullname#

Full name.

Returns:: parent and name joined to single string
Return type:: str

property n#

Number of time steps

Returns:: number of time steps
Return type:: int

property is_constant_dt#

Boolean telling whether the time series is sampled at constant intervals or not.

Returns:: Constant sampling interval or not
Return type:: bool

property start#

Start time.

Returns:: start time
Return type:: float

property t#: Time array

property end#

End time.

Returns:: end time
Return type:: float

property dtg_start#

Start time as datetime object.

Returns:: Start time as datetime.datetime instanc, provided that dtg_ref is defined. Otherwise, returns None.
Return type:: datetime

property dtg_end#

End time as datetime object.

Returns:: End time as datetime.datetime instance, provided that dtg_ref is defined. Otherwise, returns None.
Return type:: datetime

property duration#

Duration of time series.

Returns:: time series duration
Return type:: float

copy(newname=None)#

Return copy of this TimeSeries object

Parameters:: newname (str, optional) – Name to assign to copy.
Returns:: Copy of this TimeSeries object
Return type:: TimeSeries

Notes

Does not support parameters for the get() method. It is recommended to modify the copied object instead of the original.

filter(filtertype, freq, twin=None, taperfrac=None)#

Apply FFT filter

Parameters:

filtertype (str) –
Type of filter to apply. Available options:
- ’lp’ - low-pass filter time series
- ’hp’ - high-pass filter time series
- ’bp’ - band-pass filter time series
- ’bs’ - band-stop filter time series
- ’tp’ - threshold filter time series
freq (float or tuple) – Filter frequency [Hz]. One frequency for ‘lp’, ‘hp’ and ‘tp’ filters, two frequencies for ‘bp’ and ‘bs’.
twin (tuple, optional) – Time window (start, stop) to consider (removes away signal outside time window).
taperfrac (float, optional) – Fraction of time domain signal to be tapered. For details, see get().

Returns:

Tuple with to arrays: time array and filtered signal.

Return type:

tuple

See also

get

Notes

filter() is a special case of the get() method. For instance; assuming ts is a TimeSeries instance, the code:

>>> t, xlo = ts.filter('lp', 0.03, twin=(1000, 11800))

… is equivalent to:

>>> t, xlo = ts.get(twin=(1000, 11800), filterargs=('lp', 0.03))

Examples

Low-pass filter the time series at period of 30 [s] (assuming ts is a TimeSeries instance):

>>> t, xlo = ts.filter('lp', 1/30)

High-pass filter at period of 30 [s]:

>>> t, xhi = ts.filter('hp', 1/30)

Band-pass filter, preserving signal between 0.01 and 0.1 [Hz]:

>>> t, xband = ts.filter('bp', (0.01, 0.1))

If the signal includes a significant transient, this may be omitted by specifying time window to consider:

>>> t, xlo = ts.filter('lp', 0.03, twin=(1000, 1e12))

fit_weibull(twin=None, method='msm')#

Fit Weibull distribution to sample of global maxima.

Parameters:

twin (tuple, optional) – Time window to consider.
method ({'msm', 'lse', 'mle', 'pwm', 'pwm2'}, optional) – See qats.weibull.Weibull.fit for description of options.

Returns:

Class instance.

Return type:

Weibull

Examples

>>> weib = ts.fit_weibull(twin=(200., 1e12), method='msm')
>>> print(weib.params)
(372.90398322024936, 5.2533589509069714, 0.8516538181105509)

The fit in example above is equivalent to:

>>> from qats.stats.weibull import Weibull
>>> maxima = ts.maxima(local=False, threshold=None, twin=(200., 1e12), rettime=False)
>>> weib = Weibull.fit(maxima, method='msm')

get(twin=None, resample=None, window_len=None, filterargs=None, window='rectangular', taperfrac=None)#

Return time series processed according to parameters

Parameters:

twin (tuple, optional) – time window, cuts away time series beyond time window
filterargs (tuple, optional) –
Apply filtering. Argument options:
- (‘lp’, f) - Low-pass filter at frequency f
- (‘hp’, f) - High-pass filter at frequency f
- (‘bp’, flo, fhi) - Band-pass filter between frequencies flo and fhi
- (‘bs’, flo, fhi) - Band-stop filter between frequencies flo and fhi
- (‘tp’, a) - Threshold-pass filter at amplitude a
resample (float or ndarray or list, optional) –
Resample time series:
- to specified constant time step if resample is a float
- to specified time if resample is an array or list
window_len (int, optional) – Smooth time serie based on convoluting the time series with a window of specified length. An odd number is recommended.
window (str, optional) – Type of window function used for smoothing, default ‘rectangular’, see qats.signal.smooth for options.
taperfrac (float, optional) – Fraction of time domain signal to be tapered. A taper of 0.001-0.01 is recommended before calculation of the power spectral density.

Returns:

Tuple of two numpy arrays; (time, data)

Return type:

tuple

Notes

The data is modified in the following order

Windowing
Resampling
Tapering
Filtering
Smoothing

Mean value of signal is subtracted before step 3, and then re-added after step 4 (except if high-pass filter is specified).

Resampling is achieved by specifying either dt or t. If both are specified t overrules. Resampling to a a specified time array t cannot be specified at the same time as a time window twin.

Filtering is achieved by FFT truncation.

When smoothing the central data point is calculated at the weighted average of the windowed data points. In the case of the rectangular window all windowed data points are equally weighted. Other window functions are available on request. Note that windowing have some similarities to filtering.

Windowing is achieved by direct truncation of time series within specified time range.

Data tapering is performed by multiplying the time series with a Tukey window (tapered cosine window).

interpolate(time)#

Interpolate linearly in data to values a specified time

Parameters:: time (array_like) – time at which data is interpolated
Returns:: interpolated data values
Return type:: array_like
Raises:: ValueError – If interpolation is attempted on values outside the range of t.

Notes

Extrapolation outside the range of t is not allowed since that does not make sense when analysing generally irregular timeseries.

kurtosis(fisher=False, bias=False, **kwargs)#

Kurtosis of time series

Parameters:

fisher (bool, optional) – If True, Fisher’s definition is used (normal ==> 0.0). If False (default), Pearson’s definition is used (normal ==> 3.0).
bias (bool, optional) – If False (default), then the calculations are corrected for statistical bias.
**kwargs (optional) – Additional keyword arguments are passed to get().

Returns:

Sample kurtosis

Return type:

float

See also

scipy.stats.kurtosis

max(**kwargs)#

Maximum value of time series.

Parameters:: **kwargs (optional) – Additional keyword arguments are passed to get().
Returns:: Maximum value of time series
Return type:: float

Examples

Get maximum of entire time series:

>>> xmax = ts.max()

Get maximum within a specified time window:

>>> xmax = ts.max(twin=(1200, 12000))

maxima(twin=None, local=False, threshold=None, rettime=False, **kwargs)#

Return sorted maxima

Parameters:

twin (tuple, optional) – Time window (start, end) to consider.
local (bool, optional) – return local maxima also, default only global maxima are considered
threshold (float, optional) – consider only maxima larger than specified treshold. Default mean value.
rettime (bool, optional) – If True, (maxima, time_maxima), where time_maxima is an array of time instants associated with the maxima sample.
**kwargs (optional) – Additional keyword arguments are passed to get().

Returns:

array – Signal maxima, sorted from smallest to largest.
array – Only returned if rettime is True. Time instants of signal maxima.

See also

qats.signal.find_maxima

Notes

By default only ‘global’ maxima are considered, i.e. the largest maximum between each mean-level up-crossing. If local=True, local maxima are also included (first derivative is zero, second derivative is negative).

mean(**kwargs)#

Mean value of time series.

Parameters:: **kwargs (optional) – Keyword arguments are passed to get().
Returns:: Sample mean
Return type:: float

See also

numpy.mean

min(**kwargs)#

Minimum value of time series.

Parameters:: **kwargs (optional) – Keyword arguments are passed to get().
Returns:: Minimum value of time series
Return type:: float

minima(twin=None, local=False, threshold=None, rettime=False, **kwargs)#

Return sorted minima

Parameters:

twin (tuple, optional) – Time window (start, end) to consider.
local (bool, optional) – return local minima also, default only global minima are considered
threshold (float, optional) – consider only minima smaller (considering the sign) than specified threshold. Default mean value.
rettime (bool, optional) – If True, (maxima, time_maxima), where time_maxima is an array of time instants associated with the maxima sample.
**kwargs (optional) – Additional keyword arguments are passed to get().

Returns:

array – Signal minima, sorted from smallest to largest.
array – Only returned if rettime is True. Time instants of signal minima.

Notes

Minima are found by multiplying the time series with -1, finding the maxima using the maxima() method and then multiplying the maxima with -1 again.

By default only ‘global’ minima are considered, that is the smallest minimum between each mean-level up-crossing. If local=True local minima are also considered.

See also

maxima

modify(**kwargs)#

Modify TimeSeries object

Parameters:: **kwargs (optional) – Keyword arguments are passed to get().

Notes

Modifies ´t´ and ´x´ on current TimeSeries object. This is irreversible.

plot(figurename=None, show=None, num=1, **kwargs)#

Plot time series trace.

Parameters:

figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
**kwargs (optional) – Additional keyword arguments are passed to get().

plot_psd(figurename=None, show=None, num=1, **kwargs)#

Plot time series power spectral density.

Parameters:

figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
**kwargs (optional) – Additional keyword arguments are passed to psd().

plot_cycle_range(n=200, w=None, bw=1.0, figurename=None, show=None, num=1, **kwargs)#

Plot cycle range versus number of occurrences.

Parameters:

n (int, optional) – Group by cycle range in n equidistant bins.
w (float, optional) – Group by cycle range in w wide equidistant bins. Overrides n.
bw (float, optional) – Bar width, expressed as ratio of bin width.
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
**kwargs (optional) – Additional keyword arguments are passed to rfc().

plot_cycle_rangemean(n=None, w=None, figurename=None, show=None, num=1, **kwargs)#

Plot cycle range-mean versus number of occurrences.

Parameters:

n (int, optional) – Group by cycle range in n equidistant bins.
w (float, optional) – Group by cycle range in w wide equidistant bins. Overrides n.
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
**kwargs (optional) – Additional keyword arguments are passed to rfc().

Notes

Cycle means are represented by weighted averages in each bin.

plot_cycle_rangemean3d(nr=100, nm=100, figurename=None, show=None, num=1, **kwargs)#

Plot cycle range-mean versus number of occurrences as 3D surface.

Parameters:

nr (int, optional) – Group by cycle range in nr equidistant bins.
nm (int, optional) – Group by cycle mean in nm equidistant bins.
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
**kwargs (optional) – Additional keyword arguments are passed to rfc().

psd(nperseg=None, noverlap=None, detrend='constant', nfft=None, normalize=False, **kwargs)#

Estimate power spectral density using Welch’s method.

Parameters:

nperseg (int, optional) – Length of each segment. Default 1/4 of the signal length.
noverlap (int, optional) – Number of points to overlap between segments. Default noverlap = nperseg / 2.
nfft (int, optional) – Length of the FFT used, if a zero padded FFT is desired. Default the FFT length is nperseg.
detrend (str or function, optional) – Specifies how to detrend each segment. If detrend is a string, it is passed as the type argument to detrend. If it is a function, it takes a segment and returns a detrended segment. Defaults to ‘constant’.
normalize (bool, optional) – Normalize power spectral density on maxium density.
kwargs (optional) – Additional keyword arguments are passed to get().

Returns:

Two arrays: sample frequencies and corresponding power spectral density

Return type:

tuple

Notes

Welch’s method [1] computes an estimate of the power spectral density by dividing the data into overlapping segments, computing a modified periodogram for each segment and averaging the periodograms. Welch method is chosen over the periodogram as the spectral density is smoothed by adjusting the nperseg parameter. The periodogram returns a raw spectrum which requires additional smoothing to get a readable spectral density plot.

An appropriate amount of overlap will depend on the choice of window and on your requirements. For the default ‘hanning’ window an overlap of 50% is a reasonable trade off between accurately estimating the signal power, while not over counting any of the data. Narrower windows may require a larger overlap.

If noverlap is 0, this method is equivalent to Bartlett’s method [2].

References

P. Welch, “The use of the fast Fourier transform for the estimation of power spectra: A method based on time averaging over short, modified periodograms”, IEEE Trans. Audio Electroacoust. vol. 15, pp. 70-73, 1967.
M.S. Bartlett, “Periodogram Analysis and Continuous Spectra”, Biometrika, vol. 37, pp. 1-16, 1950.

resample(dt=None, t=None)#

Resample with constant sampling interval dt

Parameters:

dt (float, optional) – Constant sampling interval
t (array_like, optional) – Time array to which the data is resampled

Returns:

Resampled data

Return type:

array_like

Notes

Either dt or t have to specified. If both are specified t overrules.

If dt is used the resampled data cover the period given by the objects t attribute, in other words from start to end.

rfc(**kwargs)#

Returns a sorted list containing with cycle range, mean and count.

Parameters:: **kwargs (optional) – Additional keyword arguments are passed to get().
Returns:: Cycle range, mean and count sorted ascending by cycle range.
Return type:: np.array

Examples

Unpack cycle ranges, means and counts as 1D arrays:

>>> cycles = ts.rfc()
>>> ranges, means, counts = cycles.T

Notes

Half cycles are counted as 0.5, so the returned counts may not be whole numbers.

See also

qats.fatigue.rainflow.count_cycles

set_dtg_ref(new_ref=None)#

Set or adjust the dtg reference.

If there is no pre-defined dtg reference for the time series, dtg reference (dtg_ref) is set to the specified value.

If the time series already has a dtg reference, time array is updated so that t=0 now refers to the new dtg reference. This implies that time array is shifted as follows:

t += (dtg_ref - new_ref).total_seconds()

If no new value is specified, dtg_ref is adjusted so that time array starts at zero (if it doesn’t already).

Parameters:: new_ref (datetime) – New dtg reference.
Raises:: ValueError – If new_ref is not a datetime.datetime instance, or if dtg_ref is not pre-defined and new_dtg is not given.

stats(statsdur=10800.0, quantiles=(0.37, 0.57, 0.9), is_minima=False, include_sample=False, **kwargs)#

Returns dictionary with time series properties and statistics

Parameters:

statsdur (float) – Duration in seconds for estimation of extreme value distribution (Gumbel) from peak distribution (Weibull). Default is 10800 seconds (3 hours).
quantiles (tuple, optional) – Quantiles in the Gumbel distribution used for extreme value estimation, defaults to (0.37, 0.57, 0.90).
is_minima (bool, optional) – Fit to sample of minima instead of maxima. The sample is multiplied by -1 prior to parameter estimation.
include_sample (bool, optional) – Return sample of maxima or minima (minima=True).
**kwargs – Additional keyword arguments are passed to get().

Returns:

Time series statistics (for details, see Notes below).

Return type:

OrderedDict

Notes

The returned dictionary contains:

Key         Description
--------    -----------
start       First value of time array [s]
end         Last value of time array [s]
duration    end - start [s]
dtavg       Average time step [s]
mean        Mean value of signal array
std         Unbiased standard deviation of signal array
skew        Unbiased skewness of signal array (=0 for normal distribution)
kurt        Unbiased kurtosis of signal array (=3 for normal distribution)
min         Minimum value of signal array
max         Maximum value of signal array
tz          Average mean crossing period [s]
wloc        Weibull distribution location parameter fitted to sample of global maxima
wscale      Weibull distribution scale parameter fitted to sample of global maxima
wshape      Weibull distribution shape parameter fitted to sample of global maxima
gloc        Gumbel distribution location parameter estimated from Weibull distribution and `statsdur`
gscale      Gumbel distribution scale parameter estimated from Weibull distribution and `statsdur`
p_* ..      Extreme values estimated from the Gumbel distribution, e.g. p_90 is the 0.9 quantile

Examples

Generate statistics for entire time series, unfiltered:

>>> stats = ts.stats()

To get statistics for filtered time series, one may specify the filter to apply:

>>> stats_lf = ts.stats(filterargs=('lp', 0.3))
>>> stats_hf = ts.stats(filterargs=('hp', 0.3))

To ignore the transient part of the time series, time window may be specified:

>>> stats = ts.stats(twin=(500., 1e12))

std(**kwargs)#

Unbiased standard deviation of time series.

Parameters:: **kwargs (optional) – Additional keyword arguments are passed to get().
Returns:: Sample standard deviation
Return type:: float

Notes

Computes the unbiased sample standard deviation, i.e. it uses a correction factor n / (n - ddof).

See also

scipy.stats.tstd

skew(bias=False, **kwargs)#

Skewness of time series

Parameters:

bias (bool, optional) – If False (default), then the calculations are corrected for statistical bias.
**kwargs (optional) – Additional keyword arguments are passed to get().

Returns:

Sample skewness

Return type:

float

See also

scipy.stats.skew

`qats.TsDB`#

class TsDB(name=None)#

A class for storage, processing and presentation of time series.

Parameters:

name (str, optional) – Database name.

Attributes:

name (str) – Database name.
register (OrderedDict) – TimeSeries objects by unique time series id.
register_parent (OrderedDict) – Parent file path by unique time series id.
register_indices (OrderedDict) – Index of time series on parent file by unique time series id.
register_keys (list) – Unique time series id.

Properties

`common`	Common part of all keys (paths) in DB.
`n`	Number of time series in database

Methods

`add`(ts)	Add new TimeSeries object to db
`clear`([names, display])	Clear/remove time series from register
`copy`([names, shallow])	Make a copy (new TsDB instance) with the specified keys/names included.
`create_common_time`([names, twin, maxdt, strict])	Creates common time array from: latest start time, earliest end time and minimum mean time step.
`export`(filename[, names, delim, ...])	Export time series to file
`fromfile`(filenames[, read, verbose])	Create TsDB instance from one ore more files.
`get`([name, ind, store])	Get (single) TimeSeries object.
`geta`([name, ind, store])	Get (single) time series as numpy arrays (tuple of time and data arrays).
`getd`([names, ind, store, fullkey])	Get dict of TimeSeries objects.
`getda`([names, ind, store, fullkey])	Get dictionary of (numpy) arrays.
`getl`([names, ind, store])	Get list of TimeSeries objects.
`getm`([names, ind, store, fullkey])	Get (dictionary of) multiple TimeSeries objects.
`is_common_time`([names, twin])	Check if time array is common.
`list`([names, display, relative])	List time series in database by id/key
`load`(filenames[, read, verbose])	Load time series from files
`plot`([names, figurename, show, num, store])	Plot time series traces.
`plot_cycle_range`([names, n, w, bw, ...])	Plot cycle range versus number of occurrences.
`plot_cycle_rangemean`([names, n, w, ...])	Plot cycle range-mean versus number of occurrences.
`plot_psd`([names, figurename, show, num, store])	Plot time series power spectral density.
`rename`(name, newname)	Rename a timeseries (and update register accordingly).
`stats`([statsdur, names, ind, store, fullkey])	Get statistics for time series processed according to parameters
`stats_dataframe`([statsdur, names, ind, ...])	Get Pandas Dataframe with time series statistics.
`update`(tsdb[, names, shallow])	Update TsDB with speicified keys/names from other TsDB instance.

API

classmethod fromfile(filenames, read=False, verbose=False)#

Create TsDB instance from one ore more files.

Parameters:

filenames (str, list or tuple) – File names including suffix. Wildcards can also be used.
read (bool, optional) – If True, all time series are read from file and stored. The default is that they are read from file when requested by any of the get*() methods.
verbose (bool, optional) – If True, print information to screen.

Returns:

TsDB instance with files loaded.

Return type:

TsDB

Notes

The purpose of the classmethod is efficient initiation of a new class instance. For example:

>>> from qats import TsDB
>>> tsdb = TsDB.fromfile("mooring.ts")

… is equivalent to:

>>> tsdb = TsDB("")
>>> tsdb.load("mooring.ts")

See also

load: Includes notes of relevance for this method.

property common#

Common part of all keys (paths) in DB.

Return type:: str

property n#

Number of time series in database

Returns:: int
Return type:: number of loaded time series

add(ts)#

Add new TimeSeries object to db

Parameters:: ts (TimeSeries) – added TimeSeries object

Notes

Key/identifier will be the name of the time series. If you want to change the key, just change the name before adding the TimeSeries to the db.

clear(names=None, display=True)#

Clear/remove time series from register

Parameters:

names (str or list or tuple, optional) – Name of time series to remove from database register, supports wildcard.
display (bool, optional) – disable print to screen. Default True

copy(names=None, shallow=False)#

Make a copy (new TsDB instance) with the specified keys/names included.

Parameters:

names (str or list or tuple, optional) – Time series names filter that supports regular expressions.
shallow (bool, optional) – If False (default), the copied TimeSeries objects do not point back to the TimeSeries instances in the source TsDB.

Returns:

New TsDB instance.

Return type:

tsdb

Notes

If shallow is True, the TimeSeries objects in the new TsDB instance point back to the original objects. This implies that modifications to the copied TimeSeries are routed back to the source objects. The advantage of using shallow=True is that memory usage is limited. However, if in doubt use shallow=False (the default).

Specified timeseries that are not preloaded (stored), will be loaded during this procedure.

create_common_time(names=None, twin=None, maxdt=None, strict=False)#

Creates common time array from: latest start time, earliest end time and minimum mean time step.

Parameters:

names (str or list or tuple, optional) – Time series names
twin (tuple, optional) – If specified, the common time array within specified window (start, end) is created.
maxdt (float, optional) – Max. time step desired. If minimum mean time step is larger than ‘maxdt’, the latter is used.
strict (bool, optional) – If True, ValueError is raised if obtained time step deviates from specified/recommended time step.

Returns:

New time array.

Return type:

array

Notes

Be careful when specifying the maximum time step.

export(filename, names=None, delim='\t', skip_header=False, exist_ok=True, basename=True, verbose=False, **kwargs)#

Export time series to file

Parameters:

filename (str) – File name including suffix.
names (str or list or tuple, optional) – Time series names
delim (str, optional) – column delimiter for column wise ascii file, default “ “
skip_header (bool, optional) – For ascii files, skip header with keys? Default is to include them on first line. This parameter is ignored for other file formats.
exist_ok (bool, optional) – if false (the default), a FileExistsError is raised if target file already exists
basename (bool, optional) – If true (the default), basename (no path/file info) will be exported to key file. If false, the name/path relative to common path is used. Also see notes below.
verbose (bool, optional) – Print information
kwargs (optional) – see documentation of get() method for available options

Notes

Currently implemented file formats

direct access format (.ts)
column-wise ascii file with single header line defining the keys(.dat) (comment character is #)

The time series are resampled to a common time vector with a constant time step (sample rate). The minimum average time step of all the selected time series is applied. This is done before enforcing the specified time window.

If basename is true, an exception is raised if two or more time series share the same basename. The solution is then to specify basename=False, so that only the common part of the paths/identifiers of the specified time series is removed before writing the identifiers to key file (applies to .ts format) or ascii file header. Note that in this case the keys are modified so that path separators (‘/’ and ‘') are replaced by underscore (‘_’).

get(name=None, ind=None, store=True)#

Get (single) TimeSeries object.

Parameters:

name (str, optional) – Time series name
ind (int, optional) – Time series index in database register.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.

Returns:

Time series

Return type:

TimeSeries

Notes

Either name or ind must be specified.

Error is raised if zero or more than one match is obtained.

Note that this method is somewhat similar to geta() but returns a TimeSeries object instead of arrays. Therefore this method does not support keyword arguments to be passed further to TimeSeries.get().

geta(name=None, ind=None, store=True, **kwargs)#

Get (single) time series as numpy arrays (tuple of time and data arrays). Optionally, the returned data array may be processed according to specified optional arguments (see kwargs).

Parameters:

name (str, optional) – Time series name
ind (int, optional) – Time series index in database register.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
kwargs (optional) – See documentation of get() method for available options

Returns:

Time and data arrays

Return type:

tuple

Notes

Either name or ind must be specified.

Error is raised if zero or more than one match is obtained.

getd(names=None, ind=None, store=True, fullkey=False)#

Get dict of TimeSeries objects.

Note that this method is identical to getm().

Parameters:

names (str or list or tuple, optional) – Time series name(s), supports wildcard.
ind (int or list, optional) – Index (or indices) of desired time series (index refers to index of key in list attribute register_keys). This parameter may not be combined with keys or names.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
fullkey (bool, optional) – Use full key in returned container

Returns:

TimeSeries objects

Return type:

dict

getda(names=None, ind=None, store=True, fullkey=False, **kwargs)#

Get dictionary of (numpy) arrays. Optionally, the returned data arrays may be processed according to specified optional arguments (see kwargs).

Parameters:

names (str or list or tuple, optional) – Time series names, supports wildcard.
ind (int or list, optional) – Index (or indices) of desired time series (index refers to index of key in list attribute register_keys). This parameter may not be combined with keys or names.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
fullkey (bool, optional) – Use full key in returned container
kwargs (optional) – see documentation of get() method for available options

Returns:

Each entry is a tuple with 2 arrays: time and data for each time series

Return type:

dict

Notes

When working on a large time series database it is recommended to set store=False to avoid too high memory usage. Then the TimeSeries objects will not be stored in the database, only their addresses.

getl(names=None, ind=None, store=True)#

Get list of TimeSeries objects.

Parameters:

names (str or list or tuple, optional) – Time series names, supports wildcard.
ind (int or list, optional) – Index (or indices) of desired time series (index refers to index of key in list attribute register_keys). This parameter may not be combined with keys or names.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.

Returns:

TimeSeries objects

Return type:

list

Notes

getm(names=None, ind=None, store=True, fullkey=False)#

Get (dictionary of) multiple TimeSeries objects.

Parameters:

names (str or list or tuple, optional) – Time series name(s), supports wildcard.
ind (int or list, optional) – Index (or indices) of desired time series (index refers to index of key in list attribute register_keys). This parameter may not be combined with keys or names.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
fullkey (bool, optional) – Use full key in returned container

Returns:

TimeSeries objects

Return type:

dict

Notes

Note that this method is somewhat similar to getda() but returns TimeSeries objects instead of numpy arrays. Therefore this method does not support keyword arguments to be passed further to TimeSeries.get().

is_common_time(names=None, twin=None)#

Check if time array is common.

Parameters:

names (str or list or tuple, optional) – Time series names
twin (tuple, optional) – Time window (start, end) to consider.

Returns:

True if common time array (within specified time window), otherwise False.

Return type:

bool

list(names=None, display=False, relative=False)#

List time series in database by id/key

Parameters:

names (str or list or tuple, optional) – Time series names filter that supports regular expressions, default all time series will be listed
display (bool, optional) – Disable print to screen, default False
relative (bool, optional) – Truncate time series names to unique part i.e. path relative to common path of all time series.

Returns:

Time series names

Return type:

list

Notes

Full identifier/key is obtained by joining the common path of all time series in db and the unique part of the identifiers.

load(filenames, read=False, verbose=False)#

Load time series from files

Parameters:

filenames (str or list or tuple) – File names including suffix. Wildcards can also be used.
read (bool, optional) – If True, all time series are read from file and stored. The default is that they are read from file when requested by any of the get methods.
verbose (bool, optional) – If True, print information to screen.

Notes

read=True may be time consuming and require high memory usage if applied for large files with many time series. However, if you will work with all the time series on files of moderate size, read=True can provide efficiency as you only access the file(s) once.

If time series names contain path separators (‘/’ or ‘'), these must be enclosed within square brackets (e.g. as the slash in “response[m/s]”).

plot(names=None, figurename=None, show=None, num=1, store=True, **kwargs)#

Plot time series traces.

Parameters:

names (str/list/tuple, optional) – Time series names
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
kwargs (optional) – See documentation of TimeSeries.get() method for available options

Notes

See also

qats.TimeSeries

plot_psd(names=None, figurename=None, show=None, num=1, store=True, **kwargs)#

Plot time series power spectral density.

Parameters:

names (str/list/tuple, optional) – Time series names
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
kwargs (optional) – see documentation of TimeSeries.get() method for available options

Notes

See also

qats.TimeSeries

plot_cycle_range(names=None, n=200, w=None, bw=1.0, figurename=None, show=None, num=1, store=True, **kwargs)#

Plot cycle range versus number of occurrences.

Parameters:

names (str/list/tuple, optional) – Time series names
n (int, optional) – Group by cycle range in n equidistant bins.
w (float, optional) – Group by cycle range in w wide equidistant bins. Overrides n.
bw (float, optional) – Bar width, expressed as ratio of bin width.
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
kwargs (optional) – see documentation of TimeSeries.get() method for available options

Notes

When working on a large time series database it is recommended to set store=False to avoid too high memory usage. Then the TimeSeries objects will not be stored in the database, only their addresses.

See also

TsDB.rfc, TsDB.plot_cycle_rangemean, TimeSeries.rfc, rainflow.count_cycles, rainflow.rebin_cycles

plot_cycle_rangemean(names=None, n=None, w=None, figurename=None, show=True, num=1, store=True, **kwargs)#

Plot cycle range-mean versus number of occurrences.

Parameters:

names (str/list/tuple, optional) – Time series names
n (int, optional) – Group by cycle range in n equidistant bins.
w (float, optional) – Group by cycle range in w wide equidistant bins. Overrides n.
figurename (str, optional) – Save figure to file ‘figurename’ instead of displaying on screen.
show (bool, optional) – Show figure? Defaults to False if figurename is specified, otherwise True.
num (int, optional) – Matplotlib figure number. Defaults to 1.
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
kwargs (optional) – see documentation of TimeSeries.get() method for available options

Notes

When working on a large time series database it is recommended to set store=False to avoid too high memory Cycle means are represented by weighted averages in each bin.

When working on a large time series database it is recommended to set store=False to avoid too high memory usage. Then the TimeSeries objects will not be stored in the database, only their addresses.

See also

qats.TimeSeries

rename(name, newname)#

Rename a timeseries (and update register accordingly).

Parameters:

name (str) – Unique time series name (pattern)
newname (str) – New time series name (i.e. unique id/key less the path of parent file).

Notes

A single match must be obtained for the specified name.

stats(statsdur=10800.0, names=None, ind=None, store=True, fullkey=False, **kwargs)#

Get statistics for time series processed according to parameters

Parameters:

statsdur (float, optional) – Duration in seconds for estimation of extreme value distribution (Gumbel) from peak distribution (Weibull). Default is 3 hours.
names (str or list or tuple, optional) – Time series names
ind (int or list, optional) – Time series indices in database
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
fullkey (bool, optional) – Use full key in returned container
kwargs (optional) – see documentation of TimeSeries.stats() and TimeSeries.get() methods for available options

Returns:

Each entry is a dictionary with statistics

Return type:

dictionary

Notes

Full unique path/key is obtained by joining the common part of the paths/keys and the unique part of the keys

Examples

To get sample statistics and 3-hour extreme (default) value statistics for time series in database

>>> from qats import TsDB
>>> db = TsDB.fromfile('filename')
>>> stats = db.stats()

To get sample statistics and 1-hour (3600 seconds) extreme value statistics for time series in database which names starts with ‘Mooring’.

>>> stats = db.stats(statsdur=3600., names="Mooring*")

To get sample statistics and 3-hour extreme value statistics for time series in database which names starts with ‘Mooring’ low-pass filtered at 0.025 Hz.

>>> stats = db.stats(names="Mooring*", filterargs=("lp", 0.025))

To ignore the transient part of the time series, time window may be specified:

>>> stats = db.stats(names="Mooring*", twin=(1000., 1e12), filterargs=("lp", 0.025))

stats_dataframe(statsdur=10800.0, names=None, ind=None, store=True, fullkey=False, **kwargs)#

Get Pandas Dataframe with time series statistics.

Parameters:

statsdur (float, optional) – Duration in seconds for estimation of extreme value distribution (Gumbel) from peak distribution (Weibull). Default is 3 hours.
names (str or list or tuple, optional) – Time series names
ind (int or list, optional) – Time series indices in database
store (bool, optional) – Disable time series storage. Default is to store the time series objects first time it is read.
fullkey (bool, optional) – Use full key in returned container
kwargs (optional) – see documentation of TimeSeries.stats() and TimeSeries.get() methods for available options

Returns:

Statistics for each time series organized in columns.

Return type:

Dataframe

See also

qats.TsDB.stats, pandas.Dataframe

Examples

>>> from qats import TsDB
>>> db = TsDB.fromfile('filename')
>>> df = db.stats_dataframe()
>>> # print first part of dataframe
>>> print(df.head())

>>> # transpose dataframe to get statistics for each time series in rows instead of columns
>>> df = df.transpose(copy=True)

update(tsdb, names=None, shallow=False)#

Update TsDB with speicified keys/names from other TsDB instance.

Parameters:

tsdb (TsDB) – TsDB instance to update from.
names (str or list or tuple, optional) – Time series names
shallow (bool, optional) – If False (default), the copied TimeSeries objects do not point back to the TimeSeries instances in the source TsDB.

qats.TimeSeries#

qats.TsDB#

`qats.TimeSeries`#

`qats.TsDB`#