Pytrendy

Use-case notes (from the notebooks)

• Gradual trends — the default case; trend_class='gradual' for all Up/Down. Compare via filter_segments(direction='Up', sort_by='change_rank') to rank competing uptrends.
• Abrupt trends — short, sharp shifts (changepoint-style). Pass method_params=dict(abrupt_padding=N) to extend each abrupt segment N days forward (for Interrupted Time Series / Pre-Post analysis). Padding stops early if the signal reverses; segments gain a padded=True column. Combine with gradual in one run — DTW classifies each segment independently, so a single detect_trends() call returns both classes.
• Noise — direction='Noise' segments are flagged by a rolling SNR threshold, not by magnitude. Use filter_segments(direction='Noise') to inspect what got rejected. As noise std rises, trends shorten and more Noise/Flat segments appear; borderline trends keep high change_rank so they're easy to filter out.
• Noise control via avoid_noise — method_params=dict(avoid_noise=False) opts out of noise detection entirely. Spikes and noisy regions are ignored and trend detection proceeds straight through them. Use case: new-market launches or quasi-experiments where the signal is zero before and after an activation window — with avoid_noise=True (default), the step-change boundaries produce Noise artifacts; with avoid_noise=False, you get clean Up/Down segments. See whats-new.md v1.2.0 entry / PR #110.

Tests exercise this heavily in tests/test_io_results.py (all @pytest.mark.core) — any API change there breaks the core suite immediately. Read results_pytrendy.py before extending the class.

Segment classification

• direction ∈ {Up, Down, Flat, Noise} — assigned during process_signals/segments_get.
• trend_class ∈ {gradual, abrupt, NaN} — assigned by segments_refine/trend_classify.py via DTW against classes_signals references. Only Up/Down segments get a class; Flat/Noise stay NaN.
• Min segment length: Up/Down ≥3 days, Flat/Noise ≥1 day (enforced in segments_get.py).

method_params (the only tuning surface)

{'abrupt_padding': 0, 'avoid_noise': True}  # defaults; see maintenance skill for deprecation note

detect_trends reconstructs this dict from an allowlist — unknown keys are dropped. Adding a tunable = update the allowlist in detect_trends.py:72 + the docstring + add a test.

Install & verify

During development you can import pytrendy directly — no rebuild step needed. The commands below are primarily for end users or when setting up a fresh environment.

pip install -e ".[dev]"           # dev: pytest, pytest-cov, pytest-mpl, pytest-timeout
pip install -e ".[dev,docs]"      # add mkdocs material + mkdocstrings for docs work

Verify before push — CI runs core first, then non-core with --cov-append:

pytest tests/ -m core                       # essential, must pass
pytest tests/ -m "not core" --cov-append    # the rest
# or just: pytest  (pyproject addopts already set --mpl --cov=pytrendy)

• 15s per-test timeout (pytest-timeout).
• Plot tests use pytest-mpl with baselines pinned to matplotlib==3.10.8 (hard pin in pyproject.toml). Regenerating baselines on another version = false failures. See the test skill.
• coverage.xml + .coverage are gitignored artifacts; don't commit.

Docs

• MkDocs Material + mkdocstrings (Google-style). New page → register under nav: in mkdocs.yml.
• mkdocs serve for local preview. PRs touching docs/, mkdocs.yml, or pytrendy/ auto-deploy a preview at russellsb.github.io/pytrendy/pr-<N>/ (bot comments the URL; removed on PR close; fork PRs skipped).
• JupyterLite notebooks in docs/examples/ — run scripts/normalize_notebooks.sh before building docs (works around a JupyterLite text-output rendering bug).