Add configurable time weighting initial state (#49)

* Add time weighting initial state support

* Address PR review feedback

* Update runtime and dev dependencies

* Add Dependabot update configuration

* Resolve IDE warnings

* Remove generated issue report artifacts

* Address PR feedback and improve coverage

Author: jmrplens

.github/dependabot.yml

@@ -0,0 +1,34 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Etc/UTC"
+    labels:
+      - "dependencies"
+      - "github-actions"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:30"
+      timezone: "Etc/UTC"
+    labels:
+      - "dependencies"
+      - "python"
+    open-pull-requests-limit: 5
+    versioning-strategy: "increase"
+    ignore:
+      - dependency-name: "*"
+        update-types:
+          - "version-update:semver-minor"
+          - "version-update:semver-patch"

.github/workflows/release.yml

@@ -2,25 +2,20 @@ name: Publish to PyPI and Release
 
 on:
   push:
-    branches:
-      - main
-    paths-ignore:
-      - 'README.md'
-      - '.github/**'
-  workflow_dispatch:
+    tags:
+      - "v*"
 
 permissions:
   contents: write
 
 jobs:
   release:
     runs-on: ubuntu-latest
-    if: github.repository == 'jmrplens/PyOctaveBand' && !contains(github.event.head_commit.message, 'skip ci')
+    if: github.repository == 'jmrplens/PyOctaveBand'
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.TOKEN_GH }}
 
       - name: Set up Python
         uses: actions/setup-python@v5
@@ -32,41 +27,42 @@ jobs:
           python -m pip install --upgrade pip
           pip install build twine
 
-      - name: Bump version
-        id: bump
+      - name: Validate tag version
+        id: version
         run: |
-          # Read current version from pyproject.toml
-          # Look for 'version =' specifically in the [project] section or at line start
-          CURRENT_VERSION=$(grep -m 1 -oP '^version\s*=\s*"\K[^"]+' pyproject.toml)
-          echo "Current version: $CURRENT_VERSION"
-          
-          # Increment patch version
-          IFS='.' read -r major minor patch <<< "$CURRENT_VERSION"
-          NEW_PATCH=$((patch + 1))
-          NEW_VERSION="$major.$minor.$NEW_PATCH"
-          echo "New version: $NEW_VERSION"
-          
-          # Update pyproject.toml
-          sed -i "s/^version = \"$CURRENT_VERSION\"/version = \"$NEW_VERSION\"/" pyproject.toml
-          
-          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          PACKAGE_VERSION=$(python - <<'PY'
+          import ast
+          from pathlib import Path
 
-      - name: Commit and push changes
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
-          git add pyproject.toml
-          git commit -m "chore: bump version to ${{ steps.bump.outputs.version }} [skip ci]"
-          git push origin main
+          version_file = Path("src/pyoctaveband/_version.py")
+          module = ast.parse(version_file.read_text(encoding="utf-8"))
 
-      - name: Create Git Tag
-        run: |
-          git tag v${{ steps.bump.outputs.version }}
-          git push origin v${{ steps.bump.outputs.version }}
+          for node in module.body:
+              if isinstance(node, ast.Assign):
+                  for target in node.targets:
+                      if isinstance(target, ast.Name) and target.id == "__version__":
+                          print(ast.literal_eval(node.value))
+                          raise SystemExit(0)
+
+          raise SystemExit("Unable to find __version__ in src/pyoctaveband/_version.py")
+          PY
+          )
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+
+          if [ "$PACKAGE_VERSION" != "$TAG_VERSION" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match package version ${PACKAGE_VERSION}"
+            exit 1
+          fi
+
+          echo "version=$PACKAGE_VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=$GITHUB_REF_NAME" >> "$GITHUB_OUTPUT"
 
       - name: Build package
         run: python -m build
 
+      - name: Check package
+        run: python -m twine check dist/*
+
       - name: Publish to PyPI
         env:
           TWINE_USERNAME: __token__
@@ -76,11 +72,11 @@ jobs:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: v${{ steps.bump.outputs.version }}
-          name: Release v${{ steps.bump.outputs.version }}
+          tag_name: ${{ steps.version.outputs.tag }}
+          name: Release ${{ steps.version.outputs.tag }}
           body: |
-            Automated release for version v${{ steps.bump.outputs.version }}
+            Automated release for version ${{ steps.version.outputs.version }}
           draft: false
           prerelease: false
         env:
-          GITHUB_TOKEN: ${{ secrets.TOKEN_GH }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -55,4 +55,5 @@ coverage.xml
 *.wav
 tests/*.png
 snyk.sarif
+issues_final*.json
 node_modules/

README.md

@@ -90,7 +90,7 @@ All core functionality can be imported directly from the `pyoctaveband` package.
 | `octavefilter` | `function` | **High-level analysis.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc. (Default: 1)<br>• `order`: Filter order (Default: 6)<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: 'butter', 'cheby1', 'cheby2', 'ellip', 'bessel' (Default: 'butter')<br>• `sigbands`: Return time signals (Default: False)<br>• `detrend`: Remove DC offset (Default: True)<br>• `calibration_factor`: Sensitivity multiplier (Default: 1.0)<br>• `dbfs`: Output in dBFS instead of dB SPL (Default: False)<br>• `mode`: 'rms' or 'peak' (Default: 'rms')<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `ripple`: Passband ripple [dB] (for cheby1/ellip)<br>• `attenuation`: Stopband atten. [dB] (for cheby2/ellip) | `spl, freq = octavefilter(x, fs, ...)`<br>• `spl`: levels [dB]<br>• `freq`: frequencies [Hz]<br><br>**With `sigbands=True`:**<br>`spl, freq, xb = octavefilter(x, fs, sigbands=True)`<br>• `xb`: List of filtered signals (one per band)<br><br>**Calibrated usage:**<br>`spl, f = octavefilter(x, fs, calibration_factor=0.05)` |
 | `OctaveFilterBank` | `class` | **Efficient bank implementation.**<br>• `fs`: Sample rate [Hz]<br>• `fraction`: 1, 3, etc.<br>• `order`: Filter order<br>• `limits`: [f_min, f_max] (Default: [12, 20000])<br>• `filter_type`: Architecture name<br>• `show`: Plot response (Default: False)<br>• `plot_file`: Path to save plot (Default: None)<br>• `calibration_factor`: Sensitivity multiplier<br>• `dbfs`: Use dBFS (Default: False)<br>• `ripple`: Passband ripple [dB]<br>• `attenuation`: Stopband attenuation [dB] | `bank = OctaveFilterBank(fs=48000, fraction=3, order=6, filter_type='butter', show=True)`<br>`spl, f = bank.filter(x, sigbands=False, mode='rms', detrend=True)`<br><br>• `bank`: Instance of the filter bank |
 | `weighting_filter` | `function` | **Acoustic weighting.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `curve`: 'A', 'C', or 'Z' (Default: 'A') | `y = weighting_filter(x, fs, curve='A')`<br><br>• `y`: 1D array of weighted signal |
-| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse' | `env = time_weighting(x, fs, mode='fast')`<br><br>• `env`: 1D array of energy envelope (Mean Square) |
+| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Raw signal array (squared internally; time is the last axis)<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse'<br>• `initial_state`: None, 'zero', 'first', scalar, or array (Default: None)<br>• `None`: use the default rest state (`y[-1] = 0`)<br>• `'zero'`: explicitly initialize `y[-1]` to zero<br>• scalar: broadcast to every channel<br>• array: must match/broadcast to `x.shape[:-1]`; for `x.shape == (n_channels, n_samples)`, use shape `(n_channels,)` | `env = time_weighting(x, fs, mode='fast', initial_state=None)`<br><br>• `env`: energy envelope (Mean Square), same shape as `x` |
 | `linkwitz_riley` | `function` | **Audio crossover.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `freq`: Crossover frequency [Hz]<br>• `order`: Any even number (Default: 4) | `lo, hi = linkwitz_riley(x, fs, freq=1000, order=4)`<br><br>• `lo`: Low-pass filtered signal<br>• `hi`: High-pass filtered signal |
 | `calculate_sensitivity` | `function`| **SPL Calibration.**<br>• `ref_signal`: Calibration signal<br>• `target_spl`: Level of calibrator (Default: 94.0)<br>• `ref_pressure`: Reference pressure (Default: 20e-6) | `s = calculate_sensitivity(ref_signal, target_spl=94.0)`<br><br>• `s`: Float (multiplier for pressure) |
 | `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Required)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f_cen, f_low, f_high, labels = getansifrequencies(fraction=3)`<br><br>• `f_cen`: List of center frequencies [Hz]<br>• `f_low`: List of lower edges [Hz]<br>• `f_high`: List of upper edges [Hz]<br>• `labels`: IEC nominal frequency labels |
@@ -244,6 +244,24 @@ energy_envelope = time_weighting(signal, fs, mode='fast')
 spl_t = 10 * np.log10(energy_envelope / (2e-5)**2)
 ```
 
+By default, the exponential integrator starts from rest (`y[-1] = 0`). Passing `initial_state=None` leaves this default unspecified, while `initial_state='zero'` requests the same zero state explicitly. If the recorded segment begins after a steady signal is already present, you can start from the first sample energy instead:
+
+```python
+energy_envelope = time_weighting(signal, fs, mode='fast', initial_state='first')
+```
+
+For block processing, pass the last output value from the previous block as the next block's `initial_state` instead of resetting each block:
+
+```python
+state = None
+
+for block in audio_blocks:
+    energy_envelope = time_weighting(block, fs, mode='fast', initial_state=state)
+    state = energy_envelope[-1]
+```
+
+For multichannel blocks with time on the last axis, carry one state per channel: use `state = energy_envelope[..., -1]`. A scalar `initial_state` is applied to every channel, while an array must match or broadcast to the non-time shape, such as `(n_channels,)` for input shaped `(n_channels, n_samples)`.
+
 ---
 
 ## ⚡ Performance: Multichannel & Vectorization
@@ -564,6 +582,8 @@ $$
 
 Where `tau` is the time constant (e.g., 125ms for Fast).
 
+The default initial condition is `y[-1] = 0`. Use `initial_state='first'` to start from the first input energy, or pass a scalar/array with the previous mean-square output state.
+
 ---
 
 ## 🧪 Development and Verification

issues_final.json

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "PyOctaveBand"
-version = "1.2.1"
+dynamic = ["version"]
 authors = [
   { name="Jose Manuel Requena Plens", email="jmrplens@gmail.com" },
 ]
@@ -17,10 +17,10 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "numpy",
-    "scipy",
-    "matplotlib",
-    "numba",
+    "numpy>=2.4.4",
+    "scipy>=1.17.1",
+    "matplotlib>=3.10.9",
+    "numba>=0.65.1",
 ]
 
 [project.urls]
@@ -30,6 +30,9 @@ dependencies = [
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.dynamic]
+version = {attr = "pyoctaveband._version.__version__"}
+
 [tool.mypy]
 python_version = "3.11"
 strict = true

issues_final_check.json

@@ -1,6 +1,6 @@
-ruff
-mypy
-bandit
-types-setuptools
-pytest
-pytest-cov
+ruff>=0.15.12
+mypy>=2.0.0
+bandit>=1.9.4
+types-setuptools>=82.0.0.20260508
+pytest>=9.0.3
+pytest-cov>=7.1.0

pyproject.toml

@@ -1,13 +1,13 @@
-contourpy>=1.2.0
+contourpy>=1.3.3
 cycler>=0.12.1
-fonttools>=4.50.0
-kiwisolver>=1.4.5
-matplotlib>=3.8.0
-numpy>=1.26.0
-packaging>=23.0
-pillow>=10.0.0
-pyparsing>=3.1.0
-python-dateutil>=2.9.0
-scipy>=1.10.0
-six>=1.16.0
-numba==0.63.1
+fonttools>=4.62.1
+kiwisolver>=1.5.0
+matplotlib>=3.10.9
+numpy>=2.4.4
+packaging>=26.2
+pillow>=12.2.0
+pyparsing>=3.3.2
+python-dateutil>=2.9.0.post0
+scipy>=1.17.1
+six>=1.17.0
+numba==0.65.1

requirements-dev.txt

@@ -15,14 +15,14 @@
 from .core import OctaveFilterBank
 from .frequencies import getansifrequencies, normalizedfreq
 from .parametric_filters import WeightingFilter, linkwitz_riley, time_weighting, weighting_filter
+from ._version import __version__
 
 # Use non-interactive backend for plots
 matplotlib.use("Agg")
 
-__version__ = "1.2.0"
-
 # Public methods
 __all__ = [
+    "__version__",
     "octavefilter",
     "getansifrequencies",
     "normalizedfreq",
@@ -37,7 +37,7 @@
 
 @overload
 def octavefilter(
-    x: List[float] | np.ndarray,
+    x: List[float] | np.ndarray,  # NOSONAR - public API
     fs: int,
     fraction: float = 1,
     order: int = 6,
@@ -58,7 +58,7 @@ def octavefilter(
 
 @overload
 def octavefilter(
-    x: List[float] | np.ndarray,
+    x: List[float] | np.ndarray,  # NOSONAR - public API
     fs: int,
     fraction: float = 1,
     order: int = 6,
@@ -79,7 +79,7 @@ def octavefilter(
 
 @overload
 def octavefilter(
-    x: List[float] | np.ndarray,
+    x: List[float] | np.ndarray,  # NOSONAR - public API
     fs: int,
     fraction: float = 1,
     order: int = 6,
@@ -100,7 +100,7 @@ def octavefilter(
 
 @overload
 def octavefilter(
-    x: List[float] | np.ndarray,
+    x: List[float] | np.ndarray,  # NOSONAR - public API
     fs: int,
     fraction: float = 1,
     order: int = 6,
@@ -120,7 +120,7 @@ def octavefilter(
 
 
 def octavefilter(
-    x: List[float] | np.ndarray,
+    x: List[float] | np.ndarray,  # NOSONAR - public API
     fs: int,
     fraction: float = 1,
     order: int = 6,