(V) TL: Transformation Layer

Theoretical Framework

Main Concepts

The main theoretical concepts building the foundation of the Transformation Layer are:

• transforming sequence represented in the code as class TransformingSequence.
• TPSF represented in the code as class Tpsf.
• text history which is a list of objects of type Tpsf.

See Key Terms and Their Definitions for detailed definitions of the terms transforming sequence, TPSF, and text history.

Layers Projection

The Sentence Layer and Burst Layer are projected on the Transformation Layer. As a result the transforming sequence and the TPSF are enriched with further information.

See SL2TL Projection for more details on the projection of Sentence Layer on the Transformation Layer and BL2TL Projection for more details on the projection of the Burst Layer on the Transformation Layer.

Classes

class TSBuilder (immutable)

The class TSBuilder stores basic data on the transformation retrieved directly from a keystroke log file required for generating objects of type TransformingSequence.

Both a TSBuilder and TransformingSequence can have one of the following labels:

• append
• insertion
• deletion
• midletion
• replacement
• pasting
• navigation

All possible TSLabels are listed in a class TSLabels in the module names.py.

Fields:

• text: Text content of the transforming sequence.
• label: Edit operation type (append, insertion, etc.).
• startpos: Start position in the text.
• endpos: End position in the text (None if not applicable).
• starttime: Timestamp when the first character of the TS was produced.
• endtime: Timestamp when the last event character of the TS was produced.
• pauses: List of preceding pauses of each character of the TS.
• following_pause: Pause following the last character of the TS.
• rplcmt_textlen: Length of text replaced during replacement operation.

Public Methods:

to_transforming_sequence(
        self,
        removed_text: str,
        sscope: str,
        segments: list[Segment],
        replaced_segments: list[Segment],
        settings: Settings
) -> TransformingSequence

Assembles and returns a fully populated TransformingSequence.

__str__() -> str

Returns a formatted string representation of the TSBuilder.

to_dict() -> TSDict

Converts the TSBuilder to a dictionary representation.

TypedDict: TSBuilderDict

A dictionary representation of a TSBuilder instance.

class TSBuilderDict(TypedDict):
    text: str
    label: str
    startpos: int
    endpos: int | None
    starttime: float | None
    endtime: float | None
    pauses: list[float]
    following_pause: float

class TransformingSequence (immutable)

Fields:

• text: Text content of the TS.
• replaced_text: Original text replaced during replacement operation.
• label: Edit operation label.
• startpos, endpos: Start and end positions in the text.
• starttime, endtime: Timestamp when the first event started and ended.
• pauses: List of preceding pauses of each character of the TS.
• following_pause: Pause following the last character of the TS.
• bursts: List of bursts (result of Burst Layer projection).
• bscope: Burst-level scope of the TS (result of Burst Layer projection).
• segments: List of sentence segments (result of Sentence Layer projection).
• replaced_segments: Sentence segments replaced during replacement operation (result of Sentence Layer projection).
• sscope: Sentence-level scope of the TS.
• relevance: Boolean flag indicating whether the TS is considered relevant.

Public Methods:

__str__() -> str

Returns a formatted string representation of the TransformingSequence.

to_dict() -> TSDict

Converts the TransformingSequence to a dictionary representation.

TypedDict: TSDict

A dictionary representation of a TransformingSequence instance.

class TSDict(TypedDict):
    text: str
    replaced_text: str
    label: str
    startpos: int
    endpos: int
    starttime: float
    endtime: float
    pauses: list[float]
    following_pause: float
    bursts: list[BurstDict]
    bscope: str
    segments: list[SegmentDict]
    replaced_segments: list[SegmentDict]
    sscope: str
    relevance: bool

class TsBuilderFactory

TsBuilderFactory is a class for constructing TSBuilder (Transforming Sequence Builder) instances.

Public Methods:

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

Builds a fully populated TSBuilder object for each action group and appends it to the result list.

Description:

• Combines all editing actions grouped by type to retrieve the TS text.
• Determines the start and end positions.
• Retrieves start and end timestamps as well as pauses (information available only for keyboard events).
• Adjusts positions for deletions, midletions, and replacements.
• Returns a list of fully populated TSBuilder objects for further processing.

class Tpsf

The Tpsf class represents a TPSF. It encapsulates a single version of text along with its associated TS, text units, and information about its relevance.

Fields:

• id (int): Unique identifier for this revision.
• text (str): The resulting text after this transformation.
• ts (TransformingSequence): The transforming sequence for this transformation.
• prev_tpsf (Optional[Tpsf]): Reference to the previous TPSF (if any).
• textunits (list[Textunit]): Text units building the current text version.
• deleted_textunits (list[Textunit]): List of deleted text units.
• relevance (bool): Indicates whether this TPSF is considered relevant.
• irrelevant_tss_aggregated (tuple[TransformingSequence, ...]): Aggregated transforming sequences marked as irrelevant.
• final (bool, default: False): Whether this is the final transformation operation.

Public Methods:

__str__(self) -> str

Returns a formatted string representation of the TPSF.

to_dict(self) -> TpsfDict

Serializes the TPSF into a TpsfDict structure.

TypedDict: TpsfDict

A serializable dictionary representation of a Tpsf instance, designed for exporting TPSF data.

class TpsfDict(TypedDict):
    id: int
    text: str
    prev_tpsf_text: str | None
    ts: TSDict
    tus: list[TextUnitDict]
    deleted_tus: list[TextUnitDict]
    prev_tpsf_tus: list[TextUnitDict]
    relevance: bool

class TpsfFactory

The class TpsfFactory processes a list of transforming sequences to generate a sequence of TPSF objects, each representing a distinct version of text.

It recognizes the following TS types:

• Text production: append, insertion, pasting
• Text deletion: deletion, midletion
• Text replacement: replacement (deletes and inserts in one operation)
• Navigation: navigation (no text change, filtered out during TPSF generation)

Public Methods:

run(
   tss: list[TransformingSequence], 
   settings: Settings
) -> list[Tpsf]

Generates a list of Tpsf objects from a list of transforming sequences. The list of Tpsf objects builds the text history.

Processing Steps:

• Filters out non-relevant TS types.
• Reconstructs text version after each transformation.
• Retrieves text units and sentence-related scope using SenTransProjector.
• Generates a fully populated TransformingSequence object.
• Determines TPSF relevance.
• If the given TPSF is relevant, it aggregates transforming sequences from preceding TPSFs classified as irrelevant.
• Produces a fully populated Tpsf object.

Public Methods:

filter_tpsfs(
   tpsfs: list[Tpsf]
) -> list[Tpsf]

Filters a list of TPSFs, keeping only those marked as relevant.