nems.epoch module

nems.epoch.check_result(f)[source]
nems.epoch.remove_overlap(a)[source]

Remove overlapping occurences by taking the first occurence

nems.epoch.merge_epoch(a)[source]
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:
  1. Epochs with NaN for a start time. (It is OK if end is NaN.)

  2. Epochs where start comes after the end

  3. 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.