TwoPy 0.1.0__tar.gz → 0.1.2__tar.gz

{twopy-0.1.0 → twopy-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.1.0
+Version: 0.1.2
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT
@@ -22,6 +22,8 @@ Requires-Dist: ty<0.1,>=0.0.34
 
 Two-photon imaging analysis tool for the Clark Lab output format.
 
+![twopy napari interface](docs/assets/twopy-napari.png)
+
 ## Getting Started
 
 twopy lets you open two-photon recordings, draw ROIs, plot responses in real time,
@@ -36,25 +38,24 @@ the converted files, so the original source files remain separate from twopy's o
 
 Examples use micromamba, but any conda-compatible environment manager should work.
 
-Run this once from the twopy folder to install everything you need:
+Preferred setup is a fresh Python 3.13 environment with the published PyPI
+package:
 
 ```sh
-micromamba env create -f environment.yml
-micromamba activate twopy
-micromamba run -n twopy pre-commit install
-cp config.example.yml config.yml
+micromamba create -n twopy -c conda-forge python=3.13 pip -y && micromamba run -n twopy python -m pip install twopy
 ```
 
-Then edit `config.yml` so the paths match your computer. The example file
-explains each setting in plain language. `config.yml` stays local to your
-machine and is not tracked by git.
-
-If the `twopy` command is missing after setup, refresh the editable install:
+Verify the install:
 
 ```sh
-micromamba run -n twopy python -m pip install -e .
+micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'
 ```
 
+If you are working from a source checkout, copy `config.example.yml` to
+`config.yml`, then edit `config.yml` so the paths match your computer. The
+example file explains each setting in plain language. `config.yml` stays local
+to your machine and is not tracked by git.
+
 ### Start The GUI
 
 Start napari from the twopy environment:
@@ -96,9 +97,18 @@ Basic GUI flow:
 
 ## Setup Details
 
-The environment installs twopy as an editable package, so the `twopy` terminal
-command is available after activating the environment. If the environment
-already existed before the command was added, refresh the editable install:
+For development, install from the repository so local code edits are used:
+
+```sh
+micromamba env create -f environment.yml
+micromamba activate twopy
+micromamba run -n twopy pre-commit install
+```
+
+The development environment installs twopy as an editable package, so the
+`twopy` terminal command is available after activating the environment. If the
+environment already existed before the command was added, refresh the editable
+install:
 
 ```sh
 micromamba run -n twopy python -m pip install -e .
@@ -113,31 +123,6 @@ micromamba run -n twopy pre-commit run --all-files
 The installed pre-commit hook runs ruff, ty, and the unit tests before each
 commit.
 
-## Release
-
-PyPI publishing uses GitHub Actions Trusted Publishing. No PyPI API token secret
-is required.
-
-One-time setup in PyPI:
-
-1. Add a trusted publisher for the `twopy` project.
-2. Use owner `gumadeiras`, repository `twopy`, workflow
-   `publish-to-pypi.yml`, and environment `pypi`.
-3. In GitHub, create the `pypi` environment and require manual approval.
-
-Release flow:
-
-1. Update `project.version` in `pyproject.toml`.
-2. Run `micromamba run -n twopy pre-commit run --all-files`.
-3. Commit the version change.
-4. Create a GitHub release whose tag is the same version, with or without a
-   leading `v`.
-5. Publish the release.
-
-The release workflow checks that the tag matches `pyproject.toml`, builds the
-wheel and source distribution, checks package metadata, and publishes to PyPI
-after the `pypi` environment approval.
-
 ## Find Recordings
 
 ```python
@@ -241,6 +226,14 @@ shared exponential tau and one amplitude per ROI. The default dF/F fit mode is
 `robust`; pass `fit_mode="source_bounds"` when you need original source-bound
 behavior for audit comparisons.
 
+The script and napari workflows also accept `ResponseProcessingOptions` for
+post-dF/F response processing. Smoothing and low-pass filters are applied to
+continuous dF/F before trial grouping, while correlation filtering scores
+grouped trial responses and stores the selected settings plus QC scores in the
+analysis HDF5 output. Smoothing supports moving-average and Savitzky-Golay
+methods; Savitzky-Golay defaults to a seven-frame window with polynomial order
+two.
+
 ## Open In Napari
 
 From a converted output directory that contains `recording_data.h5`, or from a

{twopy-0.1.0 → twopy-0.1.2}/README.md

@@ -2,6 +2,8 @@
 
 Two-photon imaging analysis tool for the Clark Lab output format.
 
+![twopy napari interface](docs/assets/twopy-napari.png)
+
 ## Getting Started
 
 twopy lets you open two-photon recordings, draw ROIs, plot responses in real time,
@@ -16,25 +18,24 @@ the converted files, so the original source files remain separate from twopy's o
 
 Examples use micromamba, but any conda-compatible environment manager should work.
 
-Run this once from the twopy folder to install everything you need:
+Preferred setup is a fresh Python 3.13 environment with the published PyPI
+package:
 
 ```sh
-micromamba env create -f environment.yml
-micromamba activate twopy
-micromamba run -n twopy pre-commit install
-cp config.example.yml config.yml
+micromamba create -n twopy -c conda-forge python=3.13 pip -y && micromamba run -n twopy python -m pip install twopy
 ```
 
-Then edit `config.yml` so the paths match your computer. The example file
-explains each setting in plain language. `config.yml` stays local to your
-machine and is not tracked by git.
-
-If the `twopy` command is missing after setup, refresh the editable install:
+Verify the install:
 
 ```sh
-micromamba run -n twopy python -m pip install -e .
+micromamba run -n twopy python -c 'import twopy; print(twopy.__name__)'
 ```
 
+If you are working from a source checkout, copy `config.example.yml` to
+`config.yml`, then edit `config.yml` so the paths match your computer. The
+example file explains each setting in plain language. `config.yml` stays local
+to your machine and is not tracked by git.
+
 ### Start The GUI
 
 Start napari from the twopy environment:
@@ -76,9 +77,18 @@ Basic GUI flow:
 
 ## Setup Details
 
-The environment installs twopy as an editable package, so the `twopy` terminal
-command is available after activating the environment. If the environment
-already existed before the command was added, refresh the editable install:
+For development, install from the repository so local code edits are used:
+
+```sh
+micromamba env create -f environment.yml
+micromamba activate twopy
+micromamba run -n twopy pre-commit install
+```
+
+The development environment installs twopy as an editable package, so the
+`twopy` terminal command is available after activating the environment. If the
+environment already existed before the command was added, refresh the editable
+install:
 
 ```sh
 micromamba run -n twopy python -m pip install -e .
@@ -93,31 +103,6 @@ micromamba run -n twopy pre-commit run --all-files
 The installed pre-commit hook runs ruff, ty, and the unit tests before each
 commit.
 
-## Release
-
-PyPI publishing uses GitHub Actions Trusted Publishing. No PyPI API token secret
-is required.
-
-One-time setup in PyPI:
-
-1. Add a trusted publisher for the `twopy` project.
-2. Use owner `gumadeiras`, repository `twopy`, workflow
-   `publish-to-pypi.yml`, and environment `pypi`.
-3. In GitHub, create the `pypi` environment and require manual approval.
-
-Release flow:
-
-1. Update `project.version` in `pyproject.toml`.
-2. Run `micromamba run -n twopy pre-commit run --all-files`.
-3. Commit the version change.
-4. Create a GitHub release whose tag is the same version, with or without a
-   leading `v`.
-5. Publish the release.
-
-The release workflow checks that the tag matches `pyproject.toml`, builds the
-wheel and source distribution, checks package metadata, and publishes to PyPI
-after the `pypi` environment approval.
-
 ## Find Recordings
 
 ```python
@@ -221,6 +206,14 @@ shared exponential tau and one amplitude per ROI. The default dF/F fit mode is
 `robust`; pass `fit_mode="source_bounds"` when you need original source-bound
 behavior for audit comparisons.
 
+The script and napari workflows also accept `ResponseProcessingOptions` for
+post-dF/F response processing. Smoothing and low-pass filters are applied to
+continuous dF/F before trial grouping, while correlation filtering scores
+grouped trial responses and stores the selected settings plus QC scores in the
+analysis HDF5 output. Smoothing supports moving-average and Savitzky-Golay
+methods; Savitzky-Golay defaults to a seven-frame window with polynomial order
+two.
+
 ## Open In Napari
 
 From a converted output directory that contains `recording_data.h5`, or from a

{twopy-0.1.0 → twopy-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "twopy"
-version = "0.1.0"
+version = "0.1.2"
 description = "Two-photon imaging analysis tool with a napari interface."
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/__init__.py

@@ -5,6 +5,7 @@ Inputs: none.
 Outputs: package constants and helper functions imported by users and scripts.
 """
 
+from twopy._version import __version__
 from twopy.analysis import (
     DEFAULT_RESPONSE_POST_WINDOW_SECONDS,
     DEFAULT_RESPONSE_PRE_WINDOW_SECONDS,
@@ -12,6 +13,7 @@ from twopy.analysis import (
     AnalysisResponseRun,
     BackgroundCorrectedRoiTraces,
     BackgroundCorrectionMethod,
+    CorrelationFilterOptions,
     DeltaFOverFFitMode,
     EpochFrameWindow,
     FrameWindow,
@@ -19,9 +21,13 @@ from twopy.analysis import (
     GroupedRoiResponseSummary,
     InterpolatedEpochMapping,
     LoadedAnalysisOutputs,
+    LowPassFilterOptions,
+    ResponseProcessingOptions,
+    RoiCorrelationScores,
     RoiDeltaFOverF,
     RoiResponseSummary,
     RoiResponseTrial,
+    SmoothingOptions,
     WindowedRoiResponse,
     analyze_recording_responses,
     apply_motion_artifact_mask_to_delta_f_over_f,
@@ -104,6 +110,7 @@ __all__ = [
     "classify_recording_photodiode_events",
     "compute_roi_delta_f_over_f",
     "compute_recording_responses",
+    "CorrelationFilterOptions",
     "convert_recording_to_twopy",
     "DEFAULT_RESPONSE_POST_WINDOW_SECONDS",
     "DEFAULT_RESPONSE_PRE_WINDOW_SECONDS",
@@ -129,6 +136,7 @@ __all__ = [
     "load_roi_set",
     "load_source_conversion_inputs",
     "LoadedAnalysisOutputs",
+    "LowPassFilterOptions",
     "make_roi_set_from_label_image",
     "make_frame_windows",
     "make_roi_set",
@@ -143,7 +151,9 @@ __all__ = [
     "PhotodiodeEvent",
     "PhotodiodeEventType",
     "PhotodiodeEventSet",
+    "ResponseProcessingOptions",
     "RoiDeltaFOverF",
+    "RoiCorrelationScores",
     "RoiResponseSummary",
     "RoiResponseTrial",
     "RoiSet",
@@ -155,6 +165,7 @@ __all__ = [
     "save_roi_set",
     "select_epoch_frame_windows",
     "split_traces_by_frame_windows",
+    "SmoothingOptions",
     "SpatialCrop",
     "SpatialDomain",
     "StimulusSpecificColumnMapping",
@@ -164,5 +175,3 @@ __all__ = [
     "write_response_summary_grouped_csv",
     "write_response_summary_trials_csv",
 ]
-
-__version__ = "0.1.0"

twopy-0.1.2/src/twopy/_version.py

@@ -0,0 +1,14 @@
+"""Package-version metadata for twopy.
+
+Inputs: installed Python package metadata.
+Outputs: the current twopy package version string.
+
+Keeping this in one small module prevents the public Python API and command-line
+interface from drifting when ``pyproject.toml`` changes.
+"""
+
+from importlib.metadata import version
+
+__all__ = ["__version__"]
+
+__version__ = version("twopy")

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/analysis/__init__.py

@@ -31,6 +31,13 @@ from twopy.analysis.persistence import (
     write_response_summary_grouped_csv,
     write_response_summary_trials_csv,
 )
+from twopy.analysis.response_processing import (
+    CorrelationFilterOptions,
+    LowPassFilterOptions,
+    ResponseProcessingOptions,
+    RoiCorrelationScores,
+    SmoothingOptions,
+)
 from twopy.analysis.responses import (
     GroupedRoiResponses,
     GroupedRoiResponseSummary,
@@ -72,6 +79,7 @@ __all__ = [
     "BackgroundCorrectionMethod",
     "compute_roi_delta_f_over_f",
     "compute_recording_responses",
+    "CorrelationFilterOptions",
     "DeltaFOverFFitMode",
     "EpochFrameWindow",
     "extract_background_corrected_roi_traces",
@@ -85,14 +93,18 @@ __all__ = [
     "is_gray_epoch_name",
     "load_analysis_outputs",
     "LoadedAnalysisOutputs",
+    "LowPassFilterOptions",
     "make_frame_windows",
     "map_stimulus_epochs_to_frame_windows",
     "RoiDeltaFOverF",
+    "ResponseProcessingOptions",
+    "RoiCorrelationScores",
     "RoiResponseSummary",
     "RoiResponseTrial",
     "save_analysis_outputs",
     "select_epoch_frame_windows",
     "split_traces_by_frame_windows",
+    "SmoothingOptions",
     "summarize_epoch_roi_responses",
     "summarize_grouped_responses",
     "WindowedRoiResponse",

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/analysis/persistence.py

@@ -23,6 +23,14 @@ from twopy.analysis.background_subtraction import (
     BackgroundCorrectionMethod,
 )
 from twopy.analysis.dff import RoiDeltaFOverF
+from twopy.analysis.response_processing import (
+    ResponseProcessingOptions,
+    RoiCorrelationScores,
+)
+from twopy.analysis.response_processing.persistence import (
+    read_response_processing_group,
+    write_response_processing_group,
+)
 from twopy.analysis.responses import (
     GroupedRoiResponses,
     RoiResponseTrial,
@@ -87,6 +95,8 @@ class LoadedAnalysisOutputs:
     dff: RoiDeltaFOverF | None
     epoch_windows: tuple[EpochFrameWindow, ...]
     grouped_responses: GroupedRoiResponses | None
+    response_processing_options: ResponseProcessingOptions | None
+    correlation_scores: RoiCorrelationScores | None
 
 
 def save_analysis_outputs(
@@ -97,6 +107,8 @@ def save_analysis_outputs(
     dff: RoiDeltaFOverF | None = None,
     epoch_windows: Sequence[EpochFrameWindow] = (),
     grouped_responses: GroupedRoiResponses | None = None,
+    response_processing_options: ResponseProcessingOptions | None = None,
+    correlation_scores: RoiCorrelationScores | None = None,
     response_summary_trials_csv: Path | None = None,
     response_summary_grouped_csv: Path | None = None,
 ) -> None:
@@ -109,6 +121,9 @@ def save_analysis_outputs(
         dff: Optional ROI dF/F result.
         epoch_windows: Optional stimulus windows used for response grouping.
         grouped_responses: Optional grouped trial responses.
+        response_processing_options: Optional smoothing, low-pass, and
+            correlation-QC settings used for these outputs.
+        correlation_scores: Optional ROI-level correlation QC scores.
         response_summary_trials_csv: Optional CSV path for one row per trial
             and ROI, with one column per relative response timepoint.
         response_summary_grouped_csv: Optional CSV path for one row per epoch,
@@ -129,6 +144,9 @@ def save_analysis_outputs(
     if any(path is not None for path in summary_outputs) and grouped_responses is None:
         msg = "response summary CSV outputs require grouped_responses"
         raise ValueError(msg)
+    if correlation_scores is not None and response_processing_options is None:
+        msg = "correlation_scores require response_processing_options"
+        raise ValueError(msg)
 
     output_path = path.expanduser()
     output_path.parent.mkdir(parents=True, exist_ok=True)
@@ -147,6 +165,12 @@ def save_analysis_outputs(
                 h5_file.create_group("responses"),
                 grouped_responses,
             )
+        if response_processing_options is not None:
+            write_response_processing_group(
+                h5_file.create_group("response_processing"),
+                options=response_processing_options,
+                correlation_scores=correlation_scores,
+            )
 
     if grouped_responses is not None:
         if response_summary_trials_csv is not None:
@@ -177,6 +201,11 @@ def load_analysis_outputs(path: Path) -> LoadedAnalysisOutputs:
     input_path = path.expanduser()
     with h5py.File(input_path, "r") as h5_file:
         _require_analysis_format(h5_file, input_path)
+        response_processing = (
+            read_response_processing_group(h5_file["response_processing"])
+            if "response_processing" in h5_file
+            else None
+        )
         return LoadedAnalysisOutputs(
             path=input_path,
             roi_set=(
@@ -198,6 +227,14 @@ def load_analysis_outputs(path: Path) -> LoadedAnalysisOutputs:
                 if "responses" in h5_file
                 else None
             ),
+            response_processing_options=(
+                response_processing.options if response_processing is not None else None
+            ),
+            correlation_scores=(
+                response_processing.correlation_scores
+                if response_processing is not None
+                else None
+            ),
         )
 
 

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/analysis/response_processing/__init__.py

@@ -12,6 +12,8 @@ how to save the resulting audit trail.
 
 from twopy.analysis.response_processing.apply import (
     ResponseProcessingResult,
+    apply_correlation_filter_to_grouped_roi_responses,
+    mask_grouped_roi_responses_by_included_rois,
     process_grouped_roi_responses,
     process_roi_delta_f_over_f,
 )
@@ -33,6 +35,7 @@ from twopy.analysis.response_processing.qc import (
 from twopy.analysis.response_processing.signals import (
     butterworth_low_pass,
     nan_aware_moving_average,
+    nan_aware_savgol_filter,
 )
 
 __all__ = [
@@ -42,7 +45,10 @@ __all__ = [
     "CorrelationWindowSeconds",
     "LowPassFilterMethod",
     "LowPassFilterOptions",
+    "apply_correlation_filter_to_grouped_roi_responses",
+    "mask_grouped_roi_responses_by_included_rois",
     "nan_aware_moving_average",
+    "nan_aware_savgol_filter",
     "process_grouped_roi_responses",
     "process_roi_delta_f_over_f",
     "ResponseProcessingOptions",

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/analysis/response_processing/apply.py

@@ -25,10 +25,13 @@ from twopy.analysis.response_processing.qc import (
 from twopy.analysis.response_processing.signals import (
     butterworth_low_pass,
     nan_aware_moving_average,
+    nan_aware_savgol_filter,
 )
 from twopy.analysis.responses import GroupedRoiResponses, RoiResponseTrial
 
 __all__ = [
+    "apply_correlation_filter_to_grouped_roi_responses",
+    "mask_grouped_roi_responses_by_included_rois",
     "ResponseProcessingResult",
     "process_grouped_roi_responses",
     "process_roi_delta_f_over_f",
@@ -122,18 +125,10 @@ def process_grouped_roi_responses(
     validate_response_processing_options(options, data_rate_hz=grouped.data_rate_hz)
     _validate_grouped_for_processing(grouped)
     processed = _copy_grouped_with_processed_values(grouped, options=options)
-    correlation_scores = None
-    if options.correlation_filter.reference in {"epoch_mean", "epoch_peak"}:
-        correlation_scores = score_roi_correlations(
-            processed,
-            minimum_correlation=options.correlation_filter.minimum_correlation,
-            reference=options.correlation_filter.reference,
-            window_seconds=options.correlation_filter.window_seconds,
-        )
-        processed = _mask_excluded_rois(
-            processed,
-            included_mask=correlation_scores.included_mask,
-        )
+    processed, correlation_scores = apply_correlation_filter_to_grouped_roi_responses(
+        processed,
+        options=options,
+    )
     return ResponseProcessingResult(
         grouped_responses=processed,
         options=options,
@@ -141,6 +136,65 @@ def process_grouped_roi_responses(
     )
 
 
+def apply_correlation_filter_to_grouped_roi_responses(
+    grouped: GroupedRoiResponses,
+    *,
+    options: ResponseProcessingOptions,
+) -> tuple[GroupedRoiResponses, RoiCorrelationScores | None]:
+    """Apply only the correlation filter from a processing option object.
+
+    Args:
+        grouped: Grouped ROI responses to score and optionally mask.
+        options: Complete processing options. Smoothing and low-pass settings
+            are validated but not re-applied here.
+
+    Returns:
+        ``(grouped_responses, scores)``. ``scores`` is ``None`` when the
+        correlation filter is disabled.
+
+    This helper lets the standard workflow process continuous dF/F first, then
+    perform trial-level quality control after grouping without accidentally
+    smoothing or filtering the same traces a second time.
+    """
+    validate_response_processing_options(options, data_rate_hz=grouped.data_rate_hz)
+    _validate_grouped_for_processing(grouped)
+    if options.correlation_filter.reference not in {"epoch_mean", "epoch_peak"}:
+        return grouped, None
+    correlation_scores = score_roi_correlations(
+        grouped,
+        minimum_correlation=options.correlation_filter.minimum_correlation,
+        reference=options.correlation_filter.reference,
+        window_seconds=options.correlation_filter.window_seconds,
+    )
+    return (
+        mask_grouped_roi_responses_by_included_rois(
+            grouped,
+            included_mask=correlation_scores.included_mask,
+        ),
+        correlation_scores,
+    )
+
+
+def mask_grouped_roi_responses_by_included_rois(
+    grouped: GroupedRoiResponses,
+    *,
+    included_mask: npt.NDArray[np.bool_],
+) -> GroupedRoiResponses:
+    """Return grouped responses with excluded ROI columns set to NaN.
+
+    Args:
+        grouped: Grouped ROI responses to mask.
+        included_mask: Boolean vector matching ``grouped.roi_labels``.
+
+    Returns:
+        New grouped responses with the same shape and labels.
+
+    The mask is public because persisted QC scores should be able to hide ROIs
+    during plot reloads without recomputing the scientific QC decision.
+    """
+    return _mask_excluded_rois(grouped, included_mask=included_mask)
+
+
 def _process_values(
     values: npt.NDArray[np.float64],
     *,
@@ -154,6 +208,12 @@ def _process_values(
             processed,
             window_frames=options.smoothing.window_frames,
         )
+    if options.smoothing.method == "savgol":
+        processed = nan_aware_savgol_filter(
+            processed,
+            window_frames=options.smoothing.window_frames,
+            polynomial_order=options.smoothing.polynomial_order,
+        )
     if options.low_pass.method == "butterworth":
         if options.low_pass.cutoff_hz is None:
             msg = "enabled low-pass filtering requires cutoff_hz"
@@ -272,6 +332,9 @@ def _processing_metadata(
     return {
         "response_processing_smoothing_method": options.smoothing.method,
         "response_processing_smoothing_window_frames": options.smoothing.window_frames,
+        "response_processing_smoothing_polynomial_order": (
+            options.smoothing.polynomial_order
+        ),
         "response_processing_low_pass_method": options.low_pass.method,
         "response_processing_low_pass_cutoff_hz": (
             "none"

{twopy-0.1.0 → twopy-0.1.2}/src/twopy/analysis/response_processing/options.py

@@ -25,7 +25,7 @@ __all__ = [
     "validate_response_processing_options",
 ]
 
-SmoothingMethod = Literal["none", "moving_average"]
+SmoothingMethod = Literal["none", "moving_average", "savgol"]
 LowPassFilterMethod = Literal["none", "butterworth"]
 CorrelationFilterReference = Literal["none", "epoch_mean", "epoch_peak"]
 CorrelationWindowSeconds = tuple[float | None, float | None]
@@ -33,17 +33,21 @@ CorrelationWindowSeconds = tuple[float | None, float | None]
 
 @dataclass(frozen=True)
 class SmoothingOptions:
-    """Moving-average smoothing settings.
+    """Response-trace smoothing settings.
 
     Inputs: a smoothing method and window length in imaging frames.
     Outputs: a typed contract consumed by signal-processing kernels.
 
-    ``method="none"`` leaves values unchanged. ``window_frames`` is still kept
-    explicit so saved options can report exactly what the user selected.
+    ``method="none"`` leaves values unchanged. ``window_frames`` and
+    ``polynomial_order`` are still kept explicit so saved options can report
+    exactly what the user selected. ``method="savgol"`` defaults to a
+    seven-frame, second-order Savitzky-Golay smoother because that preserves
+    local peak shape better than a moving average.
     """
 
     method: SmoothingMethod = "none"
-    window_frames: int = 1
+    window_frames: int = 7
+    polynomial_order: int = 2
 
 
 @dataclass(frozen=True)
@@ -124,12 +128,32 @@ def validate_response_processing_options(
 
 def _validate_smoothing_options(options: SmoothingOptions) -> None:
     """Validate smoothing options."""
-    if options.method not in {"none", "moving_average"}:
+    if options.method not in {"none", "moving_average", "savgol"}:
         msg = f"Unknown smoothing method {options.method!r}"
         raise ValueError(msg)
     if options.window_frames < 1:
         msg = f"smoothing window_frames must be at least 1; got {options.window_frames}"
         raise ValueError(msg)
+    if options.polynomial_order < 0:
+        msg = (
+            "smoothing polynomial_order must be non-negative; "
+            f"got {options.polynomial_order}"
+        )
+        raise ValueError(msg)
+    if options.method == "savgol":
+        if options.window_frames % 2 == 0:
+            msg = (
+                "Savitzky-Golay smoothing window_frames must be odd; "
+                f"got {options.window_frames}"
+            )
+            raise ValueError(msg)
+        if options.polynomial_order >= options.window_frames:
+            msg = (
+                "Savitzky-Golay polynomial_order must be below window_frames; "
+                f"got order {options.polynomial_order} and window "
+                f"{options.window_frames}"
+            )
+            raise ValueError(msg)
 
 
 def _validate_low_pass_options(