neuralib.util.segments

neuralib.util.segments.is_sorted(a, strict=False)[source]

Check if array is sorted. [reference](https://stackoverflow.com/a/47004507)

Parameters:

a (ndarray) – Input array to check for sorted order.
strict (bool) – If True, checks for strictly increasing order. Otherwise, checks for non-decreasing order.

Returns:

Returns True if the input array is sorted based on the specified criteria, else False.

Return type:

bool

neuralib.util.segments.segment_mask(x, t=None, duration=None, merge=None)[source]

segmenting an array that the value is long enough.

Parameters:

x (np.ndarray) – (N,) int-cast-able array.
t (np.ndarray | None) – (N,) T-value array
duration (float | None) – T. the minimal True duration, duration smaller than value will set to even value. If using negative value, then duration larger than value will set to even value.
merge (float | None) –
1. the minima False duration, duration smaller than value will set to odd value.

Returns:

(N,) int array, where even value indicate False, odd value indicate True

Return type:

SegmentGroup

neuralib.util.segments.segment_epochs(x, t=None, duration=None, merge=None)[source]

Parameters:

x (np.ndarray) – (N,) int-cast-able array.
t (np.ndarray | None) – (N,) T-value array.
duration (float | None)
merge (float | None)

Returns:

(M, 2) T-value array. If t is None, return an N-value index array

Return type:

Segment

neuralib.util.segments.has_gap(y, gap)[source]

Parameters:

y (ndarray) – (N,) V-value array
gap (float) – V

Returns:

Return type:

bool

neuralib.util.segments.segment_gap(x, gap)[source]

segmenting an array that cut at the place which the difference of nearby value larger than gap.

min{|ai-aj|} > gap for any value ai from segment si, any value aj from segment sj, si != sj.

Parameters:

x (ndarray) – (N,) V-value array
gap (float) – V

Returns:

(N,) int-group array

Return type:

ndarray

neuralib.util.segments.as_segment(segs)[source]

Parameters:: segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – Input segment-like data that can be converted to a 2D array of floats.
Returns:: A numpy 2D array representation of the input segments.
Raises:: ValueError – If the input cannot be reshaped to a (N, 2) segment array.
Return type:: ndarray

neuralib.util.segments.segment_range(segs)[source]

change [(start, stop)] to [(start, duration)]

Parameters:: segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – segments. Array[float, [N, 2]]
Returns:: Array[int, [N, 2]]
Return type:: ndarray

neuralib.util.segments.segment_duration(segs)[source]

Parameters:: segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [N, 2]]
Returns:: T-value array. Array[int, N]
Return type:: ndarray

neuralib.util.segments.segment_at_least_duration(segs, duration)[source]

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [N, 2]]
duration (float) – T-value

Returns:

T-value segments. Array[float, [N, 2]]

Return type:

ndarray

neuralib.util.segments.segment_expand_duration(segs, duration)[source]

Parameters:

segs (SegmentLike) – T-value segments. Array[float, [N, 2]]
duration (float | tuple[float, float] | np.ndarray) – T-value scalar, tuple(prepend:T, append:T), or (N, 2?) array

Returns:

T-value segments. Array[float, [N, 2]]

Return type:

np.ndarray

neuralib.util.segments.segment_universe()[source]

Returns:: segment of [-inf, inf]
Return type:: ndarray

neuralib.util.segments.segment_flatten(segs, closed=True)[source]

sorting and remove overlapped segments.

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [N, 2]]
closed (bool) – Is segment a closed on right side?

Returns:

T-value segments. Array[float, [M, 2]]

Return type:

ndarray

neuralib.util.segments.segment_invert(segs)[source]

Parameters:: segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [N, 2]]
Returns:: T-value segments. Array[float, [N+1, 2]]
Return type:: ndarray

neuralib.util.segments.segment_intersection(a, b)[source]

Parameters:

a (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [A, 2]]
b (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [B, 2]]

Returns:

T-value segments. Array[float, [C, 2]]

Return type:

ndarray

neuralib.util.segments.segment_union(a, b, gap=0)[source]

Parameters:

a (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [A, 2]]
b (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [B, 2]]
gap (float) – T value

Returns:

T-value segments. Array[float, [C, 2]]

Return type:

ndarray

neuralib.util.segments.segment_diff(a, b)[source]

Parameters:

a (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [A, 2]]
b (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [B, 2]]

Returns:

T-value segments. Array[float, [C, 2]]

Return type:

ndarray

neuralib.util.segments.segment_contains(segs, t)[source]

whether t in the segments.

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – T-value segments. Array[float, [N, 2]]
t (ndarray) – T-value array. Array[float, R]

Returns:

bool array. Array[bool, R]

Return type:

ndarray

neuralib.util.segments.segment_index(segs, t)[source]

find the index of segs where t located

segs : ---[---]---[---)[---]---
ret  :  -1  0   -2  1    2   -4

The following code are true

I = segment_index(S, T)
for i in np.nonzero(I >= 0)[0]:
    assert S[I[i], 0] <= t[i] <= S[I[i], 1]

for i in np.nonzero(I < 0)[0]:
    if -I[t] - 1 == 0:
        assert t[i] < S[-I[t] - 1, 0]
    elif -I[t] - 1 == len(S):
        assert S[-I[i] - 2, 1] < t[i]
    else:
        assert S[-I[i] - 2, 1] < t[i] < S[-I[t] - 1, 0]

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (N, 2) T-value segments
t (ndarray) – (R,) T-value array

Returns:

(R,) N-value index array

Raises:

ValueError – segs has overlapped segments or not sorted

Return type:

ndarray

neuralib.util.segments.segment_overlap(segs, t, mode)[source]

mode == ‘in’

returns = [∃ s in S st. t ⊂ s | for t in T]

mode == ‘out’

returns = [∃ s in S st. s ⊂ t | for t in T]

mode == ‘overlap’

returns = [∃ s in S st. s ⋂ t ≠ ∅ | for t in T]

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (N, 2) T-value segments
t (ndarray) – (R, 2) T-value segments
mode (Literal['in', 'out', 'overlap'])

Returns:

(R,) bool array

Return type:

ndarray

neuralib.util.segments.segment_overlap_index(segs, t, mode)[source]

mode == ‘in’ (t is smaller)

return[t] = [∃ i in |S| st. t ⊂ s[i]] for t in T, otherwise [-1]

mode == ‘out’ (t is larger):

return[t] = [∃ i in |S| st. s[i] ⊂ t] for t in T, otherwise [-1]

mode == ‘overlap’

return[t] = [∃ i in |S| st. s[i] ⋂ t ≠ ∅] for t in T, otherwise [-1]

returns = [min(return[T]), max(return[T])]

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (N, 2) T-value segments
t (ndarray) – (R, 2) T-value segments
mode (Literal['in', 'out', 'overlap'])

Returns:

(2, R) N-value index array

Return type:

ndarray

neuralib.util.segments.segment_join(segs, gap=0)[source]

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (N, 2) T-value segments
gap (float) – T

Returns:

(N, 2) T-value segments

Return type:

ndarray

neuralib.util.segments.segment_join_index(segs, gap=0)[source]

Parameters:

segs (ndarray) – (N, 2) T-value sorted segments
gap (float) – T gap

Returns:

(N,) index grouping array

Return type:

ndarray

neuralib.util.segments.segment_map(f, segs, t, v=None)[source]

Parameters:

f (Callable[[ndarray], float]) – function ((N,) V-value array) -> R-value
segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (S, 2) T-value segment
t (ndarray) – (T,) T-value array
v (ndarray | None) – (T,) V-value array. If None, use t.

Returns:

(S,) R-value array

Return type:

ndarray

neuralib.util.segments.segment_group_map(f, group, v)[source]

Parameters:

f (Callable[[ndarray], float]) – function ((N,) V-value array) -> R-value
group (ndarray) –
1. S-group array. Only non-negative value will be considered.
v (ndarray) – (T,) T-value array

Returns:

(S,) R-value array

Return type:

ndarray

neuralib.util.segments.segment_sample(segs)[source]

Parameters:: segs (ndarray | tuple[float, float] | list[tuple[float, float]])
Return type:: _SegmentSampleHelper

neuralib.util.segments.segment_bins(segs, duration, interval=0, nbins=None)[source]

Divide segs into equal-size sub-segments with equal duration and equal interval.

returns = [(start := R[0] + (i+d)*j, start + d)] ⊆ segs, for j in [0, t)

Parameters:

segs (ndarray | tuple[float, float] | list[tuple[float, float]]) – (N, 2) T-value segment
duration (float) – T value
interval (float) – T value
nbins (int | None) – number of bins

Returns:

(nbins, 2) T-value segment

Return type:

ndarray

neuralib.util.segments.shuffle_time(t, method, segs=None, duration=inf, circular=True)[source]

Shuffle t by remapping function method for t in segs.

Parameters:

t (ndarray) – (N,) T-value array
method (Callable[[ndarray], ndarray]) – time remapping function with signature ((K,) T-value array) -> (K,) T-value array
segs (ndarray | None) – (S, 2) segment, only shift time in the segments.
duration (float) – The maximal T value
circular – keep total event number. If epochs is given, keep total event number in epochs.

Returns:

(N’,) T-value array

neuralib.util.segments.shuffle_time_uniform(t, segs=None, *, duration=inf, circular=True)[source]

Shuffle t for t in segs.

Parameters:

t (ndarray) – (N,) T-value array
segs (ndarray | None) – (S, 2) segment, only shift time in the segments.
duration (float) – The maximal T value
circular – keep total event number. If epochs is given, keep total event number in epochs.

Returns:

(N’,) T-value array

Return type:

ndarray

neuralib.util.segments.shuffle_time_normal(t, loc=0, scale=1, segs=None, *, duration=inf, circular=True)[source]

Shuffle t with add a value from a normal distribution for t in segs.

Parameters:

t (ndarray) – (N,) T-value array
loc (float) – mean of the normal distribution
scale (float) – std of the normal distribution
segs (ndarray | None) – (S, 2) segment, only shift time in the segments.
duration (float) – The maximal T value
circular – keep total event number. If epochs is given, keep total event number in epochs.

Returns:

(N’,) T-value array

Return type:

ndarray

neuralib.util.segments.shift_time(t, shift, segs=None, *, duration=inf, circular=True)[source]

Shift t with a shift value for t in segs.

Parameters:

t (ndarray) – (N,) T-value array
shift (float) – shift T value, positive value.
segs (ndarray | None) – (S, 2) segment, only shift time in the segments.
duration (float) – The maximal T value for wrapping when circular
circular – keep total event number. If epochs is given, keep total event number in epochs.

Returns:

(N’,) T-value array

neuralib.util.segments.foreach_map(v, f, indices_or_sections)[source]

Map function f into vector v in given sections.

Parameters:

v (ndarray) – Input 1d array
f (Callable[[ndarray], ndarray]) – Function to apply to each segment
indices_or_sections (ndarray) – If indices_or_sections is an integer, N, the array will be divided into N equal arrays along axis. If such a split is not possible, an error is raised

Returns:

Return type:

ndarray

neuralib.util.segments.grouped_iter(v, n)[source]

Groups elements from the input iterable v into tuples of length n

>>> list(grouped_iter([1, 2, 3, 4, 5, 6], 2))
[(1, 2), (3, 4), (5, 6)]

Parameters:

v (ArrayLike | Iterable) – input iterable to be grouped.
n (int) – number of elements per group

Returns:

An iterator over tuples of length n

Return type:

zip