(X) Preprocessing

Theoretical Framework

The preprocessing step is not reflected in the theoretical framework. It merely consists in preparing the keystroke logs for proper downstream processing.

Classes

class EventFactory

The EventFactory class is responsible for parsing keystroke log files (in either scriptlog_idfx, inputlog_idfx, or protext_csv formats) and transforming their events into strongly-typed Event objects. These events are used for generating actions, transforming sequences, and managing text history within the processing pipeline.

Supported Event Types:

• NavigationKeyboardEvent
• BDeletionKeyboardEvent (Backspace deletions)
• DDeletionKeyboardEvent (Delete key deletions)
• ProductionKeyboardEvent (Character insertions/productions)
• ReplacementEvent (Sequence replacement)

class BaseEvent

The BaseEvent class serves as the foundational class for representing keystroke events within the event processing pipeline. Each event stores its content, positional information, and sequential relationships to adjacent events. Subclasses extend this base class to represent specific event types such as keyboard production, deletion, navigation, and replacements.

This class also supports integration with an Action object (through to_action()), allowing events to be transformed into higher-level actions for downstream processing.

Constructor Parameters:

• content (str): The textual content associated with the event.
• startpos (int): The starting position of the event in the text.
• endpos (int | None): The ending position of the event in the text (may be None for events without a defined end).

Attributes:

• content: str – The text content related to the event.
• startpos: int – Index of the first character affected by the event.
• endpos: int | None – Index of the last character affected by the event (can be None).
• prev_evnt: BaseEvent | None – Reference to the preceding event (if available).
• next_evnt: BaseEvent | None – Reference to the succeeding event (if available).

class KeyboardEvent

The KeyboardEvent and its subclasses represent keyboard-related keystroke events. These events describe:

• Character production (typing or pasting)
• Character deletion (via Backspace or Delete)
• Cursor navigation without text modification

Each event stores timing, key information, and context for later conversion into high-level Action objects (Append, Insertion, Deletion, Midletion, Navigation, or Pasting).

Constructor Parameters:

• content (str): The character(s) associated with the event.
• startpos (int): Cursor position before the event.
• endpos (int | None): Cursor position after the event.
• keyname (str): Key identifier (e.g., VK_B, VK_BACK).
• starttime (float): Key press start time (in seconds).
• endtime (float): Key release time (in seconds).
• textlen (int): Document length at the time of the event.
• settings (Settings): Application settings (used for mapping corrections).
• char_number_diff (int): Format-specific correction factor for position vs. document length.

class ActionFactory

A class responsible for generating Action objects corresponding to each BaseEvent. Each event maps to at most one action, and the resulting list has the same logical length as the event sequence (excluding events that produce no action).

Constructor:

This class does not require instantiation—its methods are static.

Methods:

run(evnts: Collection[BaseEvent]) -> list[Action]

Generates actions from a collection of BaseEvent objects.

Parameters:

• evnts (Collection[BaseEvent]): A collection (e.g., list) of events to process.

Returns:

• list[Action]: A list of generated Action objects. Events without corresponding actions are skipped.

class ActionAggregator

Aggregates Action objects into groups based on action type and cursor position consecutiveness. This grouping is essential for identifying transformation sequences (e.g., continuous typing, bulk deletions).

Aggregation Rules

Aggregation is performed for the following action types:

• Append: Consecutive positions (e.g., startpos, startpos+1, startpos+2).
• Insertion: Same rule as Append.
• Deletion (Backspace): Consecutive positions in reverse (e.g., startpos, startpos-1, startpos-2).
• Midletion: Same as Backspace deletion.
• Deletion (Delete key): Aggregates when cursor position remains the same and text length decreases.

Aggregation is not performed for:

• Replacement
• Pasting
• Navigation

Constructor:

This class does not require instantiation—its methods are static.

Methods:

run(acts: list[Action]) -> dict[str, list[Action]]

Aggregates actions based on the rules above.

Parameters:

• acts (list[Action]): A list of actions to aggregate.

Returns:

• dict[str, list[Action]]: A dictionary where keys are group identifiers (_) and values are lists of aggregated Action objects.

class Action

The Action class and its subclasses represent actions derived from keystroke events during text production. Each action captures a specific type of editing operation such as typing, deleting, navigating, or pasting.

There are 7 primary types of actions:

• Append: Producing a character at the end of the text (subclass of KeyboardAction).
• Insertion: Inserting a character in the middle of the text (subclass of KeyboardAction).
• Navigation: Moving the cursor without producing or deleting characters (subclass of KeyboardAction).
• Deletion: Deleting a character at the end of the text (subclass of KeyboardAction).
• Midletion: Deleting a character from the middle of the text (subclass of KeyboardAction).
• Replacement: Replacing a marked text segment with a new character or empty sequence.
• Pasting: Pasting a text segment.

Constructor Parameters for class Action:

• content (str): The character(s) associated with the action.
• startpos (int): The position where the action begins.
• endpos (int | None): The position where the action ends.

Constructor Parameters for class KeyboardAction:

• class Action constructor parameters
• keyname (str): Name of the key that triggered the action.
• starttime (float): Time when the key press started (in seconds).
• endtime (float): Time when the key press ended (in seconds).
• preceding_pause (float | None): Time elapsed since the previous keystroke.
• textlen (int): Length of the text at the time of the action.

Constructor Parameters for class Replacement:

• class Action constructor parameters
• rplcmt_endpos (int): End position of the replaced segment.
• rplcmt_textlen (int): Text length before replacement.

Constructor Parameters for class Pasting:

• class Action constructor parameters