time_series_common
time_series_common
¶
Shared component base and sequence handling for time-series evaluation metrics.
Every time-series metric resolves the same grouping column, selects the same numeric value columns, walks the same shared groups in the same order, and renders as one card in the report's Time-Series Metrics panel. Keeping that logic here means a fix applies to every metric at once.
Classes:
| Name | Description |
|---|---|
TimeSeriesComponent |
Base for components shown in the report's Time-Series Metrics panel. |
Functions:
| Name | Description |
|---|---|
excluded_columns_note |
Return a report note naming numeric training columns left out of evaluation. |
resolve_group_column |
Return the grouping column evaluation should use. |
select_value_columns |
Select numeric value columns eligible for evaluation. |
invalid_value_columns |
Return actionable validation failures for explicit value columns. |
shared_groups |
Find a deterministic, bounded set of groups shared by both datasets. |
group_sort_key |
Return a stable ordering key for heterogeneous group values. |
group_frame |
Return one sequence in deterministic timestamp order. |
summaries |
Average profile similarities by a diagnostic key. |
Attributes:
| Name | Type | Description |
|---|---|---|
FigureSpec |
Chart title, figure, whether it gets the column select, and its tooltip key. |
FigureSpec = tuple[str, go.Figure, bool, str]
module-attribute
¶
Chart title, figure, whether it gets the column select, and its tooltip key.
TimeSeriesComponent
pydantic-model
¶
Bases: Component
Base for components shown in the report's Time-Series Metrics panel.
The report runs every component in TIME_SERIES_COMPONENTS and renders
each as a metric card from the class attributes below. Subclasses extend
jinja_context with their figures, built with figure_rows.
Attributes:
| Name | Type | Description |
|---|---|---|
card_id |
str
|
HTML id of the metric card. |
description |
str
|
One-line description shown on the card. |
tooltip_key |
str
|
Key of the card's info tooltip in |
template |
str
|
Jinja template rendered inside the card. |
score_colored_traces |
bool
|
Whether chart traces are colored by score, so the report keeps their colors instead of applying dataset colors. |
Fields:
-
name(str) -
score(EvaluationScore) -
details(dict[str, Any])
details
pydantic-field
¶
Metric-specific diagnostic details.
jinja_context
cached
property
¶
Return score, details, and card attributes for report rendering.
figure_rows(figures)
staticmethod
¶
Convert figure specs into the rows the chart grid template renders.
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
excluded_columns_note(excluded)
¶
Return a report note naming numeric training columns left out of evaluation.
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
resolve_group_column(datasets, config)
¶
Return the grouping column evaluation should use.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
datasets
|
EvaluationDatasets
|
Training and synthetic datasets to compare. |
required |
config
|
SafeSynthesizerParameters | None
|
Optional top-level configuration naming the group column. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The group column, or |
str | None
|
note when a configured group column is missing from a dataset. |
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
select_value_columns(datasets, value_columns, timestamp_column, group_column, label)
¶
Select numeric value columns eligible for evaluation.
Explicit value_columns retain their configured order. Automatic
selection is sorted for deterministic output and follows the training
field types, so a synthetic column that collapsed to a constant or a few
integers is still evaluated (and penalized) instead of silently dropping
out. Timestamp and grouping columns are excluded even when their storage
dtype is numeric.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
datasets
|
EvaluationDatasets
|
Training and synthetic datasets with inferred field types. |
required |
value_columns
|
list[str] | None
|
Explicitly configured columns, or |
required |
timestamp_column
|
str | None
|
Column used only to order observations. |
required |
group_column
|
str | None
|
Column used only to separate sequences. |
required |
label
|
str
|
Metric name used in the validation error, such as
|
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
Selected column names, an optional validation error, and the numeric |
str | None
|
training columns left out because synthetic data lacks them or stores |
list[str]
|
them as non-numeric values. |
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
invalid_value_columns(datasets, columns, timestamp_column, group_column)
¶
Return actionable validation failures for explicit value columns.
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
shared_groups(training, synthetic, group_column, max_groups, seed)
¶
Find a deterministic, bounded set of groups shared by both datasets.
A None sentinel represents one global sequence when grouping is not
configured. Group labels present in only one dataset are returned for
diagnostics but do not contribute to the score.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
training
|
DataFrame
|
Training records containing candidate group labels. |
required |
synthetic
|
DataFrame
|
Synthetic records containing candidate group labels. |
required |
group_column
|
str | None
|
Optional column that identifies independent sequences. |
required |
max_groups
|
int
|
Maximum number of shared groups to evaluate. |
required |
seed
|
int
|
Seed for the reproducible sample taken above |
required |
Returns:
| Type | Description |
|---|---|
list[Any]
|
Shared group keys, training-only labels, synthetic-only labels, |
list[str]
|
and the total number of shared groups before limiting. |
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
group_sort_key(value)
¶
Return a stable ordering key for heterogeneous group values.
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
group_frame(df, group_column, group_value, timestamp_column)
¶
Return one sequence in deterministic timestamp order.
mergesort preserves input order for equal timestamps, which makes
repeated runs stable without inventing a secondary ordering key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
df
|
DataFrame
|
Dataset containing one or more sequences. |
required |
group_column
|
str | None
|
Optional sequence identifier column. |
required |
group_value
|
Any
|
Group to select, or |
required |
timestamp_column
|
str | None
|
Optional column used to order the selected rows. |
required |
Returns:
| Type | Description |
|---|---|
DataFrame
|
A filtered and time-ordered DataFrame view or copy. |
Source code in src/nemo_safe_synthesizer/evaluation/components/time_series_common.py
summaries(profiles, key)
¶
Average profile similarities by a diagnostic key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
profiles
|
list[dict[str, Any]]
|
Successful group-and-column comparison details. |
required |
key
|
str
|
Detail key to group by, such as |
required |
Returns:
| Type | Description |
|---|---|
list[dict[str, Any]]
|
Deterministically ordered summaries with similarity and count. |