A research framework for studying complex adaptive systems through resonance detection, causal rooting analysis, and stability diagnostics.
Version: 4.3.0
License: MIT
Author: Christopher Woodyard
A one-page overview of DRR — what it detects, who it's for, and how to get started.
Print-ready (US Letter). Learn more at Vers3Dynamics.com.
The Dynamic Resonance Rooting (DRR) Framework is a computational pipeline that analyzes time-series and panel data to answer three core questions about complex adaptive systems:
- Resonance Detection — What oscillatory modes exist in the data?
- Rooting Analysis — What are the directional lead-lag relationships between variables?
- Stability Assessment — How stable are the resonance structures over time?
DRR combines spectral analysis (FFT, Welch PSD, Morlet wavelet scalograms), causal rooting (transfer entropy, lagged correlation), and state-space diagnostics to provide evidence for hypothesis generation about system behavior.
| Capability | Description |
|---|---|
| Resonance Detection | Identifies oscillatory patterns via FFT, Welch power spectral density, or Morlet wavelet scalograms (time-localized, for nonstationary signals) |
| Causal Rooting | Maps directional lead-lag relationships using transfer entropy or lagged correlation |
| Resonance Depth | Composite scoring combining spectral concentration, temporal persistence, phase coherence, and amplitude stability |
| State-Space Diagnostics | Transition, measurement, and stability analysis with a Kalman filter |
| State-Space Smoothing | Retrospective states and structural shocks via Hamilton (RTS) and Koopman disturbance smoothers, plus Durbin–Koopman and Carter–Kohn posterior draws |
| Nonlinear Filtering | Tempered particle filter (Herbst–Schorfheide) for likelihood evaluation of nonlinear resonance systems, plus fast Chandrasekhar recursions for linear ones |
| Phase-Transition Detection | Evidence for drift or abrupt changes in system behavior |
| Source | Description |
|---|---|
| Physics Systems | Coupled oscillators, Lorenz, Rössler, Heston, FitzHugh-Nagumo benchmarks |
| Policy Data | Tabular time-series from FRED, policy observables |
| Supervisory Panels | Banking data (FFIEC 002, FR Y-9C), institutional metrics |
| Custom Time-Series | Any multivariate numerical array |
- JSON — Structured analysis results
- CSV — Tableau-ready artifacts
- Markdown — Human-readable reports
- Plots — Visualization of resonance, rooting graphs, state-space
pip install drr-frameworkgit clone https://github.com/topherchris420/dynamic-resonance-rooting.git
cd dynamic-resonance-rooting
python -m pip install -e .For development tools:
python -m pip install -e ".[dev]"
pre-commit installfrom drr_framework import DynamicResonanceRooting, generate_coupled_oscillator
sampling_rate = 200.0
_, data = generate_coupled_oscillator(
sampling_rate=sampling_rate,
target_frequency_hz=12.5,
random_state=42,
)
drr = DynamicResonanceRooting(embedding_dim=3, tau=2, sampling_rate=sampling_rate)
results = drr.analyze_system(data, multivariate=True, window_size=256)
print(results["resonance_depths"])
print(results["rooting_analysis"]["significant_edges"])File: examples/physics_lab.py
Analyze coupled oscillator systems and benchmark generators:
- Lorenz attractor
- Rössler system
- Heston volatility model
- FitzHugh-Nagumo neurons
File: examples/policy_lab.py
Analyze tabular policy observables:
- Time-series from FRED
- Economic indicators
- Policy shock response
File: examples/supervisory_policy_lab.py
Federal Reserve banking supervision:
- FFIEC 002 / FR Y-9C data integration
- Institutional risk metrics
- Validation-readiness packets
- Tableau exports for executive dashboards
File: examples/state_space_lab.py
End-to-end state-space workflow — fit, Kalman filter, Koopman smooth (with structural shocks), Durbin–Koopman posterior bands, Chandrasekhar likelihood, and a tempered particle filter on a nonlinear observation.
File: examples/quickstart_resonance_export.py
Compact load-detect-export demonstration
The framework includes a specialized supervisory application for Federal Reserve oversight:
Real-time early-warning system for detecting non-linear liquidity panics ("Dash for Cash" loop) across Large Foreign Banking Organizations (LFBOs).
- Resonance Detection — Identifies hidden cyclical funding stress via Welch/FFT
- Rooting Analysis — Maps lead-lag structures between Treasury shocks and bank liquidity drains
- Composite Scoring — Resonance Depth combining spectral concentration, temporal persistence, phase coherence, amplitude stability
- Stress Simulation — 200 bps parallel rate shift (Full AOCI vs. Opt-Out)
layer1_regulatory_backend.py— Python/SQL regulatory backendlayer2_tableau_blueprint.twb— Tableau dashboard blueprinttableau_calculated_fields.py— Tableau calculated fieldstableau_output/— Generated CSV exports
Implements SR 11-7 Model Risk Management guidelines from the Federal Reserve.
dynamic-resonance-rooting/
├── src/drr_framework/ # Core package
│ ├── analysis.py # DynamicResonanceRooting class
│ ├── _spectral.py # Spectral analysis
│ ├── benchmarks.py # Benchmark generators
│ ├── datasets.py # Data adapters
│ ├── reporting.py # Export utilities
│ ├── state_space.py # State-space filter, Chandrasekhar recursions
│ ├── smoothers.py # Kalman & simulation smoothers
│ ├── particle_filter.py # Tempered particle filter (nonlinear)
│ ├── supervision.py # Supervisory components
│ └── validation_readiness.py # Validation packets
├── examples/ # Usage examples
│ ├── physics_lab.py
│ ├── policy_lab.py
│ ├── supervisory_policy_lab.py
│ └── quickstart_resonance_export.py
├── tests/ # Test suite
├── docs/ # Documentation
│ ├── architecture.md
│ ├── user-guide.md
│ ├── developer-guide.md
│ ├── api.md
│ └── faq.md
├── data/ # Datasets
├── results/ # Output artifacts
└── pyproject.toml # Package config
| Key | Description |
|---|---|
resonances |
Dominant frequencies and spectral evidence |
resonance_depths |
Scalar persistence/stability scores by dimension |
resonance_depth_details |
Component-level scores and confidence intervals |
rooting_analysis |
Directed lagged relationships and edge metadata |
state_space_analysis |
Transition, measurement, likelihood, stability, impulse-response |
Important: DRR outputs are research diagnostics. Domain conclusions require separate validation, calibration, and review.
- User Guide — Getting started
- Architecture — System design
- API Reference — Function documentation
- Developer Guide — Contributing
- FAQ — Common questions
- Reproducibility — Ensuring reproducible results
- Validation Readiness — Model validation
If you use DRR in your research, please cite:
@software{drr-framework,
author = {Christopher Woodyard},
title = {Dynamic Resonance Rooting (DRR) Framework},
url = {https://github.com/topherchris420/dynamic-resonance-rooting},
version = {4.3.0},
year = {2026}
}MIT License — see LICENSE file for details.
The state-space filtering and smoothing routines (state_space.py,
smoothers.py, particle_filter.py) are dependency-free NumPy ports of the
algorithms in the New York Fed's
StateSpaceRoutines.jl:
the Kalman filter and Chandrasekhar recursions, the Hamilton and Koopman
smoothers, the Durbin–Koopman and Carter–Kohn simulation smoothers, and the
tempered particle filter (Herbst & Schorfheide, 2019). DRR does not depend on
Julia; the ports let DRR use these methods natively in Python.
- Herbst, E. & Schorfheide, F. (2019). Tempered Particle Filtering. Journal of Econometrics.
- Durbin, J. & Koopman, S. J. (2012). Time Series Analysis by State Space Methods.
- Herbst, E. (2015). Using the "Chandrasekhar Recursions" for Likelihood Evaluation of DSGE Models.
- StateSpaceRoutines.jl
- FFIEC 002 Reports
- Federal Reserve Supervision
- SR 11-7: Model Risk Management