TwoPy 0.1.5__tar.gz → 0.1.7__tar.gz

{twopy-0.1.5 → twopy-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: twopy
-Version: 0.1.5
+Version: 0.1.7
 Summary: Two-photon imaging analysis tool with a napari interface.
 Author-email: Gustavo Madeira Santana <fromweb1@gumadeiras.com>
 License-Expression: MIT
@@ -28,7 +28,7 @@ Two-photon imaging analysis tool for the Clark Lab output format.
 
 twopy lets you open two-photon recordings, draw ROIs, plot responses in real time, process and analyze them, and save them.
 
-When you first load a recording, twopy converts it to a standardized HDF5 format. The converted format includes the aligned movie, mean image, stimulus tables, photodiode signals, and  recording metadata. Analysis and the GUI both work from the converted files, so the original source files remain separate from twopy's outputs.
+When you first load a recording, twopy converts it to a standardized HDF5 format. The converted format includes the aligned movie, mean image, stimulus tables, photodiode signals, and  recording metadata. Analysis and the GUI both work from the converted files, so the original source files remain separate from twopy's outputs. By default, converted recordings and interactive analysis outputs are cached locally under `~/.cache/twopy/recordings` for speed; saving ROIs and analysis publishes the changed output files back to the configured `analysis_output` location in the background.
 
 ## Install
 

{twopy-0.1.5 → twopy-0.1.7}/README.md

@@ -8,7 +8,7 @@ Two-photon imaging analysis tool for the Clark Lab output format.
 
 twopy lets you open two-photon recordings, draw ROIs, plot responses in real time, process and analyze them, and save them.
 
-When you first load a recording, twopy converts it to a standardized HDF5 format. The converted format includes the aligned movie, mean image, stimulus tables, photodiode signals, and  recording metadata. Analysis and the GUI both work from the converted files, so the original source files remain separate from twopy's outputs.
+When you first load a recording, twopy converts it to a standardized HDF5 format. The converted format includes the aligned movie, mean image, stimulus tables, photodiode signals, and  recording metadata. Analysis and the GUI both work from the converted files, so the original source files remain separate from twopy's outputs. By default, converted recordings and interactive analysis outputs are cached locally under `~/.cache/twopy/recordings` for speed; saving ROIs and analysis publishes the changed output files back to the configured `analysis_output` location in the background.
 
 ## Install
 

{twopy-0.1.5 → twopy-0.1.7}/pyproject.toml

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

{twopy-0.1.5 → twopy-0.1.7}/src/twopy/analysis/persistence.py

@@ -26,6 +26,7 @@ from twopy.analysis.dff import RoiDeltaFOverF
 from twopy.analysis.response_processing import (
     ResponseProcessingOptions,
     RoiCorrelationScores,
+    RoiNormalizationFactors,
 )
 from twopy.analysis.response_processing.persistence import (
     read_response_processing_group,
@@ -99,6 +100,7 @@ class LoadedAnalysisOutputs:
     baseline_windows: tuple[FrameWindow, ...]
     grouped_responses: GroupedRoiResponses | None
     response_processing_options: ResponseProcessingOptions | None
+    normalization_factors: RoiNormalizationFactors | None
     correlation_scores: RoiCorrelationScores | None
 
 
@@ -112,6 +114,7 @@ def save_analysis_outputs(
     baseline_windows: Sequence[FrameWindow] = (),
     grouped_responses: GroupedRoiResponses | None = None,
     response_processing_options: ResponseProcessingOptions | None = None,
+    normalization_factors: RoiNormalizationFactors | None = None,
     correlation_scores: RoiCorrelationScores | None = None,
     response_summary_trials_csv: Path | None = None,
     response_summary_grouped_csv: Path | None = None,
@@ -128,6 +131,8 @@ def save_analysis_outputs(
         grouped_responses: Optional grouped trial responses.
         response_processing_options: Optional smoothing, low-pass, and
             correlation-QC settings used for these outputs.
+        normalization_factors: Optional per-ROI factors used for epoch-peak
+            normalization.
         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.
@@ -149,8 +154,10 @@ 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"
+    if (
+        correlation_scores is not None or normalization_factors is not None
+    ) and response_processing_options is None:
+        msg = "response-processing audit outputs require response_processing_options"
         raise ValueError(msg)
     if grouped_responses is not None:
         validate_grouped_roi_responses(grouped_responses)
@@ -181,6 +188,7 @@ def save_analysis_outputs(
             write_response_processing_group(
                 h5_file.create_group("response_processing"),
                 options=response_processing_options,
+                normalization_factors=normalization_factors,
                 correlation_scores=correlation_scores,
             )
 
@@ -249,6 +257,11 @@ def load_analysis_outputs(path: Path) -> LoadedAnalysisOutputs:
             response_processing_options=(
                 response_processing.options if response_processing is not None else None
             ),
+            normalization_factors=(
+                response_processing.normalization_factors
+                if response_processing is not None
+                else None
+            ),
             correlation_scores=(
                 response_processing.correlation_scores
                 if response_processing is not None

{twopy-0.1.5 → twopy-0.1.7}/src/twopy/analysis/response_processing/__init__.py

@@ -12,8 +12,10 @@ how to save the resulting audit trail.
 
 from twopy.analysis.response_processing.apply import (
     ResponseProcessingResult,
+    RoiNormalizationFactors,
     apply_correlation_filter_to_grouped_roi_responses,
     mask_grouped_roi_responses_by_included_rois,
+    normalize_grouped_roi_responses_by_epoch_peak,
     process_grouped_roi_responses,
     process_roi_delta_f_over_f,
 )
@@ -23,6 +25,8 @@ from twopy.analysis.response_processing.options import (
     CorrelationWindowSeconds,
     LowPassFilterMethod,
     LowPassFilterOptions,
+    NormalizationMethod,
+    NormalizationOptions,
     ResponseProcessingOptions,
     SmoothingMethod,
     SmoothingOptions,
@@ -45,15 +49,19 @@ __all__ = [
     "CorrelationWindowSeconds",
     "LowPassFilterMethod",
     "LowPassFilterOptions",
+    "NormalizationMethod",
+    "NormalizationOptions",
     "apply_correlation_filter_to_grouped_roi_responses",
     "mask_grouped_roi_responses_by_included_rois",
     "nan_aware_moving_average",
     "nan_aware_savgol_filter",
+    "normalize_grouped_roi_responses_by_epoch_peak",
     "process_grouped_roi_responses",
     "process_roi_delta_f_over_f",
     "ResponseProcessingOptions",
     "ResponseProcessingResult",
     "RoiCorrelationScores",
+    "RoiNormalizationFactors",
     "score_roi_correlations",
     "SmoothingMethod",
     "SmoothingOptions",

{twopy-0.1.5 → twopy-0.1.7}/src/twopy/analysis/response_processing/apply.py

@@ -15,6 +15,7 @@ import numpy.typing as npt
 
 from twopy.analysis.dff import RoiDeltaFOverF
 from twopy.analysis.response_processing.options import (
+    NormalizationOptions,
     ResponseProcessingOptions,
     validate_response_processing_options,
 )
@@ -30,17 +31,36 @@ from twopy.analysis.response_processing.signals import (
 from twopy.analysis.responses import (
     GroupedRoiResponses,
     RoiResponseTrial,
+    summarize_roi_response_trials,
     validate_grouped_roi_responses,
 )
 
 __all__ = [
     "apply_correlation_filter_to_grouped_roi_responses",
+    "normalize_grouped_roi_responses_by_epoch_peak",
     "mask_grouped_roi_responses_by_included_rois",
+    "RoiNormalizationFactors",
     "ResponseProcessingResult",
     "process_grouped_roi_responses",
     "process_roi_delta_f_over_f",
 ]
 
+_NORMALIZATION_MIN_PEAK = 1e-12
+
+
+@dataclass(frozen=True)
+class RoiNormalizationFactors:
+    """Per-ROI factors used for epoch-peak response normalization.
+
+    Inputs: grouped response trials and one enabled normalization option.
+    Outputs: the positive peak factor for each ROI in the selected epoch.
+    """
+
+    roi_labels: tuple[str, ...]
+    factors: npt.NDArray[np.float64]
+    epoch_number: int
+    epoch_name: str | None
+
 
 @dataclass(frozen=True)
 class ResponseProcessingResult:
@@ -53,6 +73,7 @@ class ResponseProcessingResult:
 
     grouped_responses: GroupedRoiResponses
     options: ResponseProcessingOptions
+    normalization_factors: RoiNormalizationFactors | None
     correlation_scores: RoiCorrelationScores | None
 
 
@@ -66,8 +87,8 @@ def process_roi_delta_f_over_f(
 
     Args:
         dff: Continuous ROI dF/F result.
-        options: Processing options. Correlation filtering is ignored here
-            because it needs grouped repeated-trial responses.
+        options: Processing options. Normalization and correlation filtering
+            are ignored here because they need grouped repeated-trial responses.
         data_rate_hz: Sampling rate in hertz.
 
     Returns:
@@ -129,6 +150,10 @@ def process_grouped_roi_responses(
     validate_response_processing_options(options, data_rate_hz=grouped.data_rate_hz)
     validate_grouped_roi_responses(grouped)
     processed = _copy_grouped_with_processed_values(grouped, options=options)
+    processed, normalization_factors = normalize_grouped_roi_responses_by_epoch_peak(
+        processed,
+        options=options.normalization,
+    )
     processed, correlation_scores = apply_correlation_filter_to_grouped_roi_responses(
         processed,
         options=options,
@@ -136,10 +161,57 @@ def process_grouped_roi_responses(
     return ResponseProcessingResult(
         grouped_responses=processed,
         options=options,
+        normalization_factors=normalization_factors,
         correlation_scores=correlation_scores,
     )
 
 
+def normalize_grouped_roi_responses_by_epoch_peak(
+    grouped: GroupedRoiResponses,
+    *,
+    options: NormalizationOptions,
+) -> tuple[GroupedRoiResponses, RoiNormalizationFactors | None]:
+    """Normalize grouped responses by each ROI's selected-epoch peak.
+
+    Args:
+        grouped: Grouped ROI responses to normalize.
+        options: Normalization settings.
+
+    Returns:
+        ``(grouped_responses, factors)``. ``factors`` is ``None`` when
+        normalization is disabled.
+
+    Raises:
+        ValueError: If the selected epoch is absent or any ROI lacks a positive
+        finite peak in that epoch.
+    """
+    validate_grouped_roi_responses(grouped)
+    if options.method not in {"none", "epoch_peak"}:
+        msg = f"Unknown normalization method {options.method!r}"
+        raise ValueError(msg)
+    if options.method == "none":
+        return grouped, None
+    if options.epoch_number is None:
+        msg = "epoch-peak normalization requires an epoch_number"
+        raise ValueError(msg)
+    factors = _normalization_factors(grouped, options=options)
+    trials = tuple(
+        _copy_trial_with_values(trial, trial.values / factors.factors)
+        for trial in grouped.trials
+    )
+    return (
+        GroupedRoiResponses(
+            roi_labels=grouped.roi_labels,
+            data_rate_hz=grouped.data_rate_hz,
+            trials=trials,
+            pre_window_seconds=grouped.pre_window_seconds,
+            post_window_seconds=grouped.post_window_seconds,
+            response_window_auto=grouped.response_window_auto,
+        ),
+        factors,
+    )
+
+
 def apply_correlation_filter_to_grouped_roi_responses(
     grouped: GroupedRoiResponses,
     *,
@@ -259,6 +331,52 @@ def _copy_grouped_with_processed_values(
     )
 
 
+def _normalization_factors(
+    grouped: GroupedRoiResponses,
+    *,
+    options: NormalizationOptions,
+) -> RoiNormalizationFactors:
+    """Return per-ROI selected-epoch peak factors."""
+    selected_trials = tuple(
+        trial
+        for trial in grouped.trials
+        if trial.epoch_number == options.epoch_number
+        and (options.epoch_name is None or trial.epoch_name == options.epoch_name)
+    )
+    if len(selected_trials) == 0:
+        label = (
+            f"{options.epoch_number}: {options.epoch_name}"
+            if options.epoch_name is not None
+            else str(options.epoch_number)
+        )
+        msg = f"No trials matched normalization epoch {label}"
+        raise ValueError(msg)
+    summary = summarize_roi_response_trials(
+        selected_trials,
+        roi_labels=grouped.roi_labels,
+        data_rate_hz=grouped.data_rate_hz,
+    )
+    factors = np.nanmax(summary.mean_values, axis=1)
+    bad_indices = tuple(
+        index
+        for index, factor in enumerate(factors)
+        if not np.isfinite(factor) or factor <= _NORMALIZATION_MIN_PEAK
+    )
+    if len(bad_indices) > 0:
+        bad_labels = ", ".join(grouped.roi_labels[index] for index in bad_indices)
+        msg = (
+            "Normalization epoch peak must be positive for every ROI; "
+            f"invalid ROI labels: {bad_labels}"
+        )
+        raise ValueError(msg)
+    return RoiNormalizationFactors(
+        roi_labels=grouped.roi_labels,
+        factors=factors.astype(np.float64, copy=False),
+        epoch_number=int(options.epoch_number or 0),
+        epoch_name=options.epoch_name,
+    )
+
+
 def _mask_excluded_rois(
     grouped: GroupedRoiResponses,
     *,
@@ -334,6 +452,17 @@ def _processing_metadata(
             else float(options.low_pass.cutoff_hz)
         ),
         "response_processing_low_pass_order": options.low_pass.order,
+        "response_processing_normalization_method": options.normalization.method,
+        "response_processing_normalization_epoch_number": (
+            "none"
+            if options.normalization.epoch_number is None
+            else int(options.normalization.epoch_number)
+        ),
+        "response_processing_normalization_epoch_name": (
+            "none"
+            if options.normalization.epoch_name is None
+            else options.normalization.epoch_name
+        ),
         "response_processing_correlation_reference": (
             options.correlation_filter.reference
         ),

{twopy-0.1.5 → twopy-0.1.7}/src/twopy/analysis/response_processing/options.py

@@ -19,6 +19,8 @@ __all__ = [
     "CorrelationWindowSeconds",
     "LowPassFilterMethod",
     "LowPassFilterOptions",
+    "NormalizationMethod",
+    "NormalizationOptions",
     "ResponseProcessingOptions",
     "SmoothingMethod",
     "SmoothingOptions",
@@ -27,6 +29,7 @@ __all__ = [
 
 SmoothingMethod = Literal["none", "moving_average", "savgol"]
 LowPassFilterMethod = Literal["none", "butterworth"]
+NormalizationMethod = Literal["none", "epoch_peak"]
 CorrelationFilterReference = Literal["none", "epoch_mean", "epoch_peak"]
 CorrelationWindowSeconds = tuple[float | None, float | None]
 
@@ -66,6 +69,24 @@ class LowPassFilterOptions:
     order: int = 2
 
 
+@dataclass(frozen=True)
+class NormalizationOptions:
+    """Epoch-peak normalization settings for grouped ROI responses.
+
+    Inputs: a normalization method and the stimulus epoch used as the scale
+    reference.
+    Outputs: a typed contract consumed after trial grouping.
+
+    ``method="none"`` leaves grouped responses unchanged. ``method="epoch_peak"``
+    divides every response for each ROI by that ROI's mean-response peak in the
+    selected epoch, so the selected epoch's plotted peak becomes one.
+    """
+
+    method: NormalizationMethod = "none"
+    epoch_number: int | None = None
+    epoch_name: str | None = None
+
+
 @dataclass(frozen=True)
 class CorrelationFilterOptions:
     """Correlation-based response quality-control settings.
@@ -91,13 +112,15 @@ class CorrelationFilterOptions:
 class ResponseProcessingOptions:
     """Complete response post-processing configuration.
 
-    Inputs: optional smoothing, low-pass filtering, and correlation QC settings.
+    Inputs: optional smoothing, low-pass filtering, epoch-peak normalization,
+    and correlation QC settings.
     Outputs: one immutable object passed through workflow, plotting, and future
     persistence boundaries.
     """
 
     smoothing: SmoothingOptions = field(default_factory=SmoothingOptions)
     low_pass: LowPassFilterOptions = field(default_factory=LowPassFilterOptions)
+    normalization: NormalizationOptions = field(default_factory=NormalizationOptions)
     correlation_filter: CorrelationFilterOptions = field(
         default_factory=CorrelationFilterOptions
     )
@@ -123,6 +146,7 @@ def validate_response_processing_options(
     """
     _validate_smoothing_options(options.smoothing)
     _validate_low_pass_options(options.low_pass, data_rate_hz=data_rate_hz)
+    _validate_normalization_options(options.normalization)
     _validate_correlation_options(options.correlation_filter)
 
 
@@ -186,6 +210,19 @@ def _validate_low_pass_options(
             raise ValueError(msg)
 
 
+def _validate_normalization_options(options: NormalizationOptions) -> None:
+    """Validate epoch-peak normalization options."""
+    if options.method not in {"none", "epoch_peak"}:
+        msg = f"Unknown normalization method {options.method!r}"
+        raise ValueError(msg)
+    if options.epoch_number is not None and options.epoch_number < 1:
+        msg = f"normalization epoch_number must be positive; got {options.epoch_number}"
+        raise ValueError(msg)
+    if options.method == "epoch_peak" and options.epoch_number is None:
+        msg = "epoch-peak normalization requires an epoch_number"
+        raise ValueError(msg)
+
+
 def _validate_correlation_options(options: CorrelationFilterOptions) -> None:
     """Validate correlation-filter options."""
     if options.reference not in {"none", "epoch_mean", "epoch_peak"}:

{twopy-0.1.5 → twopy-0.1.7}/src/twopy/analysis/response_processing/persistence.py

@@ -1,6 +1,7 @@
 """Persist response-processing settings and QC audit data.
 
-Inputs: typed response-processing options and optional ROI correlation scores.
+Inputs: typed response-processing options plus optional normalization and ROI
+correlation audit data.
 Outputs: one inspectable HDF5 group that analysis persistence can embed.
 
 This module keeps the response-processing audit contract near the processing
@@ -12,12 +13,15 @@ from dataclasses import dataclass
 import h5py
 import numpy as np
 
+from twopy.analysis.response_processing.apply import RoiNormalizationFactors
 from twopy.analysis.response_processing.options import (
     CorrelationFilterOptions,
     CorrelationFilterReference,
     CorrelationWindowSeconds,
     LowPassFilterMethod,
     LowPassFilterOptions,
+    NormalizationMethod,
+    NormalizationOptions,
     ResponseProcessingOptions,
     SmoothingMethod,
     SmoothingOptions,
@@ -41,6 +45,7 @@ _SMOOTHING_METHODS: tuple[SmoothingMethod, ...] = (
     "savgol",
 )
 _LOW_PASS_METHODS: tuple[LowPassFilterMethod, ...] = ("none", "butterworth")
+_NORMALIZATION_METHODS: tuple[NormalizationMethod, ...] = ("none", "epoch_peak")
 _CORRELATION_REFERENCES: tuple[CorrelationFilterReference, ...] = (
     "none",
     "epoch_mean",
@@ -53,10 +58,12 @@ class PersistedResponseProcessing:
     """Response-processing audit data loaded from HDF5.
 
     Inputs: one ``response_processing`` HDF5 group.
-    Outputs: typed options plus optional ROI correlation scores.
+    Outputs: typed options plus optional normalization factors and ROI
+    correlation scores.
     """
 
     options: ResponseProcessingOptions
+    normalization_factors: RoiNormalizationFactors | None
     correlation_scores: RoiCorrelationScores | None
 
 
@@ -64,6 +71,7 @@ def write_response_processing_group(
     group: h5py.Group,
     *,
     options: ResponseProcessingOptions,
+    normalization_factors: RoiNormalizationFactors | None = None,
     correlation_scores: RoiCorrelationScores | None = None,
 ) -> None:
     """Write response-processing settings and optional QC scores.
@@ -71,6 +79,8 @@ def write_response_processing_group(
     Args:
         group: Destination ``response_processing`` HDF5 group.
         options: Processing options used for the saved analysis output.
+        normalization_factors: Optional per-ROI normalization factors used for
+            epoch-peak normalization.
         correlation_scores: Optional ROI-level correlation QC result.
 
     Returns:
@@ -86,6 +96,24 @@ def write_response_processing_group(
     low_pass.attrs["cutoff_hz"] = _optional_float_attr(options.low_pass.cutoff_hz)
     low_pass.attrs["order"] = options.low_pass.order
 
+    normalization = group.create_group("normalization")
+    normalization.attrs["method"] = options.normalization.method
+    normalization.attrs["epoch_number"] = _optional_int_attr(
+        options.normalization.epoch_number,
+    )
+    normalization.attrs["epoch_name"] = _optional_text_attr(
+        options.normalization.epoch_name,
+    )
+    if normalization_factors is not None:
+        normalization.create_dataset(
+            "roi_labels",
+            data=np.asarray(
+                normalization_factors.roi_labels,
+                dtype=h5py.string_dtype("utf-8"),
+            ),
+        )
+        normalization.create_dataset("factors", data=normalization_factors.factors)
+
     correlation = group.create_group("correlation_filter")
     correlation.attrs["reference"] = options.correlation_filter.reference
     correlation.attrs["minimum_correlation"] = (
@@ -136,12 +164,25 @@ def read_response_processing_group(group: h5py.Group) -> PersistedResponseProces
     options = ResponseProcessingOptions(
         smoothing=_read_smoothing_options(group["smoothing"]),
         low_pass=_read_low_pass_options(group["low_pass"]),
+        normalization=(
+            _read_normalization_options(group["normalization"])
+            if "normalization" in group
+            else NormalizationOptions()
+        ),
         correlation_filter=_read_correlation_filter_options(
             group["correlation_filter"],
         ),
     )
     return PersistedResponseProcessing(
         options=options,
+        normalization_factors=(
+            _read_normalization_factors(
+                group["normalization"],
+                options=options.normalization,
+            )
+            if "normalization" in group and "factors" in group["normalization"]
+            else None
+        ),
         correlation_scores=(
             _read_correlation_scores(group["correlation_scores"])
             if "correlation_scores" in group
@@ -176,6 +217,19 @@ def _read_low_pass_options(group: h5py.Group) -> LowPassFilterOptions:
     )
 
 
+def _read_normalization_options(group: h5py.Group) -> NormalizationOptions:
+    """Read normalization settings from one HDF5 group."""
+    return NormalizationOptions(
+        method=require_string_choice(
+            _plain_attr_value(group.attrs["method"]),
+            name="response_processing normalization method",
+            allowed=_NORMALIZATION_METHODS,
+        ),
+        epoch_number=_optional_int_from_attr(group.attrs["epoch_number"]),
+        epoch_name=_optional_text_from_attr(group.attrs["epoch_name"]),
+    )
+
+
 def _read_correlation_filter_options(group: h5py.Group) -> CorrelationFilterOptions:
     """Read correlation-filter settings from one HDF5 group."""
     return CorrelationFilterOptions(
@@ -189,6 +243,24 @@ def _read_correlation_filter_options(group: h5py.Group) -> CorrelationFilterOpti
     )
 
 
+def _read_normalization_factors(
+    group: h5py.Group,
+    *,
+    options: NormalizationOptions,
+) -> RoiNormalizationFactors:
+    """Read persisted epoch-peak normalization factors."""
+    return RoiNormalizationFactors(
+        roi_labels=_read_string_dataset(group, "roi_labels"),
+        factors=require_float64_array(
+            group["factors"][()],
+            name="response_processing/normalization/factors",
+            ndim=1,
+        ),
+        epoch_number=int(options.epoch_number or 0),
+        epoch_name=options.epoch_name,
+    )
+
+
 def _read_correlation_scores(group: h5py.Group) -> RoiCorrelationScores:
     """Read persisted ROI correlation QC scores."""
     return RoiCorrelationScores(
@@ -226,6 +298,16 @@ def _optional_float_attr(value: float | None) -> str | float:
     return "none" if value is None else float(value)
 
 
+def _optional_int_attr(value: int | None) -> str | int:
+    """Return an HDF5-friendly optional integer attribute value."""
+    return "none" if value is None else int(value)
+
+
+def _optional_text_attr(value: str | None) -> str:
+    """Return an HDF5-friendly optional text attribute value."""
+    return "none" if value is None else value
+
+
 def _optional_float_from_attr(value: object) -> float | None:
     """Read an optional float value written by ``_optional_float_attr``."""
     plain_value = _plain_attr_value(value)
@@ -234,6 +316,22 @@ def _optional_float_from_attr(value: object) -> float | None:
     return float(plain_value)
 
 
+def _optional_int_from_attr(value: object) -> int | None:
+    """Read an optional integer value written by ``_optional_int_attr``."""
+    plain_value = _plain_attr_value(value)
+    if plain_value == "none":
+        return None
+    return int(plain_value)
+
+
+def _optional_text_from_attr(value: object) -> str | None:
+    """Read an optional text value written by ``_optional_text_attr``."""
+    plain_value = _plain_attr_value(value)
+    if plain_value == "none":
+        return None
+    return str(plain_value)
+
+
 def _read_string_dataset(group: h5py.Group, name: str) -> tuple[str, ...]:
     """Read a UTF-8 string dataset from HDF5."""
     return tuple(_decode_string(value) for value in group[name][()])