nems.epoch module
- nems.epoch.epoch_union(a, b)[source]
Compute the union of the epochs.
- Parameters
a (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurances of a.
b (2D array of (N x 2)) – The first column is the start time and second column is the end time. N is the number of occurances of b.
- Returns
union – The first column is the start time and second column is the end time. O is the number of occurances of the union of a and b. Note that O <= M + N.
- Return type
2D array of (O x 2)
Example
a: [ ] [ ] [ ] b: [ ] [ ] [] [ ] result: [ ] [ ] [] [ ]
- nems.epoch.epoch_difference(a, b)[source]
Compute the difference of the epochs. All regions in a which overlap with b will be removed.
- Parameters
a (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurances of a.
b (2D array of (N x 2)) – The first column is the start time and second column is the end time. N is the number of occurances of b.
- Returns
difference – The first column is the start time and second column is the end time. O is the number of occurances of the difference of a and b.
- Return type
2D array of (O x 2)
Example
a: [ ] [ ] [ ] b: [ ] [ ] [] [ ] result: [] [ ] [ ] []
- nems.epoch.epoch_intersection_full(a, b)[source]
returns all epoch times a that are fully spanned by epoch times in b
- nems.epoch.epoch_intersection(a, b, precision=6)[source]
Compute the intersection of the epochs. Only regions in a which overlap with b will be kept.
- Parameters
a (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurances of a.
b (2D array of (N x 2)) – The first column is the start time and second column is the end time. N is the number of occurances of b.
precision (int) – Number of decimal places to use for equality test.
- Returns
intersection – The first column is the start time and second column is the end time. O is the number of occurances of the difference of a and b.
- Return type
2D array of (O x 2)
Example
a: [ ] [ ] [ ] b: [ ] [ ] [] [ ] result: [ ] [ ] []
- nems.epoch._epoch_contains_mask(a, b)[source]
3d array. 1st dimension is index in a. Second dimension is index in b. Third dimension is whether start (index 0) or end (index 1) in b falls within the corresponding epoch in a.
- nems.epoch.epoch_contains(a, b, mode)[source]
Tests whether an occurence of a contains an occurence of b.
- Parameters
a (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurances of a.
b (2D array of (N x 2)) – The first column is the start time and second column is the end time. N is the number of occurances of b.
mode ({'start', 'end', 'both', 'any'}) – Test to perform. - ‘start’ requires only the start of b to be contained in a - ‘end’ requires only the end of b to be contained in a - ‘both’ requires both start and end in b to be contained in a - ‘any’ is True anywhere b partially or completely overlaps with a
- Returns
mask – Boolean mask indicating whether the corresponding entry in a meets the test criteria.
- Return type
1D array of len(a)
- nems.epoch.epoch_contained(a, b)[source]
Tests whether an occurrence of a is fully contained inside b
- nems.epoch.adjust_epoch_bounds(a, pre=0, post=0)[source]
- Parameters
a (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurances of a.
pre (scalar) – Value to add to start time of epoch
post (scalar) – Value to add to end time of epoch
Example
>>> epochs = np.array([[0.5, 1], [2.5, 3]]) >>> adjust_epoch_bounds(epochs, -0.5) [[0, 1], [2, 3]]
>>> adjust_epoch_bounds(epochs, 0.5, 1) [[1, 2], [3, 4]]
- nems.epoch.verify_epoch_integrity(epoch)[source]
- There are several kinds of pathological epochs:
Epochs with NaN for a start time. (It is OK if end is NaN.)
Epochs where start comes after the end
Epochs which are completely identical to existing triplets (i.e. redundant duplicates)
This function searches for those and throws exceptions about them.
- nems.epoch.epoch_names_matching(epochs, regex_str)[source]
Returns a list of epoch names that regex match the regex_str.
- nems.epoch.epoch_occurrences(epochs, regex=None)[source]
Returns a dataframe of the number of occurrences of each epoch. Optionally, provide regex to match only certain epoch names.
- nems.epoch.group_epochs_by_occurrence_counts(epochs, regex=None)[source]
Returns a dictionary mapping the number of occurrences to a list of epoch names. This is essentially the inverse mapping of epoch_occurrences().
- nems.epoch.find_common_epochs(epochs, epoch_name, d=12)[source]
Finds all epochs contained by epoch_name that are common to all occurences of epoch_name. An epoch is considered “common” to all occurences if the name matches and the start and end times, relative to the start epoch_name, are the same to the number of decimal places indicated.
- Parameters
epochs (dataframe with 'name', 'start', 'end') – Epochs to filter through
epoch_name (str) – Name of epoch to use
d (int) – Number of decimal places to round start and end to. This is important when comparing start and end times of different epochs due to floating-point errors.
Result –
------ –
common_epochs (dataframe with 'name', 'start', 'end') – Epochs common to all occurances of epoch_name. The start and end times will reflect the time relative to the onset of the epoch.
- nems.epoch.group_epochs_by_parent(epochs, epoch_name_regex)[source]
Iterate through subgroups of the epoches contained by a parent epoch
- Parameters
epochs (dataframe with 'name', 'start', 'end') – Epochs to filter through
epoch_name_regex (str) – Regular expression that will be used to identify parent epochs to iterate through.
- Returns
Iterator yielding a tuple of (parent epoch name, dataframe containing subset
of epochs contained by parent epoch).
Example
- nems.epoch.add_epoch(df, regex_a, regex_b, new_name=None, operation='intersection')[source]
Add a new epoch based on an operation of two epoch sets, A and B
- Parameters
df (dataframe) – Epoch dataframe with three columns (name, start, end)
regex_a (string) – Regular expression to match against for A
regex_b (string) – Regular expression to match against for B
new_name ({None, string}) – Name to assign to result of operation. If None, name is the concatenation of regex_a and regex_b.
operation ({'intersection', 'difference', 'contained'}) – Operation to perform. See docstring for epoch_{operation} for details.
- nems.epoch.append_epoch(epochs, epoch_name, epoch)[source]
Add epoch to the internal epochs dataframe
- Parameters
epochs (DataFrame or None) – existing epochs or None to create new epochs
epoch_name (string) – Name of epoch
epoch (2D array of (M x 2)) – The first column is the start time and second column is the end time. M is the number of occurrences of the epoch.