def test_1d_ndims(self):
# valid ndims
array_parser(self.time, varname="time", dims=1)
# invalid ndims
with pytest.raises(SPYValueError):
array_parser(self.time, varname="time", dims=2)
def test_ntype(self):
# string
with pytest.raises(SPYTypeError):
array_parser(str(self.time), varname="time", ntype="numeric")
# float32 instead of expected float64
with pytest.raises(SPYValueError):
array_parser(np.float32(self.time),
varname="time",
ntype='float64')
def test_character_list(self):
channels = np.array(["channel1", "channel2", "channel3"])
array_parser(channels, varname="channels", dims=1)
array_parser(channels, varname="channels", dims=(3, ))
array_parser(channels, varname="channels", dims=(None, ))
with pytest.raises(SPYValueError):
array_parser(channels, varname="channels", dims=(4, ))
def unit(self, unit):
if unit is None:
self._unit = None
return
if self.data is None:
raise SPYValueError("Syncopy - SpikeData - unit: Cannot assign `unit` without data. " +
"Please assign data first")
nunit = np.unique(self.data[:, self.dimord.index("unit")]).size
try:
array_parser(unit, varname="unit", ntype="str", dims=(nunit,))
except Exception as exc:
raise exc
self._unit = np.array(unit)
def trialid(self, trlid):
if trlid is None:
self._trialid = None
return
if self.data is None:
print("SyNCoPy core - trialid: Cannot assign `trialid` without data. " +
"Please assing data first")
return
scount = np.nanmax(self.data[:, self.dimord.index("sample")])
try:
array_parser(trlid, varname="trialid", dims=(self.data.shape[0],),
hasnan=False, hasinf=False, ntype="int_like", lims=[-1, scount])
except Exception as exc:
raise exc
self._trialid = np.array(trlid, dtype=int)
def channel(self, channel):
if channel is None:
self._channel = None
return
if self.avg is None:
raise SPYValueError(
"Syncopy: Cannot assign `channels` without data. " +
"Please assign data first")
try:
array_parser(channel,
varname="channel",
ntype="str",
dims=(self.avg.shape[self.dimord.index("channel")], ))
except Exception as exc:
raise exc
self._channel = np.array(channel)
def freq(self, freq):
if freq is None:
self._freq = None
return
if self.data is None:
print("Syncopy core - freq: Cannot assign `freq` without data. "+\
"Please assing data first")
return
try:
array_parser(freq,
varname="freq",
hasnan=False,
hasinf=False,
dims=(self.data.shape[self.dimord.index("freq")], ))
except Exception as exc:
raise exc
self._freq = np.array(freq)
def channel_j(self, channel_j):
""" :class:`numpy.ndarray` : list of channel labels """
if channel_j is None:
self._channel_j = None
return
if self.data is None:
raise SPYValueError(
"Syncopy: Cannot assign `channels` without data. " +
"Please assign data first")
try:
array_parser(
channel_j,
varname="channel_j",
ntype="str",
dims=(self.data.shape[self.dimord.index("channel_j")], ))
except Exception as exc:
raise exc
self._channel_j = np.array(channel_j)
def taper(self, tpr):
if tpr is None:
self._taper = None
return
if self.data is None:
print("Syncopy core - taper: Cannot assign `taper` without data. "+\
"Please assing data first")
try:
array_parser(
tpr,
dims=(self.data.shape[self.dimord.index("taper")], ),
varname="taper",
ntype="str",
)
except Exception as exc:
raise exc
self._taper = np.array(tpr)
def channel(self, chan):
if chan is None:
self._channel = None
return
if self.data is None:
raise SPYValueError("Syncopy: Cannot assign `channels` without data. " +
"Please assign data first")
try:
array_parser(chan, varname="channel", ntype="str")
except Exception as exc:
raise exc
# Remove duplicate entries from channel array but preserve original order
# (e.g., `[2, 0, 0, 1]` -> `[2, 0, 1`); allows for complex subset-selections
_, idx = np.unique(chan, return_index=True)
chan = np.array(chan)[np.sort(idx)]
nchan = np.unique(self.data[:, self.dimord.index("channel")]).size
if chan.size != nchan:
lgl = "channel label array of length {0:d}".format(nchan)
act = "array of length {0:d}".format(chan.size)
raise SPYValueError(legal=lgl, varname="channel", actual=act)
self._channel = chan
def test_1d_shape(self):
# valid shape
array_parser(self.time, varname="time", dims=(100, ))
# valid shape, unkown size
array_parser(self.time, varname="time", dims=(None, ))
# invalid shape
with pytest.raises(SPYValueError):
array_parser(self.time, varname="time", dims=(100, 1))
def validate_foi(foi, foilim, samplerate):
"""
Parameters
----------
foi : 'all' or array like or None
frequencies of interest
foilim : 2-element sequence or None
foi limits
Other Parameters
----------------
samplerate : float
the samplerate in Hz
Returns
-------
foi, foilim : tuple
Either both are `None` or the
user submitted one is parsed and returned
Notes
-----
Setting both `foi` and `foilim` to `None` is valid, the
subsequent analysis methods should all have a default way to
select a standard set of frequencies (e.g. np.fft.fftfreq).
"""
if foi is not None and foilim is not None:
lgl = "either `foi` or `foilim` specification"
act = "both"
raise SPYValueError(legal=lgl, varname="foi/foilim", actual=act)
if foi is not None:
if isinstance(foi, str):
if foi == "all":
foi = None
else:
raise SPYValueError(legal="'all' or `None` or list/array",
varname="foi",
actual=foi)
else:
try:
array_parser(foi,
varname="foi",
hasinf=False,
hasnan=False,
lims=[0, samplerate / 2],
dims=(None, ))
except Exception as exc:
raise exc
foi = np.array(foi, dtype="float")
if foilim is not None:
if isinstance(foilim, str):
if foilim == "all":
foilim = None
else:
raise SPYValueError(legal="'all' or `None` or `[fmin, fmax]`",
varname="foilim",
actual=foilim)
else:
try:
array_parser(foilim,
varname="foilim",
hasinf=False,
hasnan=False,
lims=[0, samplerate / 2],
dims=(2, ))
except Exception as exc:
raise exc
# foilim is of shape (2,)
if foilim[0] > foilim[1]:
msg = "Sorting foilim low to high.."
SPYInfo(msg)
foilim = np.sort(foilim)
return foi, foilim
def definetrial(obj,
trialdefinition=None,
pre=None,
post=None,
start=None,
trigger=None,
stop=None,
clip_edges=False):
"""(Re-)define trials of a Syncopy data object
Data can be structured into trials based on timestamps of a start, trigger
and end events::
start trigger stop
|---- pre ----|--------|---------|--- post----|
Parameters
----------
obj : Syncopy data object (:class:`BaseData`-like)
trialdefinition : :class:`EventData` object or Mx3 array
[start, stop, trigger_offset] sample indices for `M` trials
pre : float
offset time (s) before start event
post : float
offset time (s) after end event
start : int
event code (id) to be used for start of trial
stop : int
event code (id) to be used for end of trial
trigger :
event code (id) to be used center (t=0) of trial
clip_edges : bool
trim trials to actual data-boundaries.
Returns
-------
Syncopy data object (:class:`BaseData`-like))
Notes
-----
:func:`definetrial` supports the following argument combinations:
>>> # define M trials based on [start, end, offset] indices
>>> definetrial(obj, trialdefinition=[M x 3] array)
>>> # define trials based on event codes stored in <:class:`EventData` object>
>>> definetrial(obj, trialdefinition=<EventData object>,
pre=0, post=0, start=startCode, stop=stopCode,
trigger=triggerCode)
>>> # apply same trial definition as defined in <:class:`EventData` object>
>>> definetrial(<AnalogData object>,
trialdefinition=<EventData object w/sampleinfo/t0/trialinfo>)
>>> # define whole recording as single trial
>>> definetrial(obj, trialdefinition=None)
"""
# Start by vetting input object
try:
data_parser(obj, varname="obj")
except Exception as exc:
raise exc
if obj.data is None:
lgl = "non-empty Syncopy data object"
act = "empty Syncopy data object"
raise SPYValueError(legal=lgl, varname="obj", actual=act)
# Check array/object holding trial specifications
if trialdefinition is not None:
if trialdefinition.__class__.__name__ == "EventData":
try:
data_parser(trialdefinition,
varname="trialdefinition",
writable=None,
empty=False)
except Exception as exc:
raise exc
evt = True
else:
try:
array_parser(trialdefinition,
varname="trialdefinition",
dims=2)
except Exception as exc:
raise exc
if any([
"ContinuousData" in str(base)
for base in obj.__class__.__mro__
]):
scount = obj.data.shape[obj.dimord.index("time")]
else:
scount = np.inf
try:
array_parser(trialdefinition[:, :2],
varname="sampleinfo",
dims=(None, 2),
hasnan=False,
hasinf=False,
ntype="int_like",
lims=[0, scount])
except Exception as exc:
raise exc
trl = np.array(trialdefinition, dtype="float")
ref = obj
tgt = obj
evt = False
else:
# Construct object-class-specific `trl` arrays treating data-set as single trial
if any(
["ContinuousData" in str(base) for base in obj.__class__.__mro__]):
trl = np.array([[0, obj.data.shape[obj.dimord.index("time")], 0]])
else:
sidx = obj.dimord.index("sample")
trl = np.array([[
np.nanmin(obj.data[:, sidx]),
np.nanmax(obj.data[:, sidx]), 0
]])
ref = obj
tgt = obj
evt = False
# AnalogData + EventData w/sampleinfo
if obj.__class__.__name__ == "AnalogData" and evt and trialdefinition.sampleinfo is not None:
if obj.samplerate is None or trialdefinition.samplerate is None:
lgl = "non-`None` value - make sure `samplerate` is set before defining trials"
act = "None"
raise SPYValueError(legal=lgl, varname="samplerate", actual=act)
ref = trialdefinition
tgt = obj
trl = np.array(ref.trialinfo)
t0 = np.array(ref._t0).reshape((ref._t0.size, 1))
trl = np.hstack([ref.sampleinfo, t0, trl])
trl = np.round((trl / ref.samplerate) * tgt.samplerate).astype(int)
# AnalogData + EventData w/keywords or just EventData w/keywords
if any([kw is not None for kw in [pre, post, start, trigger, stop]]):
# Make sure we actually have valid data objects to work with
if obj.__class__.__name__ == "EventData" and evt is False:
ref = obj
tgt = obj
elif obj.__class__.__name__ == "AnalogData" and evt is True:
ref = trialdefinition
tgt = obj
else:
lgl = "AnalogData with associated EventData object"
act = "{} and {}".format(obj.__class__.__name__,
trialdefinition.__class__.__name__)
raise SPYValueError(legal=lgl, actual=act, varname="input")
# The only case we might actually need it: ensure `clip_edges` is valid
if not isinstance(clip_edges, bool):
raise SPYTypeError(clip_edges,
varname="clip_edges",
expected="Boolean")
# Ensure that objects have their sampling-rates set, otherwise break
if ref.samplerate is None or tgt.samplerate is None:
lgl = "non-`None` value - make sure `samplerate` is set before defining trials"
act = "None"
raise SPYValueError(legal=lgl, varname="samplerate", actual=act)
# Get input dimensions
szin = []
for var in [pre, post, start, trigger, stop]:
if isinstance(var, (np.ndarray, list)):
szin.append(len(var))
if np.unique(szin).size > 1:
lgl = "all trial-related arrays to have the same length"
act = "arrays with sizes {}".format(
str(np.unique(szin)).replace("[", "").replace("]", ""))
raise SPYValueError(legal=lgl,
varname="trial-keywords",
actual=act)
if len(szin):
ntrials = szin[0]
ninc = 1
else:
ntrials = 1
ninc = 0
# If both `pre` and `start` or `post` and `stop` are `None`, abort
if (pre is None and start is None) or (post is None and stop is None):
lgl = "`pre` or `start` and `post` or `stop` to be not `None`"
act = "both `pre` and `start` and/or `post` and `stop` are simultaneously `None`"
raise SPYValueError(legal=lgl, actual=act)
if (trigger is None) and (pre is not None or post is not None):
lgl = "non-None `trigger` with `pre`/`post` timing information"
act = "`trigger` = `None`"
raise SPYValueError(legal=lgl, actual=act)
# If provided, ensure keywords make sense, otherwise allocate defaults
kwrds = {}
vdict = {
"pre": {
"var": pre,
"hasnan": False,
"ntype": None,
"fillvalue": 0
},
"post": {
"var": post,
"hasnan": False,
"ntype": None,
"fillvalue": 0
},
"start": {
"var": start,
"hasnan": None,
"ntype": "int_like",
"fillvalue": np.nan
},
"trigger": {
"var": trigger,
"hasnan": None,
"ntype": "int_like",
"fillvalue": np.nan
},
"stop": {
"var": stop,
"hasnan": None,
"ntype": "int_like",
"fillvalue": np.nan
}
}
for vname, opts in vdict.items():
if opts["var"] is not None:
if isinstance(opts["var"], numbers.Number):
try:
scalar_parser(opts["var"],
varname=vname,
ntype=opts["ntype"],
lims=[-np.inf, np.inf])
except Exception as exc:
raise exc
opts["var"] = np.full((ntrials, ), opts["var"])
else:
try:
array_parser(opts["var"],
varname=vname,
hasinf=False,
hasnan=opts["hasnan"],
ntype=opts["ntype"],
dims=(ntrials, ))
except Exception as exc:
raise exc
kwrds[vname] = opts["var"]
else:
kwrds[vname] = np.full((ntrials, ), opts["fillvalue"])
# Prepare `trl` and convert event-codes + sample-numbers to lists
trl = []
evtid = list(ref.data[:, ref.dimord.index("eventid")])
evtsp = list(ref.data[:, ref.dimord.index("sample")])
nevents = len(evtid)
searching = True
trialno = 0
cnt = 0
act = ""
# Do this line-by-line: halt on error (if event-id is not found in `ref`)
while searching:
# Allocate begin and end of trial
begin = None
end = None
t0 = 0
idxl = []
# First, try to assign `start`, then `t0`
if not np.isnan(kwrds["start"][trialno]):
try:
sidx = evtid.index(kwrds["start"][trialno])
except:
act = str(kwrds["start"][trialno])
vname = "start"
break
begin = evtsp[sidx] / ref.samplerate
evtid[sidx] = -np.pi
idxl.append(sidx)
if not np.isnan(kwrds["trigger"][trialno]):
try:
idx = evtid.index(kwrds["trigger"][trialno])
except:
act = str(kwrds["trigger"][trialno])
vname = "trigger"
break
t0 = evtsp[idx] / ref.samplerate
evtid[idx] = -np.pi
idxl.append(idx)
# Trial-begin is either `trigger - pre` or `start - pre`
if begin is not None:
begin -= kwrds["pre"][trialno]
else:
begin = t0 - kwrds["pre"][trialno]
# Try to assign `stop`, if we got nothing, use `t0 + post`
if not np.isnan(kwrds["stop"][trialno]):
evtid[:sidx] = [np.pi] * sidx
try:
idx = evtid.index(kwrds["stop"][trialno])
except:
act = str(kwrds["stop"][trialno])
vname = "stop"
break
end = evtsp[idx] / ref.samplerate + kwrds["post"][trialno]
evtid[idx] = -np.pi
idxl.append(idx)
else:
end = t0 + kwrds["post"][trialno]
# Off-set `t0`
t0 -= begin
# Make sure current trial setup makes (some) sense
if begin >= end:
lgl = "non-overlapping trial begin-/end-samples"
act = "trial-begin at {}, trial-end at {}".format(
str(begin), str(end))
raise SPYValueError(legal=lgl, actual=act)
# Finally, write line of `trl`
trl.append([begin, end, t0])
# Update counters and end this mess when we're done
trialno += ninc
cnt += 1
evtsp = evtsp[max(idxl, default=-1) + 1:]
evtid = evtid[max(idxl, default=-1) + 1:]
if trialno == ntrials or cnt == nevents:
searching = False
# Abort if the above loop ran into troubles
if len(trl) < ntrials:
if len(act) > 0:
raise SPYValueError(legal="existing event-id",
varname=vname,
actual=act)
# Make `trl` a NumPy array
trl = np.round(np.array(trl) * tgt.samplerate).astype(int)
# If appropriate, clip `trl` to AnalogData object's bounds (if wanted)
if clip_edges and evt:
msk = trl[:, 0] < 0
trl[msk, 0] = 0
dmax = tgt.data.shape[tgt.dimord.index("time")]
msk = trl[:, 1] > dmax
trl[msk, 1] = dmax
if np.any(trl[:, 0] >= trl[:, 1]):
lgl = "non-overlapping trials"
act = "some trials are overlapping after clipping to AnalogData object range"
raise SPYValueError(legal=lgl, actual=act)
# The triplet `sampleinfo`, `t0` and `trialinfo` works identically for
# all data genres
if trl.shape[1] < 3:
raise SPYValueError(
"array of shape (no. of trials, 3+)",
varname="trialdefinition",
actual="shape = {shp:s}".format(shp=str(trl.shape)))
# Finally: assign `sampleinfo`, `t0` and `trialinfo` (and potentially `trialid`)
tgt._trialdefinition = trl
# In the discrete case, we have some additinal work to do
if any(["DiscreteData" in str(base) for base in tgt.__class__.__mro__]):
# Compute trial-IDs by matching data samples with provided trial-bounds
samples = tgt.data[:, tgt.dimord.index("sample")]
starts = tgt.sampleinfo[:, 0]
ends = tgt.sampleinfo[:, 1]
startids = np.searchsorted(starts, samples, side="right")
endids = np.searchsorted(ends, samples, side="left")
mask = startids == endids
startids -= 1
# Samples not belonging into any trial get a trial-ID of -1
startids[mask] = int(startids.min() <= 0) * (-1)
tgt.trialid = startids
# Write log entry
if ref == tgt:
ref.log = "updated trial-definition with [" \
+ " x ".join([str(numel) for numel in trl.shape]) \
+ "] element array"
else:
ref_log = ref._log.replace("\n\n", "\n\t")
tgt.log = "trial-definition extracted from EventData object: "
tgt._log += ref_log
tgt.cfg = {
"method": sys._getframe().f_code.co_name,
"EventData object": ref.cfg
}
ref.log = "updated trial-defnition of {} object".format(
tgt.__class__.__name__)
return
def freqanalysis(data, method='mtmfft', output='fourier',
keeptrials=True, foi=None, foilim=None,
pad_to_length=None, polyremoval=None,
taper="hann", tapsmofrq=None, nTaper=None, keeptapers=False,
toi="all", t_ftimwin=None, wavelet="Morlet", width=6, order=None,
order_max=None, order_min=1, c_1=3, adaptive=False,
out=None, **kwargs):
"""
Perform (time-)frequency analysis of Syncopy :class:`~syncopy.AnalogData` objects
**Usage Summary**
Options available in all analysis methods:
* **output** : one of :data:`~syncopy.specest.const_def.availableOutputs`;
return power spectra, complex Fourier spectra or absolute values.
* **foi**/**foilim** : frequencies of interest; either array of frequencies or
frequency window (not both)
* **keeptrials** : return individual trials or grand average
* **polyremoval** : de-trending method to use (0 = mean, 1 = linear or `None`)
List of available analysis methods and respective distinct options:
"mtmfft" : (Multi-)tapered Fourier transform
Perform frequency analysis on time-series trial data using either a single
taper window (Hanning) or many tapers based on the discrete prolate
spheroidal sequence (DPSS) that maximize energy concentration in the main
lobe.
* **taper** : one of :data:`~syncopy.shared.const_def.availableTapers`
* **tapsmofrq** : spectral smoothing box for slepian tapers (in Hz)
* **nTaper** : number of orthogonal tapers for slepian tapers
* **keeptapers** : return individual tapers or average
* **pad_to_length**: either pad to an absolute length or set to `'nextpow2'`
"mtmconvol" : (Multi-)tapered sliding window Fourier transform
Perform time-frequency analysis on time-series trial data based on a sliding
window short-time Fourier transform using either a single Hanning taper or
multiple DPSS tapers.
* **taper** : one of :data:`~syncopy.specest.const_def.availableTapers`
* **tapsmofrq** : spectral smoothing box for slepian tapers (in Hz)
* **nTaper** : number of orthogonal tapers for slepian tapers
* **keeptapers** : return individual tapers or average
* **toi** : time-points of interest; can be either an array representing
analysis window centroids (in sec), a scalar between 0 and 1 encoding
the percentage of overlap between adjacent windows or "all" to center
a window on every sample in the data.
* **t_ftimwin** : sliding window length (in sec)
"wavelet" : (Continuous non-orthogonal) wavelet transform
Perform time-frequency analysis on time-series trial data using a non-orthogonal
continuous wavelet transform.
* **wavelet** : one of :data:`~syncopy.specest.const_def.availableWavelets`
* **toi** : time-points of interest; can be either an array representing
time points (in sec) or "all"(pre-trimming and subsampling of results)
* **width** : Nondimensional frequency constant of Morlet wavelet function (>= 6)
* **order** : Order of Paul wavelet function (>= 4) or derivative order
of real-valued DOG wavelets (2 = mexican hat)
"superlet" : Superlet transform
Perform time-frequency analysis on time-series trial data using
the super-resolution superlet transform (SLT) from [Moca2021]_.
* **order_max** : Maximal order of the superlet
* **order_min** : Minimal order of the superlet
* **c_1** : Number of cycles of the base Morlet wavelet
* **adaptive** : If set to `True` perform fractional adaptive SLT,
otherwise perform multiplicative SLT
**Full documentation below**
Parameters
----------
data : `~syncopy.AnalogData`
A non-empty Syncopy :class:`~syncopy.datatype.AnalogData` object
method : str
Spectral estimation method, one of :data:`~syncopy.specest.const_def.availableMethods`
(see below).
output : str
Output of spectral estimation. One of :data:`~syncopy.specest.const_def.availableOutputs` (see below);
use `'pow'` for power spectrum (:obj:`numpy.float32`), `'fourier'` for complex
Fourier coefficients (:obj:`numpy.complex64`) or `'abs'` for absolute
values (:obj:`numpy.float32`).
keeptrials : bool
If `True` spectral estimates of individual trials are returned, otherwise
results are averaged across trials.
foi : array-like or None
Frequencies of interest (Hz) for output. If desired frequencies cannot be
matched exactly, the closest possible frequencies are used. If `foi` is `None`
or ``foi = "all"``, all attainable frequencies (i.e., zero to Nyquist / 2)
are selected.
foilim : array-like (floats [fmin, fmax]) or None or "all"
Frequency-window ``[fmin, fmax]`` (in Hz) of interest. Window
specifications must be sorted (e.g., ``[90, 70]`` is invalid) and not NaN
but may be unbounded (e.g., ``[-np.inf, 60.5]`` is valid). Edges `fmin`
and `fmax` are included in the selection. If `foilim` is `None` or
``foilim = "all"``, all frequencies are selected.
pad_to_length : int, None or 'nextpow2'
Padding of the input data, if set to a number pads all trials
to this absolute length. For instance ``pad_to_length = 2000`` pads all
trials to an absolute length of 2000 samples, if and only if the longest
trial contains at maximum 2000 samples.
Alternatively if all trials have the same initial lengths
setting `pad_to_length='nextpow2'` pads all trials to
the next power of two.
If `None` and trials have unequal lengths all trials are padded to match
the longest trial.
polyremoval : int or None
Order of polynomial used for de-trending data in the time domain prior
to spectral analysis. A value of 0 corresponds to subtracting the mean
("de-meaning"), ``polyremoval = 1`` removes linear trends (subtracting the
least squares fit of a linear polynomial).
If `polyremoval` is `None`, no de-trending is performed. Note that
for spectral estimation de-meaning is very advisable and hence also the
default.
taper : str
Only valid if `method` is `'mtmfft'` or `'mtmconvol'`. Windowing function,
one of :data:`~syncopy.specest.const_def.availableTapers` (see below).
tapsmofrq : float
Only valid if `method` is `'mtmfft'` or `'mtmconvol'` and `taper` is `'dpss'`.
The amount of spectral smoothing through multi-tapering (Hz).
Note that smoothing frequency specifications are one-sided,
i.e., 4 Hz smoothing means plus-minus 4 Hz, i.e., a 8 Hz smoothing box.
nTaper : int or None
Only valid if `method` is `'mtmfft'` or `'mtmconvol'` and `taper='dpss'`.
Number of orthogonal tapers to use. It is not recommended to set the number
of tapers manually! Leave at `None` for the optimal number to be set automatically.
keeptapers : bool
Only valid if `method` is `'mtmfft'` or `'mtmconvol'`.
If `True`, return spectral estimates for each taper.
Otherwise power spectrum is averaged across tapers,
if and only if `output` is `pow`.
toi : float or array-like or "all"
**Mandatory input** for time-frequency analysis methods (`method` is either
`"mtmconvol"` or `"wavelet"` or `"superlet"`).
If `toi` is scalar, it must be a value between 0 and 1 indicating the
percentage of overlap between time-windows specified by `t_ftimwin` (only
valid if `method` is `'mtmconvol'`).
If `toi` is an array it explicitly selects the centroids of analysis
windows (in seconds), if `toi` is `"all"`, analysis windows are centered
on all samples in the data for `method="mtmconvol"`. For wavelet based
methods (`"wavelet"` or `"superlet"`) toi needs to be either an
equidistant array of time points or "all".
t_ftimwin : positive float
Only valid if `method` is `'mtmconvol'`. Sliding window length (in seconds).
wavelet : str
Only valid if `method` is `'wavelet'`. Wavelet function to use, one of
:data:`~syncopy.specest.const_def.availableWavelets` (see below).
width : positive float
Only valid if `method` is `'wavelet'` and `wavelet` is `'Morlet'`. Nondimensional
frequency constant of Morlet wavelet function. This number should be >= 6,
which corresponds to 6 cycles within the analysis window to ensure sufficient
spectral sampling.
order : positive int
Only valid if `method` is `'wavelet'` and `wavelet` is `'Paul'` or `'DOG'`. Order
of the wavelet function. If `wavelet` is `'Paul'`, `order` should be chosen
>= 4 to ensure that the analysis window contains at least a single oscillation.
At an order of 40, the Paul wavelet exhibits about the same number of cycles
as the Morlet wavelet with a `width` of 6.
All other supported wavelets functions are *real-valued* derivatives of
Gaussians (DOGs). Hence, if `wavelet` is `'DOG'`, `order` represents the derivative order.
The special case of a second order DOG yields a function known as "Mexican Hat",
"Marr" or "Ricker" wavelet, which can be selected alternatively by setting
`wavelet` to `'Mexican_hat'`, `'Marr'` or `'Ricker'`. **Note**: A real-valued
wavelet function encodes *only* information about peaks and discontinuities
in the signal and does *not* provide any information about amplitude or phase.
order_max : int
Only valid if `method` is `'superlet'`.
Maximal order of the superlet set. Controls the maximum
number of cycles within a SL together
with the `c_1` parameter: c_max = c_1 * order_max
order_min : int
Only valid if `method` is `'superlet'`.
Minimal order of the superlet set. Controls
the minimal number of cycles within a SL together
with the `c_1` parameter: c_min = c_1 * order_min
Note that for admissability reasons c_min should be at least 3!
c_1 : int
Only valid if `method` is `'superlet'`.
Number of cycles of the base Morlet wavelet. If set to lower
than 3 increase `order_min` as to never have less than 3 cycles
in a wavelet!
adaptive : bool
Only valid if `method` is `'superlet'`.
Wether to perform multiplicative SLT or fractional adaptive SLT.
If set to True, the order of the wavelet set will increase
linearly with the frequencies of interest from `order_min`
to `order_max`. If set to False the same SL will be used for
all frequencies.
out : None or :class:`SpectralData` object
None if a new :class:`SpectralData` object is to be created, or an empty :class:`SpectralData` object
Returns
-------
spec : :class:`~syncopy.SpectralData`
(Time-)frequency spectrum of input data
Notes
-----
.. [Moca2021] Moca, Vasile V., et al. "Time-frequency super-resolution with superlets."
Nature communications 12.1 (2021): 1-18.
**Options**
.. autodata:: syncopy.specest.const_def.availableMethods
.. autodata:: syncopy.specest.const_def.availableOutputs
.. autodata:: syncopy.specest.const_def.availableTapers
.. autodata:: syncopy.specest.const_def.availableWavelets
Examples
--------
Coming soon...
See also
--------
syncopy.specest.mtmfft.mtmfft : (multi-)tapered Fourier transform of multi-channel time series data
syncopy.specest.mtmconvol.mtmconvol : time-frequency analysis of multi-channel time series data with a sliding window FFT
syncopy.specest.wavelet.wavelet : time-frequency analysis of multi-channel time series data using a wavelet transform
numpy.fft.fft : NumPy's reference FFT implementation
scipy.signal.stft : SciPy's Short Time Fourier Transform
"""
# Make sure our one mandatory input object can be processed
try:
data_parser(data, varname="data", dataclass="AnalogData",
writable=None, empty=False)
except Exception as exc:
raise exc
timeAxis = data.dimord.index("time")
# Get everything of interest in local namespace
defaults = get_defaults(freqanalysis)
lcls = locals()
# check for ineffective additional kwargs
check_passed_kwargs(lcls, defaults, frontend_name="freqanalysis")
# Ensure a valid computational method was selected
if method not in availableMethods:
lgl = "'" + "or '".join(opt + "' " for opt in availableMethods)
raise SPYValueError(legal=lgl, varname="method", actual=method)
# Ensure a valid output format was selected
if output not in spectralConversions.keys():
lgl = "'" + "or '".join(opt + "' " for opt in spectralConversions.keys())
raise SPYValueError(legal=lgl, varname="output", actual=output)
# Parse all Boolean keyword arguments
for vname in ["keeptrials", "keeptapers"]:
if not isinstance(lcls[vname], bool):
raise SPYTypeError(lcls[vname], varname=vname, expected="Bool")
# If only a subset of `data` is to be processed, make some necessary adjustments
# of the sampleinfo and trial lengths
if data._selection is not None:
sinfo = data._selection.trialdefinition[:, :2]
trialList = data._selection.trials
else:
trialList = list(range(len(data.trials)))
sinfo = data.sampleinfo
lenTrials = np.diff(sinfo).squeeze()
if not lenTrials.shape:
lenTrials = lenTrials[None]
numTrials = len(trialList)
# check polyremoval
if polyremoval is not None:
scalar_parser(polyremoval, varname="polyremoval", ntype="int_like", lims=[0, 1])
# --- Padding ---
# Sliding window FFT does not support "fancy" padding
if method == "mtmconvol" and isinstance(pad_to_length, str):
msg = "method 'mtmconvol' only supports in-place padding for windows " +\
"exceeding trial boundaries. Your choice of `pad_to_length = '{}'` will be ignored. "
SPYWarning(msg.format(pad_to_length))
if method == 'mtmfft':
# the actual number of samples in case of later padding
minSampleNum = validate_padding(pad_to_length, lenTrials)
else:
minSampleNum = lenTrials.min()
# Compute length (in samples) of shortest trial
minTrialLength = minSampleNum / data.samplerate
# Shortcut to data sampling interval
dt = 1 / data.samplerate
foi, foilim = validate_foi(foi, foilim, data.samplerate)
# see also https://docs.obspy.org/_modules/obspy/signal/detrend.html#polynomial
if polyremoval is not None:
try:
scalar_parser(polyremoval, varname="polyremoval", lims=[0, 1], ntype="int_like")
except Exception as exc:
raise exc
# Prepare keyword dict for logging (use `lcls` to get actually provided
# keyword values, not defaults set above)
log_dct = {"method": method,
"output": output,
"keeptapers": keeptapers,
"keeptrials": keeptrials,
"polyremoval": polyremoval,
"pad_to_length": pad_to_length}
# --------------------------------
# 1st: Check time-frequency inputs
# to prepare/sanitize `toi`
# --------------------------------
if method in ["mtmconvol", "wavelet", "superlet"]:
# Get start/end timing info respecting potential in-place selection
if toi is None:
raise SPYTypeError(toi, varname="toi", expected="scalar or array-like or 'all'")
if data._selection is not None:
tStart = data._selection.trialdefinition[:, 2] / data.samplerate
else:
tStart = data._t0 / data.samplerate
tEnd = tStart + lenTrials / data.samplerate
# for these methods only 'all' or an equidistant array
# of time points (sub-sampling, trimming) are valid
if method in ["wavelet", "superlet"]:
valid = True
if isinstance(toi, Number):
valid = False
elif isinstance(toi, str):
if toi != "all":
valid = False
else:
# take everything
preSelect = [slice(None)] * numTrials
postSelect = [slice(None)] * numTrials
elif not iter(toi):
valid = False
# this is the sequence type - can only be an interval!
else:
try:
array_parser(toi, varname="toi", hasinf=False, hasnan=False,
lims=[tStart.min(), tEnd.max()], dims=(None,))
except Exception as exc:
raise exc
toi = np.array(toi)
# check for equidistancy
if not np.allclose(np.diff(toi, 2), np.zeros(len(toi) - 2)):
valid = False
# trim (preSelect) and subsample output (postSelect)
else:
preSelect = []
postSelect = []
# get sample intervals and relative indices from toi
for tk in range(numTrials):
start = int(data.samplerate * (toi[0] - tStart[tk]))
stop = int(data.samplerate * (toi[-1] - tStart[tk]) + 1)
preSelect.append(slice(max(0, start), max(stop, stop - start)))
smpIdx = np.minimum(lenTrials[tk] - 1,
data.samplerate * (toi - tStart[tk]) - start)
postSelect.append(smpIdx.astype(np.intp))
# get out if sth wasn't right
if not valid:
lgl = "array of equidistant time-points or 'all' for wavelet based methods"
raise SPYValueError(legal=lgl, varname="toi", actual=toi)
# Update `log_dct` w/method-specific options (use `lcls` to get actually
# provided keyword values, not defaults set in here)
log_dct["toi"] = lcls["toi"]
# --------------------------------------------
# Check options specific to mtm*-methods
# (particularly tapers and foi/freqs alignment)
# --------------------------------------------
if "mtm" in method:
if method == "mtmconvol":
# get the sliding window size
try:
scalar_parser(t_ftimwin, varname="t_ftimwin",
lims=[dt, minTrialLength])
except Exception as exc:
SPYInfo("Please specify 't_ftimwin' parameter.. exiting!")
raise exc
# this is the effective sliding window FFT sample size
minSampleNum = int(t_ftimwin * data.samplerate)
# Construct array of maximally attainable frequencies
freqs = np.fft.rfftfreq(minSampleNum, dt)
# Match desired frequencies as close as possible to
# actually attainable freqs
# these are the frequencies attached to the SpectralData by the CR!
if foi is not None:
foi, _ = best_match(freqs, foi, squash_duplicates=True)
elif foilim is not None:
foi, _ = best_match(freqs, foilim, span=True, squash_duplicates=True)
else:
msg = (f"Automatic FFT frequency selection from {freqs[0]:.1f}Hz to "
f"{freqs[-1]:.1f}Hz")
SPYInfo(msg)
foi = freqs
log_dct["foi"] = foi
# Abort if desired frequency selection is empty
if foi.size == 0:
lgl = "non-empty frequency specification"
act = "empty frequency selection"
raise SPYValueError(legal=lgl, varname="foi/foilim", actual=act)
# sanitize taper selection and retrieve dpss settings
taper_opt = validate_taper(taper,
tapsmofrq,
nTaper,
keeptapers,
foimax=foi.max(),
samplerate=data.samplerate,
nSamples=minSampleNum,
output=output)
# Update `log_dct` w/method-specific options
log_dct["taper"] = taper
# only dpss returns non-empty taper_opt dict
if taper_opt:
log_dct["nTaper"] = taper_opt["Kmax"]
log_dct["tapsmofrq"] = tapsmofrq
# -------------------------------------------------------
# Now, prepare explicit compute-classes for chosen method
# -------------------------------------------------------
if method == "mtmfft":
check_effective_parameters(MultiTaperFFT, defaults, lcls)
# method specific parameters
method_kwargs = {
'samplerate': data.samplerate,
'taper': taper,
'taper_opt': taper_opt,
'nSamples': minSampleNum
}
# Set up compute-class
specestMethod = MultiTaperFFT(
foi=foi,
timeAxis=timeAxis,
keeptapers=keeptapers,
polyremoval=polyremoval,
output_fmt=output,
method_kwargs=method_kwargs)
elif method == "mtmconvol":
check_effective_parameters(MultiTaperFFTConvol, defaults, lcls)
# Process `toi` for sliding window multi taper fft,
# we have to account for three scenarios: (1) center sliding
# windows on all samples in (selected) trials (2) `toi` was provided as
# percentage indicating the degree of overlap b/w time-windows and (3) a set
# of discrete time points was provided. These three cases are encoded in
# `overlap, i.e., ``overlap > 1` => all, `0 < overlap < 1` => percentage,
# `overlap < 0` => discrete `toi`
# overlap = None
if isinstance(toi, str):
if toi != "all":
lgl = "`toi = 'all'` to center analysis windows on all time-points"
raise SPYValueError(legal=lgl, varname="toi", actual=toi)
equidistant = True
overlap = np.inf
elif isinstance(toi, Number):
try:
scalar_parser(toi, varname="toi", lims=[0, 1])
except Exception as exc:
raise exc
overlap = toi
equidistant = True
# this captures all other cases, e.i. toi is of sequence type
else:
overlap = -1
try:
array_parser(toi, varname="toi", hasinf=False, hasnan=False,
lims=[tStart.min(), tEnd.max()], dims=(None,))
except Exception as exc:
raise exc
toi = np.array(toi)
tSteps = np.diff(toi)
if (tSteps < 0).any():
lgl = "ordered list/array of time-points"
act = "unsorted list/array"
raise SPYValueError(legal=lgl, varname="toi", actual=act)
# Account for round-off errors: if toi spacing is almost at sample interval
# manually correct it
if np.isclose(tSteps.min(), dt):
tSteps[np.isclose(tSteps, dt)] = dt
if tSteps.min() < dt:
msg = f"`toi` selection too fine, max. time resolution is {dt}s"
SPYWarning(msg)
# This is imho a bug in NumPy - even `arange` and `linspace` may produce
# arrays that are numerically not exactly equidistant - `unique` will
# show several entries here - use `allclose` to identify "even" spacings
equidistant = np.allclose(tSteps, [tSteps[0]] * tSteps.size)
# If `toi` was 'all' or a percentage, use entire time interval of (selected)
# trials and check if those trials have *approximately* equal length
if toi is None:
if not np.allclose(lenTrials, [minSampleNum] * lenTrials.size):
msg = "processing trials of different lengths (min = {}; max = {} samples)" +\
" with `toi = 'all'`"
SPYWarning(msg.format(int(minSampleNum), int(lenTrials.max())))
# number of samples per window
nperseg = int(t_ftimwin * data.samplerate)
halfWin = int(nperseg / 2)
postSelect = slice(None) # select all is the default
if 0 <= overlap <= 1: # `toi` is percentage
noverlap = min(nperseg - 1, int(overlap * nperseg))
# windows get shifted exactly 1 sample
# to get a spectral estimate at each sample
else:
noverlap = nperseg - 1
# `toi` is array
if overlap < 0:
# Compute necessary padding at begin/end of trials to fit sliding windows
offStart = ((toi[0] - tStart) * data.samplerate).astype(np.intp)
padBegin = halfWin - offStart
padBegin = ((padBegin > 0) * padBegin).astype(np.intp)
offEnd = ((tEnd - toi[-1]) * data.samplerate).astype(np.intp)
padEnd = halfWin - offEnd
padEnd = ((padEnd > 0) * padEnd).astype(np.intp)
# Compute sample-indices (one slice/list per trial) from time-selections
soi = []
if equidistant:
# soi just trims the input data to the [toi[0], toi[-1]] interval
# postSelect then subsamples the spectral esimate to the user given toi
postSelect = []
for tk in range(numTrials):
start = max(0, int(round(data.samplerate * (toi[0] - tStart[tk]) - halfWin)))
stop = int(round(data.samplerate * (toi[-1] - tStart[tk]) + halfWin + 1))
soi.append(slice(start, max(stop, stop - start)))
# chosen toi subsampling interval in sample units, min. is 1;
# compute `delta_idx` s.t. stop - start / delta_idx == toi.size
delta_idx = int(round((soi[0].stop - soi[0].start) / toi.size))
delta_idx = delta_idx if delta_idx > 1 else 1
postSelect = slice(None, None, delta_idx)
else:
for tk in range(numTrials):
starts = (data.samplerate * (toi - tStart[tk]) - halfWin).astype(np.intp)
starts += padBegin[tk]
stops = (data.samplerate * (toi - tStart[tk]) + halfWin + 1).astype(np.intp)
stops += padBegin[tk]
stops = np.maximum(stops, stops - starts, dtype=np.intp)
soi.append([slice(start, stop) for start, stop in zip(starts, stops)])
# postSelect here remains slice(None), as resulting spectrum
# has exactly one entry for each soi
# `toi` is percentage or "all"
else:
soi = [slice(None)] * numTrials
# Collect keyword args for `mtmconvol` in dictionary
method_kwargs = {"samplerate": data.samplerate,
"nperseg": nperseg,
"noverlap": noverlap,
"taper" : taper,
"taper_opt" : taper_opt}
# Set up compute-class
specestMethod = MultiTaperFFTConvol(
soi,
postSelect,
equidistant=equidistant,
toi=toi,
foi=foi,
timeAxis=timeAxis,
keeptapers=keeptapers,
polyremoval=polyremoval,
output_fmt=output,
method_kwargs=method_kwargs)
elif method == "wavelet":
check_effective_parameters(WaveletTransform, defaults, lcls)
# Check wavelet selection
if wavelet not in availableWavelets:
lgl = "'" + "or '".join(opt + "' " for opt in availableWavelets)
raise SPYValueError(legal=lgl, varname="wavelet", actual=wavelet)
if wavelet not in ["Morlet", "Paul"]:
msg = "the chosen wavelet '{}' is real-valued and does not provide " +\
"any information about amplitude or phase of the data. This wavelet function " +\
"may be used to isolate peaks or discontinuities in the signal. "
SPYWarning(msg.format(wavelet))
# Check for consistency of `width`, `order` and `wavelet`
if wavelet == "Morlet":
try:
scalar_parser(width, varname="width", lims=[1, np.inf])
except Exception as exc:
raise exc
wfun = getattr(spywave, wavelet)(w0=width)
else:
if width != lcls["width"]:
msg = "option `width` has no effect for wavelet '{}'"
SPYWarning(msg.format(wavelet))
if wavelet == "Paul":
try:
scalar_parser(order, varname="order", lims=[4, np.inf], ntype="int_like")
except Exception as exc:
raise exc
wfun = getattr(spywave, wavelet)(m=order)
elif wavelet == "DOG":
try:
scalar_parser(order, varname="order", lims=[1, np.inf], ntype="int_like")
except Exception as exc:
raise exc
wfun = getattr(spywave, wavelet)(m=order)
else:
if order is not None:
msg = "option `order` has no effect for wavelet '{}'"
SPYWarning(msg.format(wavelet))
wfun = getattr(spywave, wavelet)()
# automatic frequency selection
if foi is None and foilim is None:
scales = get_optimal_wavelet_scales(
wfun.scale_from_period, # all availableWavelets sport one!
int(minTrialLength * data.samplerate),
dt)
foi = 1 / wfun.fourier_period(scales)
msg = (f"Setting frequencies of interest to {foi[0]:.1f}-"
f"{foi[-1]:.1f}Hz")
SPYInfo(msg)
else:
if foilim is not None:
foi = np.arange(foilim[0], foilim[1] + 1, dtype=float)
# 0 frequency is not valid
foi[foi < 0.01] = 0.01
scales = wfun.scale_from_period(1 / foi)
# Update `log_dct` w/method-specific options (use `lcls` to get actually
# provided keyword values, not defaults set in here)
log_dct["foi"] = foi
log_dct["wavelet"] = lcls["wavelet"]
log_dct["width"] = lcls["width"]
log_dct["order"] = lcls["order"]
# method specific parameters
method_kwargs = {
'samplerate' : data.samplerate,
'scales' : scales,
'wavelet' : wfun
}
# Set up compute-class
specestMethod = WaveletTransform(
preSelect,
postSelect,
toi=toi,
timeAxis=timeAxis,
polyremoval=polyremoval,
output_fmt=output,
method_kwargs=method_kwargs)
elif method == "superlet":
check_effective_parameters(SuperletTransform, defaults, lcls)
# check and parse superlet specific arguments
if order_max is None:
lgl = "Positive integer needed for order_max"
raise SPYValueError(legal=lgl, varname="order_max",
actual=None)
else:
scalar_parser(
order_max,
varname="order_max",
lims=[1, np.inf],
ntype="int_like"
)
scalar_parser(
order_min, varname="order_min",
lims=[1, order_max],
ntype="int_like"
)
scalar_parser(c_1, varname="c_1", lims=[1, np.inf], ntype="int_like")
# if no frequencies are user selected, take a sensitive default
if foi is None and foilim is None:
scales = get_optimal_wavelet_scales(
superlet.scale_from_period,
int(minTrialLength * data.samplerate),
dt)
foi = 1 / superlet.fourier_period(scales)
msg = (f"Setting frequencies of interest to {foi[0]:.1f}-"
f"{foi[-1]:.1f}Hz")
SPYInfo(msg)
else:
if foilim is not None:
# frequency range in 1Hz steps
foi = np.arange(foilim[0], foilim[1] + 1, dtype=float)
# 0 frequency is not valid
foi[foi < 0.01] = 0.01
scales = superlet.scale_from_period(1. / foi)
# FASLT needs ordered frequencies low - high
# meaning the scales have to go high - low
if adaptive:
if len(scales) < 2:
lgl = "A range of frequencies"
act = "Single frequency"
raise SPYValueError(legal=lgl, varname="foi", actual=act)
if np.any(np.diff(scales) > 0):
msg = "Sorting frequencies low to high for adaptive SLT.."
SPYWarning(msg)
scales = np.sort(scales)[::-1]
log_dct["foi"] = foi
log_dct["c_1"] = lcls["c_1"]
log_dct["order_max"] = lcls["order_max"]
log_dct["order_min"] = lcls["order_min"]
# method specific parameters
method_kwargs = {
'samplerate' : data.samplerate,
'scales' : scales,
'order_max' : order_max,
'order_min' : order_min,
'c_1' : c_1,
'adaptive' : adaptive
}
# Set up compute-class
specestMethod = SuperletTransform(
preSelect,
postSelect,
toi=toi,
timeAxis=timeAxis,
polyremoval=polyremoval,
output_fmt=output,
method_kwargs=method_kwargs)
# -------------------------------------------------
# Sanitize output and call the ComputationalRoutine
# -------------------------------------------------
# If provided, make sure output object is appropriate
if out is not None:
try:
data_parser(out, varname="out", writable=True, empty=True,
dataclass="SpectralData",
dimord=SpectralData().dimord)
except Exception as exc:
raise exc
new_out = False
else:
out = SpectralData(dimord=SpectralData._defaultDimord)
new_out = True
# Perform actual computation
specestMethod.initialize(data,
out._stackingDim,
chan_per_worker=kwargs.get("chan_per_worker"),
keeptrials=keeptrials)
specestMethod.compute(data, out, parallel=kwargs.get("parallel"), log_dict=log_dct)
# Either return newly created output object or simply quit
return out if new_out else None
def freqanalysis(data,
method='mtmfft',
output='fourier',
keeptrials=True,
foi=None,
foilim=None,
pad=None,
padtype='zero',
padlength=None,
prepadlength=None,
postpadlength=None,
polyremoval=None,
taper="hann",
tapsmofrq=None,
keeptapers=False,
toi=None,
t_ftimwin=None,
wav="Morlet",
width=6,
order=None,
out=None,
**kwargs):
"""
Perform (time-)frequency analysis of Syncopy :class:`~syncopy.AnalogData` objects
**Usage Summary**
Options available in all analysis methods:
* **output** : one of :data:`~.availableOutputs`; return power spectra, complex
Fourier spectra or absolute values.
* **foi**/**foilim** : frequencies of interest; either array of frequencies or
frequency window (not both)
* **keeptrials** : return individual trials or grand average
* **polyremoval** : de-trending method to use (0 = mean, 1 = linear, 2 = quadratic,
3 = cubic, etc.)
List of available analysis methods and respective distinct options:
:func:`~syncopy.specest.mtmfft.mtmfft` : (Multi-)tapered Fourier transform
Perform frequency analysis on time-series trial data using either a single
taper window (Hanning) or many tapers based on the discrete prolate
spheroidal sequence (DPSS) that maximize energy concentration in the main
lobe.
* **taper** : one of :data:`~.availableTapers`
* **tapsmofrq** : spectral smoothing box for tapers (in Hz)
* **keeptapers** : return individual tapers or average
* **pad** : padding method to use (`None`, `True`, `False`, `'absolute'`,
`'relative'`, `'maxlen'` or `'nextpow2'`). If `None`, then `'nextpow2'`
is selected by default.
* **padtype** : values to pad data with (`'zero'`, `'nan'`, `'mean'`, `'localmean'`,
`'edge'` or `'mirror'`)
* **padlength** : number of samples to pre-pend and/or append to each trial
* **prepadlength** : number of samples to pre-pend to each trial
* **postpadlength** : number of samples to append to each trial
:func:`~syncopy.specest.mtmconvol.mtmconvol` : (Multi-)tapered sliding window Fourier transform
Perform time-frequency analysis on time-series trial data based on a sliding
window short-time Fourier transform using either a single Hanning taper or
multiple DPSS tapers.
* **taper** : one of :data:`~.availableTapers`
* **tapsmofrq** : spectral smoothing box for tapers (in Hz)
* **keeptapers** : return individual tapers or average
* **pad** : flag indicating, whether or not to pad trials. If `None`,
trials are padded only if sliding window centroids are too close
to trial boundaries for the entire window to cover available data-points.
* **toi** : time-points of interest; can be either an array representing
analysis window centroids (in sec), a scalar between 0 and 1 encoding
the percentage of overlap between adjacent windows or "all" to center
a window on every sample in the data.
* **t_ftimwin** : sliding window length (in sec)
:func:`~syncopy.specest.wavelet.wavelet` : (Continuous non-orthogonal) wavelet transform
Perform time-frequency analysis on time-series trial data using a non-orthogonal
continuous wavelet transform.
* **wav** : one of :data:`~.availableWavelets`
* **toi** : time-points of interest; can be either an array representing
time points (in sec) to center wavelets on or "all" to center a wavelet
on every sample in the data.
* **width** : Nondimensional frequency constant of Morlet wavelet function (>= 6)
* **order** : Order of Paul wavelet function (>= 4) or derivative order
of real-valued DOG wavelets (2 = mexican hat)
**Full documentation below**
Parameters
----------
data : `~syncopy.AnalogData`
A non-empty Syncopy :class:`~syncopy.datatype.AnalogData` object
method : str
Spectral estimation method, one of :data:`~.availableMethods`
(see below).
output : str
Output of spectral estimation. One of :data:`~.availableOutputs` (see below);
use `'pow'` for power spectrum (:obj:`numpy.float32`), `'fourier'` for complex
Fourier coefficients (:obj:`numpy.complex128`) or `'abs'` for absolute
values (:obj:`numpy.float32`).
keeptrials : bool
If `True` spectral estimates of individual trials are returned, otherwise
results are averaged across trials.
foi : array-like or None
Frequencies of interest (Hz) for output. If desired frequencies cannot be
matched exactly, the closest possible frequencies are used. If `foi` is `None`
or ``foi = "all"``, all attainable frequencies (i.e., zero to Nyquist / 2)
are selected.
foilim : array-like (floats [fmin, fmax]) or None or "all"
Frequency-window ``[fmin, fmax]`` (in Hz) of interest. Window
specifications must be sorted (e.g., ``[90, 70]`` is invalid) and not NaN
but may be unbounded (e.g., ``[-np.inf, 60.5]`` is valid). Edges `fmin`
and `fmax` are included in the selection. If `foilim` is `None` or
``foilim = "all"``, all frequencies are selected.
pad : str or None or bool
One of `None`, `True`, `False`, `'absolute'`, `'relative'`, `'maxlen'` or
`'nextpow2'`.
If `pad` is `None` or ``pad = True``, then method-specific defaults are
chosen. Specifically, if `method` is `'mtmfft'` then `pad` is set to
`'nextpow2'` so that all trials in `data` are padded to the next power of
two higher than the sample-count of the longest (selected) trial in `data`. Conversely,
time-frequency analysis methods (`'mtmconvol'` and `'wavelet'`), only perform
padding if necessary, i.e., if time-window centroids are chosen too close
to trial boundaries for the entire window to cover available data-points.
If `pad` is `False`, then no padding is performed. Then in case of
``method = 'mtmfft'`` all trials have to have approximately the same
length (up to the next even sample-count), if ``method = 'mtmconvol'`` or
``method = 'wavelet'``, window-centroids have to keep sufficient
distance from trial boundaries. For more details on the padding methods
`'absolute'`, `'relative'`, `'maxlen'` and `'nextpow2'` see :func:`syncopy.padding`.
padtype : str
Values to be used for padding. Can be `'zero'`, `'nan'`, `'mean'`,
`'localmean'`, `'edge'` or `'mirror'`. See :func:`syncopy.padding` for
more information.
padlength : None, bool or positive int
Only valid if `method` is `'mtmfft'` and `pad` is `'absolute'` or `'relative'`.
Number of samples to pad data with. See :func:`syncopy.padding` for more
information.
prepadlength : None or bool or int
Only valid if `method` is `'mtmfft'` and `pad` is `'relative'`. Number of
samples to pre-pend to each trial. See :func:`syncopy.padding` for more
information.
postpadlength : None or bool or int
Only valid if `method` is `'mtmfft'` and `pad` is `'relative'`. Number of
samples to append to each trial. See :func:`syncopy.padding` for more
information.
polyremoval : int or None
**FIXME: Not implemented yet**
Order of polynomial used for de-trending data in the time domain prior
to spectral analysis. A value of 0 corresponds to subtracting the mean
("de-meaning"), ``polyremoval = 1`` removes linear trends (subtracting the
least squares fit of a linear polynomial), ``polyremoval = N`` for `N > 1`
subtracts a polynomial of order `N` (``N = 2`` quadratic, ``N = 3`` cubic
etc.). If `polyremoval` is `None`, no de-trending is performed.
taper : str
Only valid if `method` is `'mtmfft'` or `'mtmconvol'`. Windowing function,
one of :data:`~.availableTapers` (see below).
tapsmofrq : float
Only valid if `method` is `'mtmfft'` or `'mtmconvol'`. The amount of spectral
smoothing through multi-tapering (Hz). Note that smoothing frequency
specifications are one-sided, i.e., 4 Hz smoothing means plus-minus 4 Hz,
i.e., a 8 Hz smoothing box.
keeptapers : bool
Only valid if `method` is `'mtmfft'` or `'mtmconvol'`. If `True`, return
spectral estimates for each taper, otherwise results are averaged across
tapers.
toi : float or array-like or "all"
**Mandatory input** for time-frequency analysis methods (`method` is either
`"mtmconvol"` or `"wavelet"`).
If `toi` is scalar, it must be a value between 0 and 1 indicating the
percentage of overlap between time-windows specified by `t_ftimwin` (only
valid if `method` is `'mtmconvol'`, invalid for `'wavelet'`).
If `toi` is an array it explicitly selects the centroids of analysis
windows (in seconds). If `toi` is `"all"`, analysis windows are centered
on all samples in the data.
t_ftimwin : positive float
Only valid if `method` is `'mtmconvol'`. Sliding window length (in seconds).
wav : str
Only valid if `method` is `'wavelet'`. Wavelet function to use, one of
:data:`~.availableWavelets` (see below).
width : positive float
Only valid if `method` is `'wavelet'` and `wav` is `'Morlet'`. Nondimensional
frequency constant of Morlet wavelet function. This number should be >= 6,
which corresponds to 6 cycles within the analysis window to ensure sufficient
spectral sampling.
order : positive int
Only valid if `method` is `'wavelet'` and `wav` is `'Paul'` or `'DOG'`. Order
of the wavelet function. If `wav` is `'Paul'`, `order` should be chosen
>= 4 to ensure that the analysis window contains at least a single oscillation.
At an order of 40, the Paul wavelet exhibits about the same number of cycles
as the Morlet wavelet with a `width` of 6.
All other supported wavelets functions are *real-valued* derivatives of
Gaussians (DOGs). Hence, if `wav` is `'DOG'`, `order` represents the derivative order.
The special case of a second order DOG yields a function known as "Mexican Hat",
"Marr" or "Ricker" wavelet, which can be selected alternatively by setting
`wav` to `'Mexican_hat'`, `'Marr'` or `'Ricker'`. **Note**: A real-valued
wavelet function encodes *only* information about peaks and discontinuities
in the signal and does *not* provide any information about amplitude or phase.
out : None or :class:`SpectralData` object
None if a new :class:`SpectralData` object is to be created, or an empty :class:`SpectralData` object
Returns
-------
spec : :class:`~syncopy.SpectralData`
(Time-)frequency spectrum of input data
Notes
-----
Coming soon...
Examples
--------
Coming soon...
.. autodata:: syncopy.specest.freqanalysis.availableMethods
.. autodata:: syncopy.specest.freqanalysis.availableOutputs
.. autodata:: syncopy.specest.freqanalysis.availableTapers
.. autodata:: syncopy.specest.freqanalysis.availableWavelets
See also
--------
syncopy.specest.mtmfft.mtmfft : (multi-)tapered Fourier transform of multi-channel time series data
syncopy.specest.mtmconvol.mtmconvol : time-frequency analysis of multi-channel time series data with a sliding window FFT
syncopy.specest.wavelet.wavelet : time-frequency analysis of multi-channel time series data using a wavelet transform
numpy.fft.fft : NumPy's reference FFT implementation
scipy.signal.stft : SciPy's Short Time Fourier Transform
"""
# Make sure our one mandatory input object can be processed
try:
data_parser(data,
varname="data",
dataclass="AnalogData",
writable=None,
empty=False)
except Exception as exc:
raise exc
timeAxis = data.dimord.index("time")
# Get everything of interest in local namespace
defaults = get_defaults(freqanalysis)
lcls = locals()
# Ensure a valid computational method was selected
if method not in availableMethods:
lgl = "'" + "or '".join(opt + "' " for opt in availableMethods)
raise SPYValueError(legal=lgl, varname="method", actual=method)
# Ensure a valid output format was selected
if output not in spectralConversions.keys():
lgl = "'" + "or '".join(opt + "' "
for opt in spectralConversions.keys())
raise SPYValueError(legal=lgl, varname="output", actual=output)
# Parse all Boolean keyword arguments
for vname in ["keeptrials", "keeptapers"]:
if not isinstance(lcls[vname], bool):
raise SPYTypeError(lcls[vname], varname=vname, expected="Bool")
# If only a subset of `data` is to be processed, make some necessary adjustments
# and compute minimal sample-count across (selected) trials
if data._selection is not None:
trialList = data._selection.trials
sinfo = np.zeros((len(trialList), 2))
for tk, trlno in enumerate(trialList):
trl = data._preview_trial(trlno)
tsel = trl.idx[timeAxis]
if isinstance(tsel, list):
sinfo[tk, :] = [0, len(tsel)]
else:
sinfo[tk, :] = [
trl.idx[timeAxis].start, trl.idx[timeAxis].stop
]
else:
trialList = list(range(len(data.trials)))
sinfo = data.sampleinfo
lenTrials = np.diff(sinfo).squeeze()
numTrials = len(trialList)
# Set default padding options: after this, `pad` is either `None`, `False` or `str`
defaultPadding = {"mtmfft": "nextpow2", "mtmconvol": None, "wavelet": None}
if pad is None or pad is True:
pad = defaultPadding[method]
# Sliding window FFT does not support "fancy" padding
if method == "mtmconvol" and isinstance(pad, str):
msg = "method 'mtmconvol' only supports in-place padding for windows " +\
"exceeding trial boundaries. Your choice of `pad = '{}'` will be ignored. "
SPYWarning(msg.format(pad))
pad = None
# Ensure padding selection makes sense: do not pad on a by-trial basis but
# use the longest trial as reference and compute `padlength` from there
# (only relevant for "global" padding options such as `maxlen` or `nextpow2`)
if pad:
if not isinstance(pad, str):
raise SPYTypeError(pad, varname="pad", expected="str or None")
if pad == "maxlen":
padlength = lenTrials.max()
prepadlength = True
postpadlength = False
elif pad == "nextpow2":
padlength = 0
for ltrl in lenTrials:
padlength = max(padlength, _nextpow2(ltrl))
pad = "absolute"
prepadlength = True
postpadlength = False
padding(data._preview_trial(trialList[0]),
padtype,
pad=pad,
padlength=padlength,
prepadlength=prepadlength,
postpadlength=postpadlength)
# Compute `minSampleNum` accounting for padding
minSamplePos = lenTrials.argmin()
minSampleNum = padding(data._preview_trial(trialList[minSamplePos]),
padtype,
pad=pad,
padlength=padlength,
prepadlength=True).shape[timeAxis]
else:
if method == "mtmfft" and np.unique(
(np.floor(lenTrials / 2))).size > 1:
lgl = "trials of approximately equal length for method 'mtmfft'"
act = "trials of unequal length"
raise SPYValueError(legal=lgl, varname="data", actual=act)
minSampleNum = lenTrials.min()
# Compute length (in samples) of shortest trial
minTrialLength = minSampleNum / data.samplerate
# Basic sanitization of frequency specifications
if foi is not None:
if isinstance(foi, str):
if foi == "all":
foi = None
else:
raise SPYValueError(legal="'all' or `None` or list/array",
varname="foi",
actual=foi)
else:
try:
array_parser(foi,
varname="foi",
hasinf=False,
hasnan=False,
lims=[0, data.samplerate / 2],
dims=(None, ))
except Exception as exc:
raise exc
foi = np.array(foi, dtype="float")
if foilim is not None:
if isinstance(foilim, str):
if foilim == "all":
foilim = None
else:
raise SPYValueError(legal="'all' or `None` or `[fmin, fmax]`",
varname="foilim",
actual=foilim)
else:
try:
array_parser(foilim,
varname="foilim",
hasinf=False,
hasnan=False,
lims=[0, data.samplerate / 2],
dims=(2, ))
except Exception as exc:
raise exc
if foi is not None and foilim is not None:
lgl = "either `foi` or `foilim` specification"
act = "both"
raise SPYValueError(legal=lgl, varname="foi/foilim", actual=act)
# FIXME: implement detrending
# see also https://docs.obspy.org/_modules/obspy/signal/detrend.html#polynomial
if polyremoval is not None:
raise NotImplementedError("Detrending has not been implemented yet.")
try:
scalar_parser(polyremoval,
varname="polyremoval",
lims=[0, 8],
ntype="int_like")
except Exception as exc:
raise exc
# Prepare keyword dict for logging (use `lcls` to get actually provided
# keyword values, not defaults set above)
log_dct = {
"method": method,
"output": output,
"keeptapers": keeptapers,
"keeptrials": keeptrials,
"polyremoval": polyremoval,
"pad": lcls["pad"],
"padtype": lcls["padtype"],
"padlength": lcls["padlength"],
"foi": lcls["foi"]
}
# 1st: Check time-frequency inputs to prepare/sanitize `toi`
if method in ["mtmconvol", "wavelet"]:
# Get start/end timing info respecting potential in-place selection
if toi is None:
raise SPYTypeError(toi,
varname="toi",
expected="scalar or array-like or 'all'")
if data._selection is not None:
tStart = data._selection.trialdefinition[:, 2] / data.samplerate
else:
tStart = data._t0 / data.samplerate
tEnd = tStart + lenTrials / data.samplerate
# Process `toi`: we have to account for three scenarios: (1) center sliding
# windows on all samples in (selected) trials (2) `toi` was provided as
# percentage indicating the degree of overlap b/w time-windows and (3) a set
# of discrete time points was provided. These three cases are encoded in
# `overlap, i.e., ``overlap > 1` => all, `0 < overlap < 1` => percentage,
# `overlap < 0` => discrete `toi`
if isinstance(toi, str):
if toi != "all":
lgl = "`toi = 'all'` to center analysis windows on all time-points"
raise SPYValueError(legal=lgl, varname="toi", actual=toi)
overlap = 1.1
toi = None
equidistant = True
elif isinstance(toi, Number):
if method == "wavelet":
lgl = "array of time-points wavelets are to be centered on"
act = "scalar value"
raise SPYValueError(legal=lgl, varname="toi", actual=act)
try:
scalar_parser(toi, varname="toi", lims=[0, 1])
except Exception as exc:
raise exc
overlap = toi
equidistant = True
else:
overlap = -1
try:
array_parser(toi,
varname="toi",
hasinf=False,
hasnan=False,
lims=[tStart.min(), tEnd.max()],
dims=(None, ))
except Exception as exc:
raise exc
toi = np.array(toi)
tSteps = np.diff(toi)
if (tSteps < 0).any():
lgl = "ordered list/array of time-points"
act = "unsorted list/array"
raise SPYValueError(legal=lgl, varname="toi", actual=act)
# This is imho a bug in NumPy - even `arange` and `linspace` may produce
# arrays that are numerically not exactly equidistant - `unique` will
# show several entries here - use `allclose` to identify "even" spacings
equidistant = np.allclose(tSteps, [tSteps[0]] * tSteps.size)
# If `toi` was 'all' or a percentage, use entire time interval of (selected)
# trials and check if those trials have *approximately* equal length
if toi is None:
if not np.allclose(lenTrials, [minSampleNum] * lenTrials.size):
msg = "processing trials of different lengths (min = {}; max = {} samples)" +\
" with `toi = 'all'`"
SPYWarning(msg.format(int(minSampleNum), int(lenTrials.max())))
if pad is False:
lgl = "`pad` to be `None` or `True` to permit zero-padding " +\
"at trial boundaries to accommodate windows if `0 < toi < 1` " +\
"or if `toi` is 'all'"
act = "False"
raise SPYValueError(legal=lgl, actual=act, varname="pad")
# Code recycling: `overlap`, `equidistant` etc. are really only relevant
# for `mtmconvol`, but we use padding calc below for `wavelet` as well
if method == "mtmconvol":
try:
scalar_parser(t_ftimwin,
varname="t_ftimwin",
lims=[1 / data.samplerate, minTrialLength])
except Exception as exc:
raise exc
else:
t_ftimwin = 0
nperseg = int(t_ftimwin * data.samplerate)
minSampleNum = nperseg
halfWin = int(nperseg / 2)
# `mtmconvol`: compute no. of samples overlapping across adjacent windows
if overlap < 0: # `toi` is equidistant range or disjoint points
noverlap = nperseg - max(1, int(tSteps[0] * data.samplerate))
elif 0 <= overlap <= 1: # `toi` is percentage
noverlap = min(nperseg - 1, int(overlap * nperseg))
else: # `toi` is "all"
noverlap = nperseg - 1
# `toi` is array
if overlap < 0:
# Compute necessary padding at begin/end of trials to fit sliding windows
offStart = ((toi[0] - tStart) * data.samplerate).astype(np.intp)
padBegin = halfWin - offStart
padBegin = ((padBegin > 0) * padBegin).astype(np.intp)
offEnd = ((tEnd - toi[-1]) * data.samplerate).astype(np.intp)
padEnd = halfWin - offEnd
padEnd = ((padEnd > 0) * padEnd).astype(np.intp)
# Abort if padding was explicitly forbidden
if pad is False and (np.any(padBegin) or np.any(padBegin)):
lgl = "windows within trial bounds"
act = "windows exceeding trials no. " +\
"".join(str(trlno) + ", "\
for trlno in np.array(trialList)[(padBegin + padEnd) > 0])[:-2]
raise SPYValueError(legal=lgl, varname="pad", actual=act)
# Compute sample-indices (one slice/list per trial) from time-selections
soi = []
if not equidistant:
for tk in range(numTrials):
starts = (data.samplerate * (toi - tStart[tk]) -
halfWin).astype(np.intp)
starts += padBegin[tk]
stops = (data.samplerate * (toi - tStart[tk]) + halfWin +
1).astype(np.intp)
stops += padBegin[tk]
stops = np.maximum(stops, stops - starts, dtype=np.intp)
soi.append([
slice(start, stop)
for start, stop in zip(starts, stops)
])
else:
for tk in range(numTrials):
start = int(data.samplerate * (toi[0] - tStart[tk]) -
halfWin)
stop = int(data.samplerate * (toi[-1] - tStart[tk]) +
halfWin + 1)
soi.append(slice(max(0, start), max(stop, stop - start)))
# `toi` is percentage or "all"
else:
padBegin = np.zeros((numTrials, ))
padEnd = np.zeros((numTrials, ))
soi = [slice(None)] * numTrials
# For wavelets, we need to first trim the data (via `preSelect`), then
# extract the wanted time-points (`postSelect`)
if method == "wavelet":
# Simply recycle the indexing work done for `mtmconvol` (i.e., `soi`)
preSelect = []
if not equidistant:
for tk in range(numTrials):
preSelect.append(slice(soi[tk][0].start, soi[tk][-1].stop))
else:
preSelect = soi
# If `toi` is an array, convert "global" indices to "local" ones
# (select within `preSelect`'s selection), otherwise just take all
if overlap < 0:
postSelect = []
for tk in range(numTrials):
smpIdx = np.minimum(
lenTrials[tk] - 1,
data.samplerate * (toi - tStart[tk]) - offStart[tk] +
padBegin[tk])
postSelect.append(smpIdx.astype(np.intp))
else:
postSelect = [slice(None)] * numTrials
# Update `log_dct` w/method-specific options (use `lcls` to get actually
# provided keyword values, not defaults set in here)
if toi is None:
toi = "all"
log_dct["toi"] = lcls["toi"]
# Check options specific to mtm*-methods (particularly tapers and foi/freqs alignment)
if "mtm" in method:
# See if taper choice is supported
if taper not in availableTapers:
lgl = "'" + "or '".join(opt + "' " for opt in availableTapers)
raise SPYValueError(legal=lgl, varname="taper", actual=taper)
taper = getattr(spwin, taper)
# Advanced usage: see if `taperopt` was provided - if not, leave it empty
taperopt = kwargs.get("taperopt", {})
if not isinstance(taperopt, dict):
raise SPYTypeError(taperopt,
varname="taperopt",
expected="dictionary")
# Construct array of maximally attainable frequencies
nFreq = int(np.floor(minSampleNum / 2) + 1)
freqs = np.linspace(0, data.samplerate / 2, nFreq)
# Match desired frequencies as close as possible to actually attainable freqs
if foi is not None:
foi, _ = best_match(freqs, foi, squash_duplicates=True)
elif foilim is not None:
foi, _ = best_match(freqs,
foilim,
span=True,
squash_duplicates=True)
else:
foi = freqs
# Abort if desired frequency selection is empty
if foi.size == 0:
lgl = "non-empty frequency specification"
act = "empty frequency selection"
raise SPYValueError(legal=lgl, varname="foi/foilim", actual=act)
# Set/get `tapsmofrq` if we're working w/Slepian tapers
if taper.__name__ == "dpss":
# Try to derive "sane" settings by using 3/4 octave smoothing of highest `foi`
# following Hipp et al. "Oscillatory Synchronization in Large-Scale
# Cortical Networks Predicts Perception", Neuron, 2011
if tapsmofrq is None:
foimax = foi.max()
tapsmofrq = (foimax * 2**(3 / 4 / 2) -
foimax * 2**(-3 / 4 / 2)) / 2
else:
try:
scalar_parser(tapsmofrq,
varname="tapsmofrq",
lims=[1, np.inf])
except Exception as exc:
raise exc
# Get/compute number of tapers to use (at least 1 and max. 50)
nTaper = taperopt.get("Kmax", 1)
if not taperopt:
nTaper = int(
max(
2,
min(
50,
np.floor(tapsmofrq * minSampleNum * 1 /
data.samplerate))))
taperopt = {"NW": tapsmofrq, "Kmax": nTaper}
else:
nTaper = 1
# Warn the user in case `tapsmofrq` has no effect
if tapsmofrq is not None and taper.__name__ != "dpss":
msg = "`tapsmofrq` is only used if `taper` is `dpss`!"
SPYWarning(msg)
# Update `log_dct` w/method-specific options (use `lcls` to get actually
# provided keyword values, not defaults set in here)
log_dct["taper"] = lcls["taper"]
log_dct["tapsmofrq"] = lcls["tapsmofrq"]
log_dct["nTaper"] = nTaper
# Check for non-default values of options not supported by chosen method
kwdict = {"wav": wav, "width": width}
for name, kwarg in kwdict.items():
if kwarg is not lcls[name]:
msg = "option `{}` has no effect in methods `mtmfft` and `mtmconvol`!"
SPYWarning(msg.format(name))
# Now, prepare explicit compute-classes for chosen method
if method == "mtmfft":
# Check for non-default values of options not supported by chosen method
kwdict = {"t_ftimwin": t_ftimwin, "toi": toi}
for name, kwarg in kwdict.items():
if kwarg is not lcls[name]:
msg = "option `{}` has no effect in method `mtmfft`!"
SPYWarning(msg.format(name))
# Set up compute-class
specestMethod = MultiTaperFFT(samplerate=data.samplerate,
foi=foi,
nTaper=nTaper,
timeAxis=timeAxis,
taper=taper,
taperopt=taperopt,
tapsmofrq=tapsmofrq,
pad=pad,
padtype=padtype,
padlength=padlength,
keeptapers=keeptapers,
polyremoval=polyremoval,
output_fmt=output)
elif method == "mtmconvol":
# Set up compute-class
specestMethod = MultiTaperFFTConvol(soi,
list(padBegin),
list(padEnd),
samplerate=data.samplerate,
noverlap=noverlap,
nperseg=nperseg,
equidistant=equidistant,
toi=toi,
foi=foi,
nTaper=nTaper,
timeAxis=timeAxis,
taper=taper,
taperopt=taperopt,
pad=pad,
padtype=padtype,
padlength=padlength,
prepadlength=prepadlength,
postpadlength=postpadlength,
keeptapers=keeptapers,
polyremoval=polyremoval,
output_fmt=output)
elif method == "wavelet":
# Check for non-default values of `taper`, `tapsmofrq`, `keeptapers` and
# `t_ftimwin` (set to 0 above)
kwdict = {
"taper": taper,
"tapsmofrq": tapsmofrq,
"keeptapers": keeptapers
}
for name, kwarg in kwdict.items():
if kwarg is not lcls[name]:
msg = "option `{}` has no effect in method `wavelet`!"
SPYWarning(msg.format(name))
if t_ftimwin != 0:
msg = "option `t_ftimwin` has no effect in method `wavelet`!"
SPYWarning(msg)
# Check wavelet selection
if wav not in availableWavelets:
lgl = "'" + "or '".join(opt + "' " for opt in availableWavelets)
raise SPYValueError(legal=lgl, varname="wav", actual=wav)
if wav not in ["Morlet", "Paul"]:
msg = "the chosen wavelet '{}' is real-valued and does not provide " +\
"any information about amplitude or phase of the data. This wavelet function " +\
"may be used to isolate peaks or discontinuities in the signal. "
SPYWarning(msg.format(wav))
# Check for consistency of `width`, `order` and `wav`
if wav == "Morlet":
try:
scalar_parser(width, varname="width", lims=[1, np.inf])
except Exception as exc:
raise exc
wfun = getattr(spywave, wav)(w0=width)
else:
if width != lcls["width"]:
msg = "option `width` has no effect for wavelet '{}'"
SPYWarning(msg.format(wav))
if wav == "Paul":
try:
scalar_parser(order,
varname="order",
lims=[4, np.inf],
ntype="int_like")
except Exception as exc:
raise exc
wfun = getattr(spywave, wav)(m=order)
elif wav == "DOG":
try:
scalar_parser(order,
varname="order",
lims=[1, np.inf],
ntype="int_like")
except Exception as exc:
raise exc
wfun = getattr(spywave, wav)(m=order)
else:
if order is not None:
msg = "option `order` has no effect for wavelet '{}'"
SPYWarning(msg.format(wav))
wfun = getattr(spywave, wav)()
# Process frequency selection (`toi` was taken care of above): `foilim`
# selections are wrapped into `foi` thus the seemingly weird if construct
# Note: SLURM workers don't like monkey-patching, so let's pretend
# `get_optimal_wavelet_scales` is a class method by passing `wfun` as its
# first argument
if foi is None:
scales = _get_optimal_wavelet_scales(
wfun, int(minTrialLength * data.samplerate),
1 / data.samplerate)
if foilim is not None:
foi = np.arange(foilim[0], foilim[1] + 1)
if foi is not None:
foi[foi < 0.01] = 0.01
scales = wfun.scale_from_period(1 / foi)
scales = scales[::
-1] # FIXME: this only makes sense if `foi` was sorted -> cf Issue #94
# Update `log_dct` w/method-specific options (use `lcls` to get actually
# provided keyword values, not defaults set in here)
log_dct["wav"] = lcls["wav"]
log_dct["width"] = lcls["width"]
log_dct["order"] = lcls["order"]
# Set up compute-class
specestMethod = WaveletTransform(preSelect,
postSelect,
list(padBegin),
list(padEnd),
samplerate=data.samplerate,
toi=toi,
scales=scales,
timeAxis=timeAxis,
wav=wfun,
polyremoval=polyremoval,
output_fmt=output)
# If provided, make sure output object is appropriate
if out is not None:
try:
data_parser(out,
varname="out",
writable=True,
empty=True,
dataclass="SpectralData",
dimord=SpectralData().dimord)
except Exception as exc:
raise exc
new_out = False
else:
out = SpectralData(dimord=SpectralData._defaultDimord)
new_out = True
# Perform actual computation
specestMethod.initialize(data,
chan_per_worker=kwargs.get("chan_per_worker"),
keeptrials=keeptrials)
specestMethod.compute(data,
out,
parallel=kwargs.get("parallel"),
log_dict=log_dct)
# Either return newly created output object or simply quit
return out if new_out else None
def padding(data,
padtype,
pad="absolute",
padlength=None,
prepadlength=None,
postpadlength=None,
unit="samples",
create_new=True):
"""
Perform data padding on Syncopy object or :class:`numpy.ndarray`
**Usage Summary**
Depending on the value of `pad` the following padding length specifications
are supported:
+------------+----------------------+---------------+----------------------+----------------------+
| `pad` | `data` | `padlength` | `prepadlength` | `postpadlength` |
+============+======================+===============+======================+======================+
| 'absolute' | Syncopy object/array | number | `None`/`bool` | `None`/`bool` |
+------------+----------------------+---------------+----------------------+----------------------+
| 'relative' | Syncopy object/array | number/`None` | number/`None`/`bool` | number/`None`/`bool` |
+------------+----------------------+---------------+----------------------+----------------------+
| 'maxlen' | Syncopy object | `None`/`bool` | `None`/`bool` | `None`/`bool` |
+------------+----------------------+---------------+----------------------+----------------------+
| 'nextpow2' | Syncopy object/array | `None`/`bool` | `None`/`bool` | `None`/`bool` |
+------------+----------------------+---------------+----------------------+----------------------+
* `data` can be either a Syncopy object containing multiple trials or a
:class:`numpy.ndarray` representing a single trial
* (pre/post)padlength: can be either `None`, `True`/`False` or a positive
number: if `True` indicates where to pad, e.g., by using ``pad =
'maxlen'`` and ``prepadlength = True``, `data` is padded at the beginning
of each trial. **Only** if `pad` is 'relative' are scalar values supported
for `prepadlength` and `postpadlength`
* ``pad = 'absolute'``: pad to desired absolute length, e.g., by using ``pad
= 5`` and ``unit = 'time'`` all trials are (if necessary) padded to 5s
length. Here, `padlength` **has** to be provided, `prepadlength` and
`postpadlength` can be `None` or `True`/`False`
* ``pad = 'relative'``: pad by provided `padlength`, e.g., by using
``padlength = 20`` and ``unit = 'samples'``, 20 samples are padded
symmetrically around (before and after) each trial. Use ``padlength = 20``
and ``prepadlength = True`` **or** directly ``prepadlength = 20`` to pad
before each trial. Here, at least one of `padlength`, `prepadlength` or
`postpadlength` **has** to be provided.
* ``pad = 'maxlen'``: (only valid for **Syncopy objects**) pad up to maximal
trial length found in `data`. All lengths have to be either Boolean
indicating padding location or `None` (if all are `None`, symmetric
padding is performed)
* ``pad = 'nextpow2'``: pad each trial up to closest power of two. All
lengths have to be either Boolean indicating padding location or `None`
(if all are `None`, symmetric padding is performed)
Full documentation below.
Parameters
----------
data : Syncopy object or :class:`numpy.ndarray`
Non-empty Syncopy data object or array representing numeric data to be
padded. **NOTE**: if `data` is a :class:`numpy.ndarray`, it is assumed
that it represents recordings from only a single trial, where its first
axis corresponds to time. In other words, `data` is a
'time'-by-'channel' array such that its rows reflect samples and its
columns represent channels. If `data` is a Syncopy object, trial
information and dimensional order are fetched from `data.trials` and
`data.dimord`, respectively.
padtype : str
Padding value(s) to be used. Available options are:
* 'zero' : pad using zeros
* 'nan' : pad using `np.nan`'s
* 'mean' : pad with by-channel mean value across each trial
* 'localmean' : pad with by-channel mean value using only `padlength` or
`prepadlength`/`postpadlength` number of boundary-entries for averaging
* 'edge' : pad with trial-boundary values
* 'mirror' : pad with reflections of trial-boundary values
pad : str
Padding mode to be used. Available options are:
* 'absolute' : pad each trial to achieve a desired absolute length such
that all trials have identical length post padding. If `pad` is `absolute`
a `padlength` **has** to be provided, `prepadlength` and `postpadlength`
may be `True` or `False`, respectively (see Examples for details).
* 'relative' : pad each trial by provided `padlength` such that all trials
are extended by the same amount regardless of their original lengths.
If `pad` is `relative`, `prepadlength` and `postpadlength` can either
be specified directly (using numerical values) or implicitly by only
providing `padlength` and setting `prepadlength` and `postpadlength`
to `True` or `False`, respectively (see Examples for details). If `pad`
is `relative` at least one of `padlength`, `prepadlength` or `postpadlength`
**has** to be provided.
* 'maxlen' : only usable if `data` is a Syncopy object. If `pad` is
'maxlen' all trials are padded to achieve the length of the longest
trial in `data`, i.e., post padding, all trials have the same length,
which equals the size of the longest trial pre-padding. For
``pad = 'maxlen'``, `padlength`, `prepadlength` as well as `postpadlength`
have to be either Boolean or `None` indicating the preferred padding
location (pre-trial, post-trial or symmetrically pre- and post-trial).
If all are `None`, symmetric padding is performed (see Examples for
details).
* 'nextpow2' : pad each trial to achieve a length equals the closest power
of two of its original length. For ``pad = 'nextpow2'``, `padlength`,
`prepadlength` as well as `postpadlength` have to be either Boolean
or `None` indicating the preferred padding location (pre-trial, post-trial
or symmetrically pre- and post-trial). If all are `None`, symmetric
padding is performed (see Examples for details).
padlength : None, bool or positive scalar
Length to be padded to `data` (if `padlength` is scalar-valued) or
padding location (if `padlength` is Boolean). Depending on the value of
`pad`, `padlength` can be used to pre-pend (if `padlength` is a positive
number and `prepadlength` is `True`) or append trials (if `padlength` is
a positive number and `postpadlength` is `True`). If neither
`prepadlength` nor `postpadlength` are specified (i.e, both are `None`),
symmetric pre- and post-trial padding is performed (i.e., ``0.5 * padlength``
before and after each trial - note that odd sample counts are rounded downward
to the nearest even integer). If ``unit = 'time'``, `padlength` is assumed
to be given in seconds, otherwise (``unit = 'samples'``), `padlength` is
interpreted as sample-count. Note that only ``pad = 'relative'`` and
``pad = 'absolute'`` support numeric values of `padlength`.
prepadlength : None, bool or positive scalar
Length to be pre-pended before each trial (if `prepadlength` is
scalar-valued) or pre-padding flag (if `prepadlength` is `True`). If
`prepadlength` is `True`, pre-padding length is either directly inferred
from `padlength` or implicitly derived from chosen padding mode defined
by `pad`. If ``unit = 'time'``, `prepadlength` is assumed to be given in
seconds, otherwise (``unit = 'samples'``), `prepadlength` is interpreted
as sample-count. Note that only ``pad = 'relative'`` supports numeric
values of `prepadlength`.
postpadlength : None, bool or positive scalar
Length to be appended after each trial (if `postpadlength` is
scalar-valued) or post-padding flag (if `postpadlength` is `True`). If
`postpadlength` is `True`, post-padding length is either directly inferred
from `padlength` or implicitly derived from chosen padding mode defined
by `pad`. If ``unit = 'time'``, `postpadlength` is assumed to be given in
seconds, otherwise (``unit = 'samples'``), `postpadlength` is interpreted
as sample-count. Note that only ``pad = 'relative'`` supports numeric
values of `postpadlength`.
unit : str
Unit of numerical values given by `padlength` and/or `prepadlength`
and/or `postpadlength`. If ``unit = 'time'``, `padlength`,
`prepadlength`, and `postpadlength` are assumed to be given in seconds,
otherwise (``unit = 'samples'``), `padlength`, `prepadlength`, and
`postpadlength` are interpreted as sample-counts. **Note** Providing
padding lengths in seconds (i.e., ``unit = 'time'``) is only supported
if `data` is a Syncopy object.
create_new : bool
If `True`, a padded copy of the same type as `data` is returned (a
:class:`numpy.ndarray` or Syncopy object). If `create_new` is `False`,
either a single dictionary (if `data` is a :class:`numpy.ndarray`) or a
``len(data.trials)``-long list of dictionaries (if `data` is a Syncopy
object) with all necessary options for performing the actual padding
operation with :func:`numpy.pad` is returned.
Returns
-------
pad_dict : dict, if `data` is a :class:`numpy.ndarray` and ``create_new = False``
Dictionary whose items contain all necessary parameters for calling
:func:`numpy.pad` to perform the desired padding operation on `data`.
pad_dicts : list, if `data` is a Syncopy object and ``create_new = False``
List of dictionaries for calling :func:`numpy.pad` to perform the
desired padding operation on all trials found in `data`.
out : :class:`numpy.ndarray`, if `data` is a :class:`numpy.ndarray` and ``create_new = True``
Padded version (deep copy) of `data`
out : Syncopy object, if `data` is a Syncopy object and ``create_new = True``
Padded version (deep copy) of `data`
Notes
-----
This method emulates (and extends) FieldTrip's `ft_preproc_padding` by
providing a convenience wrapper for NumPy's :func:`numpy.pad` that performs
the actual heavy lifting.
Examples
--------
Consider the following small array representing a toy-problem-trial of `ns`
samples across `nc` channels:
>>> nc = 7; ns = 30
>>> trl = np.random.randn(ns, nc)
We start by padding a total of 10 zeros symmetrically to `trl`
>>> padded = spy.padding(trl, 'zero', pad='relative', padlength=10)
>>> padded[:6, :]
array([[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[-1.0866, 2.3358, 0.8758, 0.5196, 0.8049, -0.659 , -0.9173]])
>>> padded[-6:, :]
array([[ 0.027 , 1.8069, 1.5249, -0.7953, -0.8933, 1.0202, -0.6862],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ],
[ 0. , 0. , 0. , 0. , 0. , 0. , 0. ]])
>>> padded.shape
(40, 7)
Note that the above call is equivalent to
>>> padded_ident = spy.padding(trl, 'zero', pad='relative', padlength=10, prepadlength=True, postpadlength=True)
>>> np.array_equal(padded_ident, padded)
True
>>> padded_ident = spy.padding(trl, 'zero', pad='relative', prepadlength=5, postpadlength=5)
>>> np.array_equal(padded_ident, padded)
True
Similarly,
>>> prepad = spy.padding(trl, 'nan', pad='relative', prepadlength=10)
is the same as
>>> prepad_ident = spy.padding(trl, 'nan', pad='relative', padlength=10, prepadlength=True)
>>> np.allclose(prepad, prepad_ident, equal_nan=True)
True
Define bogus trials on `trl` and create a dummy object with unit samplerate
>>> tdf = np.vstack([np.arange(0, ns, 5),
np.arange(5, ns + 5, 5),
np.ones((int(ns / 5), )),
np.ones((int(ns / 5), )) * np.pi]).T
>>> adata = spy.AnalogData(trl, trialdefinition=tdf, samplerate=1)
Pad each trial to the closest power of two by appending by-trial channel
averages. However, do not perform actual padding, but only prepare dictionaries
of parameters to be passed on to :func:`numpy.pad`
>>> pad_dicts = spy.padding(adata, 'mean', pad='nextpow2', postpadlength=True, create_new=False)
>>> len(pad_dicts) == len(adata.trials)
True
>>> pad_dicts[0]
{'pad_width': array([[0, 3],
[0, 0]]), 'mode': 'mean'}
Similarly, the following call generates a list of dictionaries preparing
absolute padding by prepending zeros with :func:`numpy.pad`
>>> pad_dicts = spy.padding(adata, 'zero', pad='absolute', padlength=10, prepadlength=True, create_new=False)
>>> pad_dicts[0]
{'pad_width': array([[5, 0],
[0, 0]]), 'mode': 'constant', 'constant_values': 0}
See also
--------
numpy.pad : fast array padding in NumPy
"""
# Detect whether input is data object or array-like
if any(["BaseData" in str(base) for base in data.__class__.__mro__]):
try:
data_parser(data,
varname="data",
dataclass="AnalogData",
empty=False)
except Exception as exc:
raise exc
timeAxis = data.dimord.index("time")
spydata = True
elif data.__class__.__name__ == "FauxTrial":
if len(data.shape) != 2:
lgl = "two-dimensional AnalogData trial segment"
act = "{}-dimensional trial segment"
raise SPYValueError(legal=lgl,
varname="data",
actual=act.format(len(data.shape)))
timeAxis = data.dimord.index("time")
spydata = False
else:
try:
array_parser(data, varname="data", dims=2)
except Exception as exc:
raise exc
timeAxis = 0
spydata = False
# FIXME: Creation of new spy-object currently not supported
if not isinstance(create_new, bool):
raise SPYTypeError(create_new, varname="create_new", expected="bool")
if spydata and create_new:
raise NotImplementedError(
"Creation of padded spy objects currently not supported. ")
# Use FT-compatible options (sans FT option 'remove')
if not isinstance(padtype, str):
raise SPYTypeError(padtype, varname="padtype", expected="string")
options = ["zero", "nan", "mean", "localmean", "edge", "mirror"]
if padtype not in options:
lgl = "'" + "or '".join(opt + "' " for opt in options)
raise SPYValueError(legal=lgl, varname="padtype", actual=padtype)
# Check `pad` and ensure we can actually perform the requested operation
if not isinstance(pad, str):
raise SPYTypeError(pad, varname="pad", expected="string")
options = ["absolute", "relative", "maxlen", "nextpow2"]
if pad not in options:
lgl = "'" + "or '".join(opt + "' " for opt in options)
raise SPYValueError(legal=lgl, varname="pad", actual=pad)
if pad == "maxlen" and not spydata:
lgl = "syncopy data object when using option 'maxlen'"
raise SPYValueError(legal=lgl, varname="pad", actual="maxlen")
# Make sure a data object was provided if we're working with time values
if not isinstance(unit, str):
raise SPYTypeError(unit, varname="unit", expected="string")
options = ["samples", "time"]
if unit not in options:
lgl = "'" + "or '".join(opt + "' " for opt in options)
raise SPYValueError(legal=lgl, varname="unit", actual=unit)
if unit == "time" and not spydata:
raise SPYValueError(
legal="syncopy data object when using option 'time'",
varname="unit",
actual="time")
# Set up dictionary for type-checking of provided padding lengths
nt_dict = {"samples": "int_like", "time": None}
# If we're padding up to an absolute bound or the max. length across
# trials, compute lower bound for padding (in samples or seconds)
if pad in ["absolute", "maxlen"]:
if spydata:
maxTrialLen = np.diff(data.sampleinfo).max()
else:
maxTrialLen = data.shape[
timeAxis] # if `pad="absolute" and data is array
else:
maxTrialLen = np.inf
if unit == "time":
padlim = maxTrialLen / data.samplerate
else:
padlim = maxTrialLen
# To ease option processing, collect padding length keywords in dict
plengths = {
"padlength": padlength,
"prepadlength": prepadlength,
"postpadlength": postpadlength
}
# In case of relative padding, we need at least one scalar value to proceed
if pad == "relative":
# If `padlength = None`, pre- or post- need to be set; if `padlength`
# is set, both pre- and post- need to be `None` or `True`/`False`.
# After this code block, pre- and post- are guaranteed to be numeric.
if padlength is None:
for key in ["prepadlength", "postpadlength"]:
if plengths[key] is not None:
try:
scalar_parser(plengths[key],
varname=key,
ntype=nt_dict[unit],
lims=[0, np.inf])
except Exception as exc:
raise exc
else:
plengths[key] = 0
else:
try:
scalar_parser(padlength,
varname="padlength",
ntype=nt_dict[unit],
lims=[0, np.inf])
except Exception as exc:
raise exc
for key in ["prepadlength", "postpadlength"]:
if not isinstance(plengths[key], (bool, type(None))):
raise SPYTypeError(plengths[key],
varname=key,
expected="bool or None")
if prepadlength is None and postpadlength is None:
prepadlength = True
postpadlength = True
else:
prepadlength = prepadlength is not None
postpadlength = postpadlength is not None
if prepadlength and postpadlength:
plengths["prepadlength"] = padlength / 2
plengths["postpadlength"] = padlength / 2
else:
plengths["prepadlength"] = prepadlength * padlength
plengths["postpadlength"] = postpadlength * padlength
# Under-determined: abort if requested padding length is 0
if all(value == 0 for value in plengths.values() if value is not None):
lgl = "either non-zero value of `padlength` or `prepadlength` " + \
"and/or `postpadlength` to be set"
raise SPYValueError(legal=lgl,
varname="padlength",
actual="0|None")
else:
# For absolute padding, the desired length has to be >= max. trial length
if pad == "absolute":
try:
scalar_parser(padlength,
varname="padlength",
ntype=nt_dict[unit],
lims=[padlim, np.inf])
except Exception as exc:
raise exc
for key in ["prepadlength", "postpadlength"]:
if not isinstance(plengths[key], (bool, type(None))):
raise SPYTypeError(plengths[key],
varname=key,
expected="bool or None")
# For `maxlen` or `nextpow2` we don't want any numeric entries at all
else:
for key, value in plengths.items():
if not isinstance(value, (bool, type(None))):
raise SPYTypeError(value,
varname=key,
expected="bool or None")
# Warn of potential conflicts
if padlength and (prepadlength or postpadlength):
msg = "Found `padlength` and `prepadlength` and/or " +\
"`postpadlength`. Symmetric padding is performed. "
SPYWarning(msg)
# If both pre-/post- are `None`, set them to `True` to use symmetric
# padding, otherwise convert `None` entries to `False`
if prepadlength is None and postpadlength is None:
plengths["prepadlength"] = True
plengths["postpadlength"] = True
else:
plengths["prepadlength"] = plengths["prepadlength"] is not None
plengths["postpadlength"] = plengths["postpadlength"] is not None
# Update pre-/post-padding and (if required) convert time to samples
prepadlength = plengths["prepadlength"]
postpadlength = plengths["postpadlength"]
if unit == "time":
if pad == "relative":
prepadlength = int(prepadlength * data.samplerate)
postpadlength = int(postpadlength * data.samplerate)
elif pad == "absolute":
padlength = int(padlength * data.samplerate)
# Construct dict of keywords for ``np.pad`` depending on chosen `padtype`
kws = {
"zero": {
"mode": "constant",
"constant_values": 0
},
"nan": {
"mode": "constant",
"constant_values": np.nan
},
"localmean": {
"mode": "mean",
"stat_length": -1
},
"mean": {
"mode": "mean"
},
"edge": {
"mode": "edge"
},
"mirror": {
"mode": "reflect"
}
}
# If in put was syncopy data object, padding is done on a per-trial basis
if spydata:
# A list of input keywords for ``np.pad`` is constructed, no matter if
# we actually want to build a new object or not
pad_opts = []
for trl in data.trials:
nSamples = trl.shape[timeAxis]
if pad == "absolute":
padding = (padlength - nSamples) / (prepadlength +
postpadlength)
elif pad == "relative":
padding = True
elif pad == "maxlen":
padding = (maxTrialLen - nSamples) / (prepadlength +
postpadlength)
elif pad == "nextpow2":
padding = (_nextpow2(nSamples) - nSamples) / (prepadlength +
postpadlength)
pw = np.zeros((2, 2), dtype=int)
pw[timeAxis, :] = [prepadlength * padding, postpadlength * padding]
pad_opts.append(dict({"pad_width": pw}, **kws[padtype]))
if padtype == "localmean":
pad_opts[-1]["stat_length"] = pw[timeAxis, :]
if create_new:
pass
else:
return pad_opts
# Input was a array/FauxTrial (i.e., single trial) - we have to do the padding just once
else:
nSamples = data.shape[timeAxis]
if pad == "absolute":
padding = (padlength - nSamples) / (prepadlength + postpadlength)
elif pad == "relative":
padding = True
elif pad == "nextpow2":
padding = (_nextpow2(nSamples) - nSamples) / (prepadlength +
postpadlength)
pw = np.zeros((2, 2), dtype=int)
pw[timeAxis, :] = [prepadlength * padding, postpadlength * padding]
pad_opts = dict({"pad_width": pw}, **kws[padtype])
if padtype == "localmean":
pad_opts["stat_length"] = pw[timeAxis, :]
if create_new:
if isinstance(data, np.ndarray):
return np.pad(data, **pad_opts)
else: # FIXME: currently only supports FauxTrial
shp = list(data.shape)
shp[timeAxis] += pw[timeAxis, :].sum()
idx = list(data.idx)
if isinstance(idx[timeAxis], slice):
idx[timeAxis] = slice(idx[timeAxis].start,
idx[timeAxis].start + shp[timeAxis])
else:
idx[timeAxis] = pw[timeAxis, 0] * [idx[timeAxis][0]] + idx[timeAxis] \
+ pw[timeAxis, 1] * [idx[timeAxis][-1]]
return data.__class__(shp, idx, data.dtype, data.dimord)
else:
return pad_opts
def test_sorted_arrays(self):
ladder = np.arange(10)
array_parser(ladder, issorted=True)
array_parser(ladder, dims=1, ntype="int_like", issorted=True)
array_parser([1, 0, 4], issorted=False)
with pytest.raises(SPYValueError) as spyval:
array_parser(np.ones((2, 2)), issorted=True)
errmsg = "'2-dimensional array'; expected 1-dimensional array"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser(np.ones((3, 1)), issorted=True)
errmsg = "'unsorted array'; expected array with elements in ascending order"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser(ladder[::-1], issorted=True)
errmsg = "'unsorted array'; expected array with elements in ascending order"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser([1 + 3j, 3, 4], issorted=True)
errmsg = "'array containing complex elements'; expected real-valued array"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser(ladder, issorted=False)
errmsg = "'array with elements in ascending order'; expected unsorted array"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser(['a', 'b', 'c'], issorted=True)
errmsg = "expected dtype = numeric"
assert errmsg in str(spyval.value)
with pytest.raises(SPYValueError) as spyval:
array_parser(np.ones(0), issorted=True)
errmsg = "'array containing (fewer than) one element"
assert errmsg in str(spyval.value)
def load(filename,
tag=None,
dataclass=None,
checksum=False,
mode="r+",
out=None):
"""
Load Syncopy data object(s) from disk
Either loads single files within or outside of '.spy'-containers or loads
multiple objects from a single '.spy'-container. Loading from containers can
be further controlled by imposing restrictions on object class(es) (via
`dataclass`) and file-name tag(s) (via `tag`).
Parameters
----------
filename : str
Either path to Syncopy container folder (\*.spy, if omitted, the extension
'.spy' will be appended) or name of data or metadata file. If `filename`
points to a container and no further specifications are provided, the
entire contents of the container is loaded. Otherwise, specific objects
may be selected using the `dataclass` or `tag` keywords (see below).
tag : None or str or list
If `filename` points to a container, `tag` may be used to filter objects
by filename-`tag`. Multiple tags can be provided using a list, e.g.,
``tag = ['experiment1', 'experiment2']``. Can be combined with `dataclass`
(see below). Invalid if `filename` points to a single file.
dataclass : None or str or list
If provided, only objects of provided dataclass are loaded from disk.
Available options are '.analog', '.spectral', .spike' and '.event'
(as listed in ``spy.FILE_EXT["data"]``). Multiple class specifications
can be provided using a list, e.g., ``dataclass = ['.analog', '.spike']``.
Can be combined with `tag` (see above) and is also valid if `filename`
points to a single file (e.g., to ensure loaded object is of a specific
type).
checksum : bool
If `True`, checksum-matching is performed on loaded object(s) to ensure
data-integrity (impairs performance particularly when loading large files).
mode : str
Data access mode of loaded objects (can be 'r' for read-only, 'r+' or 'w'
for read/write access).
out : Syncopy data object
Empty object to be filled with data loaded from disk. Has to match the
type of the on-disk file (e.g., ``filename = 'mydata.analog'`` requires
`out` to be a :class:`syncopy.AnalogData` object). Can only be used
when loading single objects from disk (`out` is ignored when multiple
files are loaded from a container).
Returns
-------
Nothing : None
If a single file is loaded and `out` was provided, `out` is filled with
data loaded from disk, i.e., :func:`syncopy.load` does **not** create a
new object
obj : Syncopy data object
If a single file is loaded and `out` was `None`, :func:`syncopy.load`
returns a new object.
objdict : dict
If multiple files are loaded, :func:`syncopy.load` creates a new object
for each file and places them in a dictionary whose keys are the base-names
(sans path) of the corresponding files.
Notes
-----
All of Syncopy's classes offer (limited) support for data loading upon object
creation. Just as the class method ``.save`` can be used as a shortcut for
:func:`syncopy.save`, Syncopy objects can be created from Syncopy data-files
upon creation, e.g.,
>>> adata = spy.AnalogData('/path/to/session1.analog')
creates a new :class:`syncopy.AnalogData` object and immediately fills it
with data loaded from the file "/path/to/session1.analog".
Since only one object can be created at a time, this loading shortcut only
supports single file specifications (i.e., ``spy.AnalogData("container.spy")``
is invalid).
Examples
--------
Load all objects found in the spy-container "sessionName" (the extension ".spy"
may or may not be provided)
>>> objectDict = spy.load("sessionName")
>>> # --> returns a dict with base-filenames as keys
Load all :class:`syncopy.AnalogData` and :class:`syncopy.SpectralData` objects
from the spy-container "sessionName"
>>> objectDict = spy.load("sessionName.spy", dataclass=['analog', 'spectral'])
Load a specific :class:`syncopy.AnalogData` object from the above spy-container
>>> obj = spy.load("sessionName.spy/sessionName_someTag.analog")
This is equivalent to
>>> obj = spy.AnalogData("sessionName.spy/sessionName_someTag.analog")
If the "sessionName" spy-container only contains one object with the tag
"someTag", the above call is equivalent to
>>> obj = spy.load("sessionName.spy", tag="someTag")
If there are multiple objects of different types using the same tag "someTag",
the above call can be further narrowed down to only load the requested
:class:`syncopy.AnalogData` object
>>> obj = spy.load("sessionName.spy", tag="someTag", dataclass="analog")
See also
--------
syncopy.save : save syncopy object on disk
"""
# Ensure `filename` is either a valid .spy container or data file: if `filename`
# is a directory w/o '.spy' extension, append it
if not isinstance(filename, str):
raise SPYTypeError(filename, varname="filename", expected="str")
if len(os.path.splitext(os.path.abspath(
os.path.expanduser(filename)))[1]) == 0:
filename += FILE_EXT["dir"]
try:
fileInfo = filename_parser(filename)
except Exception as exc:
raise exc
if tag is not None:
if isinstance(tag, str):
tags = [tag]
else:
tags = tag
try:
array_parser(tags, varname="tag", ntype=str)
except Exception as exc:
raise exc
if fileInfo["filename"] is not None:
raise SPYError("Only containers can be loaded with `tag` keyword!")
for tk in range(len(tags)):
tags[tk] = "*" + tags[tk] + "*"
else:
tags = "*"
# If `dataclass` was provided, format it for our needs (e.g. 'spike' -> ['.spike'])
if dataclass is not None:
if isinstance(dataclass, str):
dataclass = [dataclass]
try:
array_parser(dataclass, varname="dataclass", ntype=str)
except Exception as exc:
raise exc
dataclass = [
"." + dclass if not dclass.startswith(".") else dclass
for dclass in dataclass
]
extensions = set(dataclass).intersection(FILE_EXT["data"])
if len(extensions) == 0:
lgl = "extension(s) '" + "or '".join(ext + "' "
for ext in FILE_EXT["data"])
raise SPYValueError(legal=lgl,
varname="dataclass",
actual=str(dataclass))
# Avoid any misunderstandings here...
if not isinstance(checksum, bool):
raise SPYTypeError(checksum, varname="checksum", expected="bool")
# Abuse `AnalogData.mode`-setter to vet `mode`
try:
spd.AnalogData().mode = mode
except Exception as exc:
raise exc
# If `filename` points to a spy container, `glob` what's inside, otherwise just load
if fileInfo["filename"] is None:
if dataclass is None:
extensions = FILE_EXT["data"]
container = os.path.join(fileInfo["folder"], fileInfo["container"])
fileList = []
for ext in extensions:
for tag in tags:
fileList.extend(glob(os.path.join(container, tag + ext)))
if len(fileList) == 0:
fsloc = os.path.join(container, "" + \
"or ".join(tag + " " for tag in tags) + \
"with extensions " + \
"or ".join(ext + " " for ext in extensions))
raise SPYIOError(fsloc, exists=False)
if len(fileList) == 1:
return _load(fileList[0], checksum, mode, out)
if out is not None:
msg = "When loading multiple objects, the `out` keyword is ignored"
SPYWarning(msg)
objectDict = {}
for fname in fileList:
obj = _load(fname, checksum, mode, None)
objectDict[os.path.basename(obj.filename)] = obj
return objectDict
else:
if dataclass is not None:
if os.path.splitext(fileInfo["filename"])[1] not in dataclass:
lgl = "extension '" + \
"or '".join(dclass + "' " for dclass in dataclass)
raise SPYValueError(legal=lgl,
varname="filename",
actual=fileInfo["filename"])
return _load(filename, checksum, mode, out)
def test_none(self):
with pytest.raises(SPYTypeError):
array_parser(None, varname="time")
def test_1d_lims(self):
# valid lims
array_parser(self.time, varname="time", lims=[0, 10])
# invalid lims
with pytest.raises(SPYValueError):
array_parser(self.time, varname="time", lims=[0, 5])
def test_1d_newaxis(self):
# appending singleton dimensions does not affect parsing
time = self.time[:, np.newaxis]
array_parser(time, varname="time", dims=(100, ))
array_parser(time, varname="time", dims=(None, ))
def test_2d_shape(self):
# make `self.time` a 2d-array
dummy = self.time.reshape(10, 10)
# valid shape
array_parser(dummy, varname="time", dims=(10, 10))
# valid shape, unkown size
array_parser(dummy, varname="time", dims=(10, None))
array_parser(dummy, varname="time", dims=(None, 10))
array_parser(dummy, varname="time", dims=(None, None))
# valid ndim
array_parser(dummy, varname="time", dims=2)
# invalid ndim
with pytest.raises(SPYValueError):
array_parser(dummy, varname="time", dims=3)
# invalid shape
with pytest.raises(SPYValueError):
array_parser(dummy, varname="time", dims=(100, 1))
with pytest.raises(SPYValueError):
array_parser(dummy, varname="time", dims=(None, ))
with pytest.raises(SPYValueError):
array_parser(dummy, varname="time", dims=(None, None, None))
