perda.analyzer.csv#

pydantic model perda.analyzer.csv.ParsedDataFrame[source]#

Bases: BaseModel

Config:

  • arbitrary_types_allowed: bool = True

Fields:
field data_frame: pl.DataFrame [Required]#

Data sorted by variable ID then timestamp

field parsing_errors: int [Required]#

Number of rows dropped as unparseable

pydantic model perda.analyzer.csv.ParsedVariableLine[source]#

Bases: BaseModel

Fields:
field cpp_name: str [Required]#

C++ name of the variable

field description: str [Required]#

Human readable description of the variable

field var_id: int [Required]#

Numeric ID the data rows refer to

pydantic model perda.analyzer.csv.VariableMappings[source]#

Bases: BaseModel

Fields:
field id_to_cpp_name: dict[int, str] [Required]#

Mapping from variable ID to variable name

field id_to_descript: dict[int, str] [Required]#

Mapping from variable ID to variable description

field skip_rows: int [Required]#

Number of leading rows before the numeric data section

perda.analyzer.csv.build_data_instances(mappings, data_frame, verbose=1)[source]#

Slice the sorted data into one DataInstance per variable.

Parameters:

  • mappings (VariableMappings) – Variable ID lookup tables.

  • data_frame (pl.DataFrame) – Data sorted by variable ID then timestamp.

  • verbose (int, optional) – Verbosity level. 0 for no output, 2 for progress bars. Default is 1.

Returns:

Mapping from variable ID to its DataInstance.

Return type:

dict[int, DataInstance]

Notes

Slicing the shared arrays yields zero-copy numpy views rather than duplicating data. Variables declared in the mapping lines but absent from the data get empty arrays.

perda.analyzer.csv.parse_csv(file_path, ts_offset=0, parsing_errors_limit=100, verbose=1, build_search_index=False)[source]#

Parse CSV file and return SingleRunData model.

Parameters:

  • file_path (str) – Path to the CSV file to parse.

  • ts_offset (int, optional) – Timestamp offset applied to all data points. Default is 0.

  • parsing_errors_limit (int, optional) – Maximum number of parsing errors before stopping. -1 for no limit. Default is 100.

  • verbose (int, optional) – Verbosity level. 0 for no output, 1 for basic output, 2 for detailed output. Default is 1.

  • build_search_index (bool, optional) – Whether to vectorize variable descriptions for semantic search. Requires the semantic extra and adds noticeable time to parsing. Default is False.

Returns:

Parsed data structure containing all variables.

Return type:

SingleRunData

Notes

The timestamp unit is auto-detected from the header suffix: “v2.0” means microseconds, anything else means milliseconds.

perda.analyzer.csv.parse_header_creation_time(header_line)[source]#

Extract the recording date from a log file’s first line.

Parameters:

header_line (str) – First line of the log file, e.g. "PER Log: Thu Jun 11 17:06:37 2026 v2.0".

Returns:

Parsed recording date, or None if the header carries no recognizable date.

Return type:

datetime | None

perda.analyzer.csv.parse_variable_id_mappings(file_handle, verbose=1)[source]#

Read the variable ID and name mapping lines that follow the file header.

Parameters:

  • file_handle (TextIO) – Open log file positioned just after the header line.

  • verbose (int, optional) – Verbosity level. 0 for no output, 1 for warnings, 2 for progress bars. Default is 1.

Returns:

Parsed lookup tables and the row offset where numeric data begins.

Return type:

VariableMappings

perda.analyzer.csv.parse_variable_mapping_line(line)[source]#

Parse one variable declaration line into its three fields.

Parameters:

line (str) – Declaration line, e.g. "Value pack voltage (ams.pack.voltage): 1".

Returns:

The variable’s C++ name, description, and ID.

Return type:

ParsedVariableLine

perda.analyzer.csv.read_and_sort_data(file_path, skip_rows, ts_offset=0, parsing_errors_limit=100, verbose=1)[source]#

Read the numeric data section and sort it by variable ID then timestamp.

Parameters:

  • file_path (str) – Path to the CSV file to read.

  • skip_rows (int) – Number of leading rows to skip before the numeric data.

  • ts_offset (int, optional) – Timestamp offset applied to all data points. Default is 0.

  • parsing_errors_limit (int, optional) – Maximum number of malformed rows tolerated. -1 for no limit. Default is 100.

  • verbose (int, optional) – Verbosity level. 0 for no output, 1 or higher for status. Default is 1.

Returns:

Sorted data and the count of malformed rows dropped.

Return type:

ParsedDataFrame