cursus.processing.temporal

Temporal Processing Module

This module provides atomic processors for temporal sequence processing, extracted from Temporal Self-Attention (TSA) model requirements.

class TimeDeltaProcessor(reference_strategy='most_recent', reference_field='orderDate', output_field='time_delta', time_unit='seconds', max_delta=10000000)

Bases: Processor

Computes time deltas relative to a reference point.

Extracted from TSA preprocess_functions.py: - seq_num_mtx[:, -2] = seq_num_mtx[-1, -2] - seq_num_mtx[:, -2]

Parameters:

• reference_strategy (str) – ‘most_recent’, ‘first’, ‘custom’

• reference_field (str) – Field name containing reference timestamp

• output_field (str) – Field name for computed deltas

• time_unit (str) – ‘seconds’, ‘minutes’, ‘hours’, ‘days’

• max_delta (float | None) – Maximum allowed delta (for outlier handling)

fit(data)

Learn reference time from data

get_config()

Return processor configuration

process(input_data)

Compute time deltas

class SequencePaddingProcessor(target_length=51, padding_strategy='pre', truncation_strategy='post', padding_value=0, axis=0)

Bases: Processor

Pads or truncates sequences to a target length.

Extracted from TSA preprocess_functions.py: - seq_cat_mtx = np.pad(seq_cat_mtx, [(seq_len - 1 - len(seq_cat_vars_mtx), 0), (0, 0)])

Parameters:

• target_length (int) – Desired sequence length

• padding_strategy (str) – ‘pre’, ‘post’

• truncation_strategy (str) – ‘pre’, ‘post’

• padding_value (int | float) – Value to use for padding

• axis (int) – Axis along which to pad/truncate

fit(data)

No fitting required for padding

get_config()

Return processor configuration

process(input_data)

Apply sequence padding/truncation

class SequenceOrderingProcessor(sort_field='orderDate', sort_order='ascending', validate_order=True)

Bases: Processor

Orders sequences by timestamp or other criteria.

Extracted from TSA preprocess_functions.py sequence validation logic.

Parameters:

• sort_field (str) – Field to sort by

• sort_order (str) – ‘ascending’, ‘descending’

• validate_order (bool) – Whether to validate ordering consistency

fit(data)

No fitting required for ordering

get_config()

Return processor configuration

process(input_data)

Apply sequence ordering

class TemporalMaskProcessor(padding_value=0, output_format='boolean', mask_value=True)

Bases: Processor

Generates attention masks for padded sequences.

Derived from TSA attention masking requirements.

Parameters:

• mask_value (int | float | bool) – Value indicating valid positions

• padding_value (int | float) – Value indicating padded positions

• output_format (str) – ‘boolean’, ‘float’, ‘int’

combine_masks(*masks)

Combine multiple masks using logical AND.

Parameters:

*masks (ndarray) – Variable number of mask arrays

Returns:

Combined mask

Return type:

ndarray

create_causal_mask(sequence_length)

Create a causal (lower triangular) attention mask.

Parameters:

sequence_length (int) – Length of the sequence

Returns:

Causal attention mask

Return type:

ndarray

create_padding_mask(sequence_lengths, max_length)

Create padding masks for batch of sequences with different lengths.

Parameters:

• sequence_lengths (List[int]) – List of actual sequence lengths

• max_length (int) – Maximum sequence length (padded length)

Returns:

Batch of padding masks

Return type:

ndarray

fit(data)

No fitting required for masking

get_config()

Return processor configuration

process(input_data)

Generate attention mask

Modules

sequence_ordering_processor	Sequence Ordering Processor for Temporal Self-Attention Model
sequence_padding_processor	Sequence Padding Processor for Temporal Self-Attention Model
temporal_mask_processor	Temporal Mask Processor for Temporal Self-Attention Model
time_delta_processor	Time Delta Processor for Temporal Self-Attention Model