docs: time series demo notebook

[seayang-nv]

Summary

Added time series demo notebook

Pre-Review Checklist

Ensure that the following pass:

• make format && make check or via prek validation.
• make test passes locally
• make test-e2e passes locally
• make test-ci-container passes locally (recommended)
• GPU CI status check passes -- comment /sync on this PR to trigger a run (auto-triggers on ready-for-review)

Pre-Merge Checklist

• New or updated tests for any fix or new behavior
• Updated documentation for new features and behaviors, including docstrings for API docs.

Other Notes

• Closes Create a notebook for time series #384

Summary by CodeRabbit

• Documentation
  • Added a new "Time Series" tutorial demonstrating synthetic ECG time-series generation, visualization of real vs. synthetic traces, and evaluation (including a train-on-synthetic / test-on-real workflow).
  • Tutorial and site navigation updated so the new Time Series guide appears under Tutorials.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a new "Time Series" Jupyter notebook tutorial demonstrating Safe Synthesizer time-series synthesis (ECG200), including cu129 install, data conversion, generation, visualization, manual TSTR evaluation, and registers the notebook in the docs navigation.

Changes

Time Series Tutorial

Layer / File(s)	Summary
Tutorial setup, installation, and data preparation docs/tutorials/time-series.ipynb	Notebook header/prereqs for Linux NVIDIA GPUs; installs nemo-safe-synthesizer[engine,cu129], aeon, and matplotlib; defines aeon_to_long_df(X, y) (signature simplified), loads ECG200, converts to long-format DataFrame, and plots sample real ECG traces per class.
Safe Synthesizer configuration and run docs/tutorials/time-series.ipynb	Configures SafeSynthesizer for time-series with timestamp_column="timestep" and group_training_examples_by="group_id", disables PII replacement and built-in evaluation, enforces timestamp fidelity, sets training/generation hyperparameters, runs builder, and captures builder.results.
Synthetic results retrieval and comparison plots docs/tutorials/time-series.ipynb	Retrieves results.synthetic_data, counts unique synthetic group_ids, previews synthetic rows, and plots real vs synthetic ECG traces side-by-side per class.
TSTR evaluation implementation and conclusion docs/tutorials/time-series.ipynb	Documents TSTR approach (exclude prefill timesteps), defines long_df_to_aeon, converts/trimms long-form data to aeon arrays, trains MiniRocket+RidgeClassifierCV on real vs synthetic, scores on real test set, prints accuracies and gap, and adds concluding notes.
Documentation index and navigation registration docs/tutorials/index.md, mkdocs.yml	Adds "Time Series" notebook entry to the Tutorials index and MkDocs nav configuration.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

documentation

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: time series demo notebook' directly and clearly describes the main change: adding a time series demo notebook to the documentation.
Linked Issues check	✅ Passed	The PR successfully implements the objective from issue #384 by creating a time series 101-style notebook with comprehensive pipeline demonstration including data loading, configuration, generation, and evaluation.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #384: the new notebook, tutorial index entry, and mkdocs configuration update are all necessary to deliver the requested time series demo notebook.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch seayang/time-series-101-notebook

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bc11103b-d513-4c78-99cf-0b53b93d967c

📥 Commits

Reviewing files that changed from the base of the PR and between dc0e9b3 and 7a0b0df.

📒 Files selected for processing (2)

• docs/tutorials/index.md
• docs/tutorials/time-series.ipynb

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: Typecheck
• GitHub Check: Analyze (Python)
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (python)

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{md,markdown,py}

📄 CodeRabbit inference engine (.cursor/rules/agent-markdown-style.mdc)

**/*.{md,markdown,py}: Avoid decorative bold (**text**) in list items, body text, and docstrings; use structural cues (headers, list markers, colons, backticks) for emphasis instead
Use backticks for code identifiers, paths, and CLI commands in markdown and docstrings

Files:

• docs/tutorials/index.md

**/*.{md,markdown}

📄 CodeRabbit inference engine (.cursor/rules/agent-markdown-style.mdc)

**/*.{md,markdown}: Bold is acceptable only in markdown tables where it's the conventional way to mark header-like cells in the body
Use ## headers to segment markdown sections instead of bold text
Use -- (em-dash) instead of - (hyphen) for asides in markdown

Files:

• docs/tutorials/index.md

docs/**/*.md

📄 CodeRabbit inference engine (.cursor/rules/writing-docs.mdc)

docs/**/*.md: Classify documentation content using the Diataxis framework (TUTORIAL, HOW-TO, EXPLANATION, or REFERENCE) before writing, ensuring each page fits exactly ONE type
Use cross-links between different Diataxis content types (TUTORIAL, HOW-TO, EXPLANATION, REFERENCE) to connect related documentation
Use MkDocs Material admonitions syntax for notes, warnings, and collapsible tips: !!! note, !!! warning, ??? tip
Use MkDocs Material tabs syntax (=== "Label") for presenting multiple examples or implementations side-by-side
Use code blocks with metadata (title, hl_lines) to highlight relevant code snippets in documentation examples
Use Mermaid diagrams (flowchart, sequence diagrams, etc.) for visualizing architecture, workflows, and concepts in documentation
Write documentation following high signal-to-noise principles: every sentence must earn its place by providing essential information
Use progressive disclosure in documentation: start with simple concepts, then layer complexity for advanced readers
Include working code examples in documentation; ensure all code snippets are tested and actually work
List all prerequisites at the top of documentation pages before diving into main content
End documentation pages with 'Next steps' section containing links to related content and logical progression points

Files:

• docs/tutorials/index.md

**/*

⚙️ CodeRabbit configuration file

**/*: Review as a senior maintainer for NeMo Safe Synthesizer. Prioritize issues that can change behavior, break user workflows, weaken privacy guarantees, hide failures, make tests unreliable, or create maintenance risk. Avoid generic style commentary unless it points to a concrete project convention that automated tools will not catch.
Comment only when the finding is actionable and tied to changed code. For each finding, state the impact, the condition that triggers it, and the smallest practical fix. Prefer one precise comment over broad advice. Do not ask for refactors outside the PR scope unless the changed code creates the problem.
Review type guidance: - Potential issue: use for correctness bugs, data loss, privacy leaks,
security risks, broken public APIs, invalid config behavior, missing
validation, hidden failures, nondeterministic tests, or CI breakage.

• Refactor suggestion: use for local maintainability problems introduced
  by the diff when they have clear future cost, such as duplicated setup,
  unclear boundaries, over-mocking, avoidable complexity, or opaque test
  helpers.
• Nitpick: avoid in chill mode. Do not emit formatting, import-order,
  wording, or style-only comments unless automated tools cannot catch the
  issue and it affects maintainability.

Severity guidance: - Critical: security/privacy leaks, data loss, training/test/holdout
contamination, or broken release/package/core pipeline execution.

• Major: incorrect generation/training/evaluation behavior, broken
  CLI/SDK public API, invalid config defaults or validators, or GPU/vLLM
  cleanup and process-isolation bugs likely to fail CI or production
  runs.
• Minor: localized bugs, missing focused tests for changed behavior, or
  bad test patterns that weaken regression coverage.
• Trivial: small cleanup with no behavior impact. Usually suppress in
  chill mode.
• Info: context only. Avoid unless it helps reviewers understand risk.
  Safe-Synthesizer-specific review focus: - Data ...

Files:

• docs/tutorials/index.md

docs/**

⚙️ CodeRabbit configuration file

Review documentation as MkDocs Material content. Check Diataxis fit, accurate commands, internal links, code fences, and markdown style from STYLE_GUIDE.md.

Files:

• docs/tutorials/index.md

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c4f7ab7f-9477-45d8-b8cc-8f7fa2e2bbbe

📥 Commits

Reviewing files that changed from the base of the PR and between 78521b3 and 701718e.

📒 Files selected for processing (1)

• .github/workflows/config/.secrets.baseline

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Unit Tests (3.13)
• GitHub Check: Unit Tests (3.11)
• GitHub Check: Unit Tests (3.12)
• GitHub Check: Analyze (Python)
• GitHub Check: Analyze (python)

🧰 Additional context used

🪛 Betterleaks (1.2.0)

.github/workflows/config/.secrets.baseline

[high] 132-132: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

---

[high] 139-139: Detected a Generic API Key, potentially exposing access to various services and sensitive operations.

(generic-api-key)

🔇 Additional comments (1)

.github/workflows/config/.secrets.baseline (1)

29-31: LGTM!

Also applies to: 43-47, 54-56, 60-62, 78-80

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

Actionable comments posted: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9e868ccf-dc7b-4b93-967e-938cb5915c21

📥 Commits

Reviewing files that changed from the base of the PR and between 701718e and 01c82d7.

📒 Files selected for processing (2)

• docs/tutorials/time-series.ipynb
• mkdocs.yml

✅ Files skipped from review due to trivial changes (1)

• mkdocs.yml

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: Unit Tests (3.13)
• GitHub Check: Unit Tests (3.12)
• GitHub Check: Unit Tests (3.11)

🧰 Additional context used

📓 Path-based instructions (2)

**/*

⚙️ CodeRabbit configuration file

**/*: Review as a senior maintainer for NeMo Safe Synthesizer. Prioritize issues that can change behavior, break user workflows, weaken privacy guarantees, hide failures, make tests unreliable, or create maintenance risk. Avoid generic style commentary unless it points to a concrete project convention that automated tools will not catch.
Comment only when the finding is actionable and tied to changed code. For each finding, state the impact, the condition that triggers it, and the smallest practical fix. Prefer one precise comment over broad advice. Do not ask for refactors outside the PR scope unless the changed code creates the problem.
Review type guidance: - Potential issue: use for correctness bugs, data loss, privacy leaks,
security risks, broken public APIs, invalid config behavior, missing
validation, hidden failures, nondeterministic tests, or CI breakage.

• Refactor suggestion: use for local maintainability problems introduced
  by the diff when they have clear future cost, such as duplicated setup,
  unclear boundaries, over-mocking, avoidable complexity, or opaque test
  helpers.
• Nitpick: avoid in chill mode. Do not emit formatting, import-order,
  wording, or style-only comments unless automated tools cannot catch the
  issue and it affects maintainability.

Severity guidance: - Critical: security/privacy leaks, data loss, training/test/holdout
contamination, or broken release/package/core pipeline execution.

• Major: incorrect generation/training/evaluation behavior, broken
  CLI/SDK public API, invalid config defaults or validators, or GPU/vLLM
  cleanup and process-isolation bugs likely to fail CI or production
  runs.
• Minor: localized bugs, missing focused tests for changed behavior, or
  bad test patterns that weaken regression coverage.
• Trivial: small cleanup with no behavior impact. Usually suppress in
  chill mode.
• Info: context only. Avoid unless it helps reviewers understand risk.
  Safe-Synthesizer-specific review focus: - Data ...

Files:

• docs/tutorials/time-series.ipynb

docs/**

⚙️ CodeRabbit configuration file

Review documentation as MkDocs Material content. Check Diataxis fit, accurate commands, internal links, code fences, and markdown style from STYLE_GUIDE.md.

Files:

• docs/tutorials/time-series.ipynb

🔇 Additional comments (7)

docs/tutorials/time-series.ipynb (7)

1-19: LGTM!

---

30-42: LGTM!

---

65-94: LGTM!

---

106-128: LGTM!

---

305-323: LGTM!

---

172-174: ⚡ Quick win

No issue. The parameter name enforce_timeseries_fidelity matches the actual API in src/nemo_safe_synthesizer/config/generate.py and is correct.

			> Likely an incorrect or invalid review comment.

---

1-353: ⚡ Quick win

Navigation files have been properly updated. Both mkdocs.yml (line 174) and docs/tutorials/index.md (line 12) correctly reference the new time-series tutorial. No further action needed.

[greptile-apps]

Greptile Summary

This PR adds a new Jupyter notebook tutorial (time-series.ipynb) covering synthetic ECG time-series generation using NeMo Safe Synthesizer, and wires it into the documentation index and MkDocs navigation.

• New notebook walks through loading the ECG200 dataset via aeon, configuring Safe Synthesizer in time-series mode, generating synthetic traces, and running manual TSTR evaluation with MiniRocket + RidgeClassifierCV.
• Documentation index (docs/tutorials/index.md) and mkdocs.yml updated to surface the new tutorial under Tutorials.

Confidence Score: 5/5

Documentation-only change adding a tutorial notebook; no production code paths are touched.

The change is entirely additive — a new Jupyter notebook, one line in the tutorial index, and one line in mkdocs.yml. No existing logic is modified, and the notebook follows the same structure and conventions as the other tutorials in the repo.

No files require special attention.

Important Files Changed

Filename	Overview
docs/tutorials/time-series.ipynb	New tutorial notebook: ECG200 load → synthesize → visualize → TSTR evaluation; structure is clear and cells run in logical order.
docs/tutorials/index.md	Adds a single bullet linking to the new time-series notebook; no issues.
mkdocs.yml	Adds Time Series entry under Tutorials in the site nav; consistent with existing entries.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Load ECG200 dataset
aeon load_classification] --> B[Convert to NSS long-format
aeon_to_long_df]
    B --> C[Visualize real ECG traces
matplotlib]
    C --> D[Configure SafeSynthesizer
with_time_series / with_data
with_train / with_generate]
    D --> E[builder.run
Train + Generate]
    E --> F[Retrieve synthetic_data
results.synthetic_data]
    F --> G[Visual comparison
Real vs Synthetic side-by-side]
    G --> H[TSTR Evaluation]
    H --> H1[Baseline: Train on Real
MiniRocket + RidgeClassifierCV]
    H --> H2[TSTR: Train on Synthetic
MiniRocket + RidgeClassifierCV]
    H1 --> I[Score on Real Test Set]
    H2 --> I
    I --> J[Report real_acc vs synth_acc
and TSTR gap]

Loading

_{Reviews (4): Last reviewed commit: "Merge branch 'main' into seayang/time-se..." | Re-trigger Greptile}

[kendrickb-nvidia]

Let's discuss offline about how often a synthetic sequence collapses to all 0s.