mdcheck 1.0.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mdcheck/__init__.py +42 -0
- mdcheck/cli.py +254 -0
- mdcheck/core/__init__.py +36 -0
- mdcheck/core/autocorrelation.py +178 -0
- mdcheck/core/bootstrap.py +83 -0
- mdcheck/core/drift.py +152 -0
- mdcheck/core/equilibration.py +193 -0
- mdcheck/core/replicas.py +197 -0
- mdcheck/core/scoring.py +216 -0
- mdcheck/parsers/__init__.py +14 -0
- mdcheck/parsers/amber_namd.py +87 -0
- mdcheck/parsers/generic.py +88 -0
- mdcheck/parsers/gromacs.py +101 -0
- mdcheck/reporters/__init__.py +13 -0
- mdcheck/reporters/html_report.py +360 -0
- mdcheck/reporters/manuscript_prep.py +109 -0
- mdcheck/reporters/plot_generator.py +157 -0
- mdcheck-1.0.0.dist-info/METADATA +195 -0
- mdcheck-1.0.0.dist-info/RECORD +23 -0
- mdcheck-1.0.0.dist-info/WHEEL +5 -0
- mdcheck-1.0.0.dist-info/entry_points.txt +2 -0
- mdcheck-1.0.0.dist-info/licenses/LICENSE +21 -0
- mdcheck-1.0.0.dist-info/top_level.txt +1 -0
mdcheck/__init__.py
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
"""
|
|
2
|
+
MDCheck: Automated Convergence, Statistical Inefficiency, and Reproducibility
|
|
3
|
+
Assessment for Molecular Dynamics Simulations.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
__version__ = "1.0.0"
|
|
7
|
+
__author__ = "Andre Monreal-Hernández"
|
|
8
|
+
__license__ = "MIT"
|
|
9
|
+
|
|
10
|
+
from mdcheck.core.autocorrelation import (
|
|
11
|
+
compute_autocorrelation,
|
|
12
|
+
integrated_autocorrelation_time,
|
|
13
|
+
effective_sample_size,
|
|
14
|
+
statistical_inefficiency
|
|
15
|
+
)
|
|
16
|
+
from mdcheck.core.equilibration import detect_equilibration, geweke_diagnostic
|
|
17
|
+
from mdcheck.core.replicas import (
|
|
18
|
+
assess_replica_consistency,
|
|
19
|
+
jensen_shannon_distance,
|
|
20
|
+
subspace_overlap_rmsip
|
|
21
|
+
)
|
|
22
|
+
from mdcheck.core.drift import assess_drift, block_averaging
|
|
23
|
+
from mdcheck.core.bootstrap import bootstrap_ci
|
|
24
|
+
from mdcheck.core.scoring import assess_trajectory_quality, SimulationQualityReport
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"__version__",
|
|
28
|
+
"compute_autocorrelation",
|
|
29
|
+
"integrated_autocorrelation_time",
|
|
30
|
+
"effective_sample_size",
|
|
31
|
+
"statistical_inefficiency",
|
|
32
|
+
"detect_equilibration",
|
|
33
|
+
"geweke_diagnostic",
|
|
34
|
+
"assess_replica_consistency",
|
|
35
|
+
"jensen_shannon_distance",
|
|
36
|
+
"subspace_overlap_rmsip",
|
|
37
|
+
"assess_drift",
|
|
38
|
+
"block_averaging",
|
|
39
|
+
"bootstrap_ci",
|
|
40
|
+
"assess_trajectory_quality",
|
|
41
|
+
"SimulationQualityReport"
|
|
42
|
+
]
|
mdcheck/cli.py
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Command Line Interface (CLI) for MDCheck.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
import sys
|
|
6
|
+
import os
|
|
7
|
+
import argparse
|
|
8
|
+
import numpy as np
|
|
9
|
+
|
|
10
|
+
from mdcheck import __version__
|
|
11
|
+
from mdcheck.parsers.generic import load_timeseries_file
|
|
12
|
+
from mdcheck.core.scoring import assess_trajectory_quality
|
|
13
|
+
from mdcheck.reporters.plot_generator import generate_publication_figures
|
|
14
|
+
from mdcheck.reporters.manuscript_prep import generate_manuscript_assets
|
|
15
|
+
from mdcheck.reporters.html_report import generate_html_report
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def print_banner():
|
|
19
|
+
banner = rf"""
|
|
20
|
+
__ __ _____ _____ _ _
|
|
21
|
+
| \/ | __ \ / ____| | | |
|
|
22
|
+
| \ / | | | | | | |__ ___ ___| | __
|
|
23
|
+
| |\/| | | | | | | '_ \ / _ \/ __| |/ /
|
|
24
|
+
| | | | |__| | |____| | | | __/ (__| <
|
|
25
|
+
|_| |_|_____/ \_____|_| |_|\___|\___|_|\_\ v{__version__}
|
|
26
|
+
|
|
27
|
+
Molecular Dynamics Convergence & Statistical Inefficiency Toolkit
|
|
28
|
+
Monreal-Hernández et al., 2026
|
|
29
|
+
"""
|
|
30
|
+
print(banner)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def run_demo(output_dir: str = "mdcheck_demo_output"):
|
|
34
|
+
"""
|
|
35
|
+
Generates a realistic 3-replica molecular dynamics dataset (RMSD, Radius of Gyration, Potential Energy)
|
|
36
|
+
and executes the full MDCheck assessment pipeline.
|
|
37
|
+
"""
|
|
38
|
+
print(f"\n[MDCheck] Running demonstration mode...")
|
|
39
|
+
os.makedirs(output_dir, exist_ok=True)
|
|
40
|
+
|
|
41
|
+
n_frames = 2000
|
|
42
|
+
time_coords = np.linspace(0.0, 100.0, n_frames) # 100 ns simulation
|
|
43
|
+
|
|
44
|
+
rng = np.random.default_rng(42)
|
|
45
|
+
|
|
46
|
+
# Simulate Replica 1, 2, 3
|
|
47
|
+
# Observable 1: RMSD (Equilibrating from 0.8 to 1.8 A over first 20 ns, then stable fluctuations)
|
|
48
|
+
def make_rmsd(seed):
|
|
49
|
+
r = np.random.default_rng(seed)
|
|
50
|
+
noise = np.zeros(n_frames)
|
|
51
|
+
# AR(1) correlated noise
|
|
52
|
+
phi = 0.85
|
|
53
|
+
for i in range(1, n_frames):
|
|
54
|
+
noise[i] = phi * noise[i-1] + np.sqrt(1 - phi**2) * r.normal(0, 0.08)
|
|
55
|
+
# Equilibration rise in first 400 frames (20 ns)
|
|
56
|
+
eq_curve = 1.0 * (1.0 - np.exp(-time_coords / 8.0)) + 0.8
|
|
57
|
+
return eq_curve + noise
|
|
58
|
+
|
|
59
|
+
# Observable 2: Radius of Gyration Rg (stable around 1.45 nm)
|
|
60
|
+
def make_rg(seed):
|
|
61
|
+
r = np.random.default_rng(seed)
|
|
62
|
+
noise = np.zeros(n_frames)
|
|
63
|
+
phi = 0.80
|
|
64
|
+
for i in range(1, n_frames):
|
|
65
|
+
noise[i] = phi * noise[i-1] + np.sqrt(1 - phi**2) * r.normal(0, 0.02)
|
|
66
|
+
eq_curve = 0.05 * np.exp(-time_coords / 5.0) + 1.45
|
|
67
|
+
return eq_curve + noise
|
|
68
|
+
|
|
69
|
+
r1_rmsd = make_rmsd(101)
|
|
70
|
+
r2_rmsd = make_rmsd(102)
|
|
71
|
+
r3_rmsd = make_rmsd(103)
|
|
72
|
+
|
|
73
|
+
r1_rg = make_rg(201)
|
|
74
|
+
r2_rg = make_rg(202)
|
|
75
|
+
r3_rg = make_rg(203)
|
|
76
|
+
|
|
77
|
+
primary_timeseries = {
|
|
78
|
+
"Backbone_RMSD": r1_rmsd,
|
|
79
|
+
"Radius_of_Gyration": r1_rg
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
replica_dict = {
|
|
83
|
+
"Backbone_RMSD": [r1_rmsd, r2_rmsd, r3_rmsd],
|
|
84
|
+
"Radius_of_Gyration": [r1_rg, r2_rg, r3_rg]
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
print(" -> Evaluating trajectory equilibration, autocorrelation, and replica overlap...")
|
|
88
|
+
report = assess_trajectory_quality(
|
|
89
|
+
timeseries_dict=primary_timeseries,
|
|
90
|
+
time_coords=time_coords,
|
|
91
|
+
replica_dict=replica_dict
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
# Generate assets
|
|
95
|
+
print(" -> Generating publication-ready vector figures (SVG/PDF/PNG)...")
|
|
96
|
+
generate_publication_figures(primary_timeseries, time_coords, report, output_dir, replica_dict=replica_dict)
|
|
97
|
+
|
|
98
|
+
print(" -> Formulating Methods text snippet, summary LaTeX tables, and BibTeX citations...")
|
|
99
|
+
text_assets = generate_manuscript_assets(report, output_dir)
|
|
100
|
+
|
|
101
|
+
with open(text_assets["methods_text"], "r", encoding="utf-8") as f:
|
|
102
|
+
methods_content = f.read()
|
|
103
|
+
with open(text_assets["citation_bib"], "r", encoding="utf-8") as f:
|
|
104
|
+
bib_content = f.read()
|
|
105
|
+
|
|
106
|
+
html_path = os.path.join(output_dir, "report.html")
|
|
107
|
+
print(f" -> Rendering interactive HTML report at {html_path}...")
|
|
108
|
+
generate_html_report(report, html_path, methods_text=methods_content, citation_bib=bib_content)
|
|
109
|
+
|
|
110
|
+
print("\n" + "="*70)
|
|
111
|
+
print(f" [RESULT] Overall Trajectory Certification: {report.overall_status}")
|
|
112
|
+
print(f" [SCORE] {report.score_summary}")
|
|
113
|
+
print("="*70)
|
|
114
|
+
for name, obs in report.observables.items():
|
|
115
|
+
print(f" * {name:20s}: t_eq = {obs.t_eq_time:5.2f} ns | N_eff = {obs.n_eff:6.0f} | Mean = {obs.mean_prod:.3f} [{obs.ci_lower_95:.3f}, {obs.ci_upper_95:.3f}] | Status: {obs.status}")
|
|
116
|
+
if report.replica_assessment:
|
|
117
|
+
print(f" * Multi-Replica Overlap : Mean JSD = {report.replica_assessment['mean_jsd']:.3f} | Status: {report.replica_assessment['status']}")
|
|
118
|
+
print("="*70)
|
|
119
|
+
print(f"\nAll outputs successfully saved to: {os.path.abspath(output_dir)}/")
|
|
120
|
+
print(f"Open {os.path.abspath(html_path)} in your browser to inspect the full report.\n")
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def run_assess(args):
|
|
124
|
+
"""
|
|
125
|
+
Executes assessment on user-provided input files.
|
|
126
|
+
"""
|
|
127
|
+
output_dir = args.output
|
|
128
|
+
os.makedirs(output_dir, exist_ok=True)
|
|
129
|
+
|
|
130
|
+
input_files = args.input
|
|
131
|
+
replica_files = args.replicas if args.replicas else []
|
|
132
|
+
|
|
133
|
+
if not input_files and not replica_files:
|
|
134
|
+
print("[Error] Please specify input files with --input or --replicas.", file=sys.stderr)
|
|
135
|
+
sys.exit(1)
|
|
136
|
+
|
|
137
|
+
all_files = input_files + replica_files
|
|
138
|
+
print(f"\n[MDCheck] Loading timeseries from {len(all_files)} file(s)...")
|
|
139
|
+
|
|
140
|
+
loaded_data = []
|
|
141
|
+
for fp in all_files:
|
|
142
|
+
t, s_dict, meta = load_timeseries_file(fp)
|
|
143
|
+
loaded_data.append((t, s_dict, meta, fp))
|
|
144
|
+
print(f" -> Loaded '{meta['title']}': {len(t)} frames, observables: {list(s_dict.keys())}")
|
|
145
|
+
|
|
146
|
+
primary_t, primary_dict, primary_meta, _ = loaded_data[0]
|
|
147
|
+
|
|
148
|
+
replica_dict = None
|
|
149
|
+
if len(loaded_data) > 1:
|
|
150
|
+
replica_dict = {}
|
|
151
|
+
for obs_name in primary_dict.keys():
|
|
152
|
+
rep_list = []
|
|
153
|
+
for _, s_dict, _, _ in loaded_data:
|
|
154
|
+
if obs_name in s_dict:
|
|
155
|
+
rep_list.append(s_dict[obs_name])
|
|
156
|
+
if len(rep_list) > 1:
|
|
157
|
+
replica_dict[obs_name] = rep_list
|
|
158
|
+
|
|
159
|
+
print("\n[MDCheck] Performing statistical convergence, equilibration, and inefficiency analysis...")
|
|
160
|
+
report = assess_trajectory_quality(
|
|
161
|
+
timeseries_dict=primary_dict,
|
|
162
|
+
time_coords=primary_t,
|
|
163
|
+
replica_dict=replica_dict
|
|
164
|
+
)
|
|
165
|
+
|
|
166
|
+
print(" -> Generating publication-quality vector charts...")
|
|
167
|
+
generate_publication_figures(primary_dict, primary_t, report, output_dir, replica_dict=replica_dict)
|
|
168
|
+
|
|
169
|
+
print(" -> Generating manuscript text, LaTeX summary table, and BibTeX citations...")
|
|
170
|
+
text_assets = generate_manuscript_assets(report, output_dir)
|
|
171
|
+
|
|
172
|
+
with open(text_assets["methods_text"], "r", encoding="utf-8") as f:
|
|
173
|
+
methods_content = f.read()
|
|
174
|
+
with open(text_assets["citation_bib"], "r", encoding="utf-8") as f:
|
|
175
|
+
bib_content = f.read()
|
|
176
|
+
|
|
177
|
+
html_path = os.path.join(output_dir, "report.html")
|
|
178
|
+
print(f" -> Writing HTML quality report to {html_path}...")
|
|
179
|
+
generate_html_report(report, html_path, methods_text=methods_content, citation_bib=bib_content)
|
|
180
|
+
|
|
181
|
+
print("\n" + "="*70)
|
|
182
|
+
print(f" [RESULT] Overall Trajectory Certification: {report.overall_status}")
|
|
183
|
+
print(f" [SCORE] {report.score_summary}")
|
|
184
|
+
print("="*70)
|
|
185
|
+
for name, obs in report.observables.items():
|
|
186
|
+
print(f" * {name:20s}: t_eq = {obs.t_eq_time:5.2f} | N_eff = {obs.n_eff:6.0f} | Mean = {obs.mean_prod:.3f} [{obs.ci_lower_95:.3f}, {obs.ci_upper_95:.3f}] | Status: {obs.status}")
|
|
187
|
+
if report.replica_assessment:
|
|
188
|
+
print(f" * Multi-Replica Overlap : Mean JSD = {report.replica_assessment['mean_jsd']:.3f} | Status: {report.replica_assessment['status']}")
|
|
189
|
+
print("="*70)
|
|
190
|
+
print(f"\nReport ready at: {os.path.abspath(html_path)}\n")
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
def print_citation():
|
|
194
|
+
bib = """@software{monreal2026mdcheck,
|
|
195
|
+
author = {Monreal-Hern\\'andez, Andre},
|
|
196
|
+
title = {{MDCheck: Automated Convergence, Statistical Inefficiency, and Reproducibility Assessment for Molecular Dynamics Simulations}},
|
|
197
|
+
year = {2026},
|
|
198
|
+
version = {1.0.0},
|
|
199
|
+
publisher = {Zenodo},
|
|
200
|
+
url = {https://github.com/sircalch/mdcheck}
|
|
201
|
+
}"""
|
|
202
|
+
print("\nIf you use MDCheck in your publications, please cite:\n")
|
|
203
|
+
print("APA Style:")
|
|
204
|
+
print("Monreal-Hernández, A. (2026). MDCheck: Automated Convergence, Statistical Inefficiency, and Reproducibility Assessment for Molecular Dynamics Simulations (v1.0.0). Zenodo. https://github.com/sircalch/mdcheck\n")
|
|
205
|
+
print("BibTeX:")
|
|
206
|
+
print(bib)
|
|
207
|
+
print()
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def main():
|
|
211
|
+
parser = argparse.ArgumentParser(
|
|
212
|
+
prog="mdcheck",
|
|
213
|
+
description="MDCheck: Automated Convergence, Statistical Inefficiency, and Reproducibility Assessment for Molecular Dynamics Simulations."
|
|
214
|
+
)
|
|
215
|
+
parser.add_argument("-v", "--version", action="version", version=f"mdcheck {__version__}")
|
|
216
|
+
|
|
217
|
+
subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
|
|
218
|
+
|
|
219
|
+
# Assess command
|
|
220
|
+
assess_parser = subparsers.add_parser("assess", help="Assess trajectory convergence, equilibration, and reproducibility")
|
|
221
|
+
assess_parser.add_argument("-i", "--input", nargs="+", help="Primary trajectory timeseries file(s) (.xvg, .csv, .dat, .txt)")
|
|
222
|
+
assess_parser.add_argument("-r", "--replicas", nargs="+", help="Multi-replica files for consistency comparison")
|
|
223
|
+
assess_parser.add_argument("-o", "--output", default="mdcheck_output", help="Directory to save report, plots, and manuscript assets (default: mdcheck_output)")
|
|
224
|
+
|
|
225
|
+
# Demo command
|
|
226
|
+
demo_parser = subparsers.add_parser("demo", help="Run MDCheck on a synthetic multi-replica simulation dataset")
|
|
227
|
+
demo_parser.add_argument("-o", "--output", default="mdcheck_demo_output", help="Output directory (default: mdcheck_demo_output)")
|
|
228
|
+
|
|
229
|
+
# Cite command
|
|
230
|
+
subparsers.add_parser("cite", help="Display BibTeX and APA citation details")
|
|
231
|
+
|
|
232
|
+
if len(sys.argv) == 1:
|
|
233
|
+
print_banner()
|
|
234
|
+
parser.print_help()
|
|
235
|
+
sys.exit(0)
|
|
236
|
+
|
|
237
|
+
args = parser.parse_args()
|
|
238
|
+
|
|
239
|
+
if args.command == "assess":
|
|
240
|
+
print_banner()
|
|
241
|
+
run_assess(args)
|
|
242
|
+
elif args.command == "demo":
|
|
243
|
+
print_banner()
|
|
244
|
+
run_demo(args.output)
|
|
245
|
+
elif args.command == "cite":
|
|
246
|
+
print_banner()
|
|
247
|
+
print_citation()
|
|
248
|
+
else:
|
|
249
|
+
parser.print_help()
|
|
250
|
+
|
|
251
|
+
|
|
252
|
+
if __name__ == "__main__":
|
|
253
|
+
main()
|
|
254
|
+
|
mdcheck/core/__init__.py
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""
|
|
2
|
+
MDCheck core statistical and convergence algorithms.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from mdcheck.core.autocorrelation import (
|
|
6
|
+
compute_autocorrelation,
|
|
7
|
+
integrated_autocorrelation_time,
|
|
8
|
+
effective_sample_size,
|
|
9
|
+
statistical_inefficiency
|
|
10
|
+
)
|
|
11
|
+
from mdcheck.core.equilibration import detect_equilibration, geweke_diagnostic
|
|
12
|
+
from mdcheck.core.replicas import (
|
|
13
|
+
assess_replica_consistency,
|
|
14
|
+
jensen_shannon_distance,
|
|
15
|
+
subspace_overlap_rmsip
|
|
16
|
+
)
|
|
17
|
+
from mdcheck.core.drift import assess_drift, block_averaging
|
|
18
|
+
from mdcheck.core.bootstrap import bootstrap_ci
|
|
19
|
+
from mdcheck.core.scoring import assess_trajectory_quality, SimulationQualityReport
|
|
20
|
+
|
|
21
|
+
__all__ = [
|
|
22
|
+
"compute_autocorrelation",
|
|
23
|
+
"integrated_autocorrelation_time",
|
|
24
|
+
"effective_sample_size",
|
|
25
|
+
"statistical_inefficiency",
|
|
26
|
+
"detect_equilibration",
|
|
27
|
+
"geweke_diagnostic",
|
|
28
|
+
"assess_replica_consistency",
|
|
29
|
+
"jensen_shannon_distance",
|
|
30
|
+
"subspace_overlap_rmsip",
|
|
31
|
+
"assess_drift",
|
|
32
|
+
"block_averaging",
|
|
33
|
+
"bootstrap_ci",
|
|
34
|
+
"assess_trajectory_quality",
|
|
35
|
+
"SimulationQualityReport"
|
|
36
|
+
]
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Integrated autocorrelation time, statistical inefficiency, and effective sample size.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from typing import Tuple, Optional
|
|
6
|
+
import numpy as np
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
def compute_autocorrelation(series: np.ndarray, max_lag: Optional[int] = None) -> np.ndarray:
|
|
10
|
+
"""
|
|
11
|
+
Computes the normalized autocorrelation function (ACF) of a 1D timeseries using FFT.
|
|
12
|
+
|
|
13
|
+
Parameters
|
|
14
|
+
----------
|
|
15
|
+
series : np.ndarray
|
|
16
|
+
1D array of timeseries values.
|
|
17
|
+
max_lag : int, optional
|
|
18
|
+
Maximum lag to compute. If None, computes for all possible lags.
|
|
19
|
+
|
|
20
|
+
Returns
|
|
21
|
+
-------
|
|
22
|
+
acf : np.ndarray
|
|
23
|
+
Normalized autocorrelation function with acf[0] = 1.0.
|
|
24
|
+
"""
|
|
25
|
+
x = np.asarray(series, dtype=np.float64)
|
|
26
|
+
if x.ndim != 1:
|
|
27
|
+
x = x.ravel()
|
|
28
|
+
|
|
29
|
+
n = len(x)
|
|
30
|
+
if n <= 1:
|
|
31
|
+
return np.array([1.0], dtype=np.float64)
|
|
32
|
+
|
|
33
|
+
x_mean = np.mean(x)
|
|
34
|
+
x_zero_mean = x - x_mean
|
|
35
|
+
variance = np.var(x, ddof=0)
|
|
36
|
+
|
|
37
|
+
if variance == 0 or np.isnan(variance):
|
|
38
|
+
return np.ones(max_lag if max_lag else n, dtype=np.float64)
|
|
39
|
+
|
|
40
|
+
# Zero-padding for linear autocorrelation via FFT
|
|
41
|
+
n_fft = 2 ** int(np.ceil(np.log2(2 * n - 1)))
|
|
42
|
+
fx = np.fft.fft(x_zero_mean, n=n_fft)
|
|
43
|
+
px = fx * np.conjugate(fx)
|
|
44
|
+
autocov = np.fft.ifft(px).real[:n]
|
|
45
|
+
|
|
46
|
+
# Scale by sample count at each lag for unbiased/consistent estimator
|
|
47
|
+
lags = np.arange(n)
|
|
48
|
+
denom = (n - lags) * variance
|
|
49
|
+
acf = autocov / denom
|
|
50
|
+
|
|
51
|
+
# Normalization guarantee
|
|
52
|
+
if acf[0] != 0:
|
|
53
|
+
acf = acf / acf[0]
|
|
54
|
+
else:
|
|
55
|
+
acf[0] = 1.0
|
|
56
|
+
|
|
57
|
+
if max_lag is not None and max_lag < n:
|
|
58
|
+
acf = acf[:max_lag + 1]
|
|
59
|
+
|
|
60
|
+
return acf
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def integrated_autocorrelation_time(
|
|
64
|
+
series: np.ndarray,
|
|
65
|
+
c_window: float = 6.0,
|
|
66
|
+
max_lag: Optional[int] = None
|
|
67
|
+
) -> Tuple[float, float, int]:
|
|
68
|
+
"""
|
|
69
|
+
Calculates the integrated autocorrelation time (tau_int) using a self-consistent
|
|
70
|
+
Madras-Sokal windowing procedure.
|
|
71
|
+
|
|
72
|
+
Formula:
|
|
73
|
+
tau_int = 0.5 + sum_{k=1}^M C(k)
|
|
74
|
+
where M is the smallest integer such that M >= c_window * tau_int.
|
|
75
|
+
|
|
76
|
+
Parameters
|
|
77
|
+
----------
|
|
78
|
+
series : np.ndarray
|
|
79
|
+
1D timeseries array.
|
|
80
|
+
c_window : float, default 6.0
|
|
81
|
+
Madras-Sokal window parameter (typically between 4.0 and 8.0).
|
|
82
|
+
max_lag : int, optional
|
|
83
|
+
Maximum lag to explore.
|
|
84
|
+
|
|
85
|
+
Returns
|
|
86
|
+
-------
|
|
87
|
+
tau_int : float
|
|
88
|
+
Integrated autocorrelation time in units of steps/frames.
|
|
89
|
+
g : float
|
|
90
|
+
Statistical inefficiency factor g = 1 + 2 * tau_int.
|
|
91
|
+
window_m : int
|
|
92
|
+
Window cutoff index M.
|
|
93
|
+
"""
|
|
94
|
+
x = np.asarray(series, dtype=np.float64)
|
|
95
|
+
n = len(x)
|
|
96
|
+
|
|
97
|
+
if n < 4:
|
|
98
|
+
return 0.5, 1.0, 0
|
|
99
|
+
|
|
100
|
+
if max_lag is None:
|
|
101
|
+
max_lag = min(n // 2, 50000)
|
|
102
|
+
|
|
103
|
+
acf = compute_autocorrelation(x, max_lag=max_lag)
|
|
104
|
+
|
|
105
|
+
# Initial estimate
|
|
106
|
+
tau_int = 0.5
|
|
107
|
+
window_m = 0
|
|
108
|
+
|
|
109
|
+
for k in range(1, len(acf)):
|
|
110
|
+
# Stop if autocorrelation becomes negative or noise-dominated
|
|
111
|
+
if acf[k] < 0:
|
|
112
|
+
window_m = k
|
|
113
|
+
break
|
|
114
|
+
|
|
115
|
+
tau_int += acf[k]
|
|
116
|
+
|
|
117
|
+
# Self-consistent window check: M >= c * tau_int
|
|
118
|
+
if k >= c_window * tau_int:
|
|
119
|
+
window_m = k
|
|
120
|
+
break
|
|
121
|
+
else:
|
|
122
|
+
window_m = len(acf) - 1
|
|
123
|
+
|
|
124
|
+
# Bounds guarantee
|
|
125
|
+
tau_int = max(0.5, float(tau_int))
|
|
126
|
+
g = max(1.0, float(1.0 + 2.0 * (tau_int - 0.5)))
|
|
127
|
+
|
|
128
|
+
return tau_int, g, int(window_m)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def statistical_inefficiency(series: np.ndarray, c_window: float = 6.0) -> float:
|
|
132
|
+
"""
|
|
133
|
+
Calculates the statistical inefficiency factor g.
|
|
134
|
+
|
|
135
|
+
Parameters
|
|
136
|
+
----------
|
|
137
|
+
series : np.ndarray
|
|
138
|
+
1D timeseries array.
|
|
139
|
+
c_window : float
|
|
140
|
+
Window parameter.
|
|
141
|
+
|
|
142
|
+
Returns
|
|
143
|
+
-------
|
|
144
|
+
g : float
|
|
145
|
+
Statistical inefficiency g = 1 + 2*tau_int.
|
|
146
|
+
"""
|
|
147
|
+
_, g, _ = integrated_autocorrelation_time(series, c_window=c_window)
|
|
148
|
+
return g
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def effective_sample_size(series: np.ndarray, c_window: float = 6.0) -> Tuple[float, float, float]:
|
|
152
|
+
"""
|
|
153
|
+
Computes effective sample size N_eff = N / g.
|
|
154
|
+
|
|
155
|
+
Parameters
|
|
156
|
+
----------
|
|
157
|
+
series : np.ndarray
|
|
158
|
+
1D timeseries array.
|
|
159
|
+
c_window : float
|
|
160
|
+
Madras-Sokal window parameter.
|
|
161
|
+
|
|
162
|
+
Returns
|
|
163
|
+
-------
|
|
164
|
+
n_eff : float
|
|
165
|
+
Effective number of uncorrelated samples.
|
|
166
|
+
tau_int : float
|
|
167
|
+
Integrated autocorrelation time.
|
|
168
|
+
g : float
|
|
169
|
+
Statistical inefficiency factor.
|
|
170
|
+
"""
|
|
171
|
+
x = np.asarray(series, dtype=np.float64)
|
|
172
|
+
n = len(x)
|
|
173
|
+
if n == 0:
|
|
174
|
+
return 0.0, 0.5, 1.0
|
|
175
|
+
|
|
176
|
+
tau_int, g, _ = integrated_autocorrelation_time(x, c_window=c_window)
|
|
177
|
+
n_eff = float(n) / max(1.0, g)
|
|
178
|
+
return n_eff, tau_int, g
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Block bootstrap and non-parametric confidence interval estimation.
|
|
3
|
+
"""
|
|
4
|
+
|
|
5
|
+
from typing import Tuple, Callable, Optional
|
|
6
|
+
import numpy as np
|
|
7
|
+
from mdcheck.core.autocorrelation import integrated_autocorrelation_time
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
def bootstrap_ci(
|
|
11
|
+
series: np.ndarray,
|
|
12
|
+
stat_func: Callable[[np.ndarray], float] = np.mean,
|
|
13
|
+
n_resamples: int = 2000,
|
|
14
|
+
confidence_level: float = 0.95,
|
|
15
|
+
block_size: Optional[int] = None,
|
|
16
|
+
random_state: Optional[int] = 42
|
|
17
|
+
) -> Tuple[float, float, float]:
|
|
18
|
+
"""
|
|
19
|
+
Computes moving-block bootstrap confidence intervals accounting for autocorrelation.
|
|
20
|
+
|
|
21
|
+
Parameters
|
|
22
|
+
----------
|
|
23
|
+
series : np.ndarray
|
|
24
|
+
1D timeseries array.
|
|
25
|
+
stat_func : callable, default np.mean
|
|
26
|
+
Function computing the target statistic on a 1D array.
|
|
27
|
+
n_resamples : int, default 2000
|
|
28
|
+
Number of bootstrap resamples.
|
|
29
|
+
confidence_level : float, default 0.95
|
|
30
|
+
Confidence level (e.g. 0.95 for 95% CI).
|
|
31
|
+
block_size : int, optional
|
|
32
|
+
Block length. If None, automatically determined as int(2 * tau_int + 1).
|
|
33
|
+
random_state : int, optional
|
|
34
|
+
Random seed for reproducibility.
|
|
35
|
+
|
|
36
|
+
Returns
|
|
37
|
+
-------
|
|
38
|
+
point_estimate : float
|
|
39
|
+
Observed sample statistic.
|
|
40
|
+
ci_lower : float
|
|
41
|
+
Lower bound of bootstrap confidence interval.
|
|
42
|
+
ci_upper : float
|
|
43
|
+
Upper bound of bootstrap confidence interval.
|
|
44
|
+
"""
|
|
45
|
+
x = np.asarray(series, dtype=np.float64)
|
|
46
|
+
n = len(x)
|
|
47
|
+
|
|
48
|
+
if n == 0:
|
|
49
|
+
return 0.0, 0.0, 0.0
|
|
50
|
+
|
|
51
|
+
point_estimate = float(stat_func(x))
|
|
52
|
+
|
|
53
|
+
if n < 5:
|
|
54
|
+
return point_estimate, point_estimate, point_estimate
|
|
55
|
+
|
|
56
|
+
if block_size is None:
|
|
57
|
+
tau_int, _, _ = integrated_autocorrelation_time(x)
|
|
58
|
+
block_size = max(1, int(np.ceil(2.0 * tau_int)))
|
|
59
|
+
|
|
60
|
+
rng = np.random.default_rng(random_state)
|
|
61
|
+
|
|
62
|
+
if block_size <= 1:
|
|
63
|
+
# Standard i.i.d. bootstrap
|
|
64
|
+
resample_indices = rng.integers(0, n, size=(n_resamples, n))
|
|
65
|
+
resamples = x[resample_indices]
|
|
66
|
+
boot_stats = np.apply_along_axis(stat_func, 1, resamples)
|
|
67
|
+
else:
|
|
68
|
+
# Moving block bootstrap
|
|
69
|
+
n_blocks = int(np.ceil(n / block_size))
|
|
70
|
+
max_start = n - block_size + 1
|
|
71
|
+
|
|
72
|
+
boot_stats = np.empty(n_resamples, dtype=np.float64)
|
|
73
|
+
for b in range(n_resamples):
|
|
74
|
+
start_indices = rng.integers(0, max_start, size=n_blocks)
|
|
75
|
+
sampled_blocks = np.concatenate([x[idx : idx + block_size] for idx in start_indices])
|
|
76
|
+
sampled_series = sampled_blocks[:n]
|
|
77
|
+
boot_stats[b] = stat_func(sampled_series)
|
|
78
|
+
|
|
79
|
+
alpha = (1.0 - confidence_level) / 2.0
|
|
80
|
+
ci_lower = float(np.percentile(boot_stats, 100.0 * alpha))
|
|
81
|
+
ci_upper = float(np.percentile(boot_stats, 100.0 * (1.0 - alpha)))
|
|
82
|
+
|
|
83
|
+
return point_estimate, ci_lower, ci_upper
|