perda.analyzer.run_collection#

class perda.analyzer.run_collection.RunCollection(run_metadata)[source]#

Bases: object

A chronologically ordered collection of telemetry runs.

Holds only lightweight metadata. Logs are parsed into Analyzer instances lazily, one at a time, so that a collection spanning an entire season stays cheap to hold.

Notes

Construct via the factory functions in run_collection_factory (from_directory, from_paths) rather than calling __init__ directly.

Parameters:: run_metadata (list[RunMetadata])

compare_summary(cpp_name)[source]#

Summarize a variable’s statistics across every run in the collection.

Parameters:: cpp_name (str) – C++ name of the variable to summarize.
Returns:: Summary per run filename, for runs that contain the variable.
Return type:: dict[str, DataInstanceSummary]

Examples

>>> for filename, summary in col.compare_summary("bms.pack.voltage").items():
...     print(f"{filename}: {summary.max_value}")

property filenames: list[str]#: Filenames of every run, in chronological order. Loads nothing.

filter(predicate)[source]#

Select runs by their metadata, without loading any log.

Parameters:: predicate (Callable[[RunMetadata], bool]) – Returns True for runs to keep.
Returns:: New collection holding only the matching runs.
Return type:: RunCollection

Examples

>>> col.filter(lambda run: "endurance" in run.file_path.name)

filter_by_data(predicate)[source]#

Select runs by their contents, parsing one log at a time.

Unlike filter, this must read every log, so prefer narrowing the collection with filter or filter_by_date first.

Parameters:: predicate (Callable[[Analyzer], bool]) – Returns True for runs to keep. Receives the loaded Analyzer.
Returns:: New collection holding only the matching runs.
Return type:: RunCollection

Examples

>>> overvolted = col.filter_by_data(
...     lambda aly: (aly.data["ams.pack.voltage"].value_np > 10.0).any()
... )
>>> overvolted.filenames

filter_by_date(start_date=None, end_date=None)[source]#

Select runs recorded within a date range, inclusive on both ends.

Runs with no known date are excluded.

Parameters:

start_date (str | datetime | None, optional) – Earliest date to keep, as a datetime or ISO 8601 string. Default is None (no lower bound).
end_date (str | datetime | None, optional) – Latest date to keep, as a datetime or ISO 8601 string. Default is None (no upper bound).

Returns:

New collection holding only the matching runs.

Return type:

RunCollection

Examples

>>> col.filter_by_date("2026-06-01", "2026-06-30")

get_run_by_chronological_index(index)[source]#

Load the run at a position in the collection’s chronological ordering.

Parameters:: index (int) – Position in chronological order, not the order paths were supplied.
Returns:: Analyzer for that run. Repeated calls reuse the same instance.
Return type:: Analyzer

plot_comparison(cpp_name, max_points=None)[source]#

Overlay a variable from every run in the collection on a single plot.

Each run’s timestamps are shifted so that all runs start at t = 0.

Parameters:

cpp_name (str) – C++ name of the variable to compare.
max_points (int | None, optional) – Maximum data points to plot per run. Default is None (full fidelity).

Returns:

Plotly Figure with one trace per run that contains the variable.

Return type:

go.Figure

Examples

>>> col.plot_comparison("pcm.wheelSpeeds.frontLeft", max_points=20000).show()

pydantic model perda.analyzer.run_collection.RunMetadata[source]#

Bases: BaseModel

Cheaply-obtained index metadata for a single telemetry run.

Fields:

date (datetime.datetime | None)
file_path (pathlib.Path)

field file_path: Path [Required]#: Path to the log file

field date: datetime | None = None#: Recording date parsed from the header or file stats

perda.analyzer.run_collection#

This Page