pme-toolkit 1.2.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.
@@ -0,0 +1,55 @@
1
+ """
2
+ PME-toolkit Python package.
3
+
4
+ This package provides the Python implementation of the PME-toolkit
5
+ workflow, including PME, PI-PME, and PD-PME utilities.
6
+
7
+ The MATLAB implementation remains the project reference implementation.
8
+ """
9
+
10
+ from .config_loader import load_case_json, load_config
11
+ from .layout import parse_layout
12
+ from .io import load_mat_database, load_mat_range
13
+ from .model import PmeModel, fit_from_case, fit_model, fit_pme
14
+ from .report import build_report, print_report
15
+ from .plotting import (
16
+ plot_scree_plot,
17
+ plot_variance_retained,
18
+ plot_nmse_by_source,
19
+ plot_variance_by_source,
20
+ plot_variable_modes,
21
+ plot_modes,
22
+ save_all_plots,
23
+ source_colors,
24
+ )
25
+ from .filters import apply_filters, FilterResult
26
+ from .weights import build_weights, build_wf, build_wc
27
+ from .datasets import ensure_case_inputs
28
+
29
+ __all__ = [
30
+ "load_case_json",
31
+ "load_config",
32
+ "parse_layout",
33
+ "load_mat_database",
34
+ "load_mat_range",
35
+ "PmeModel",
36
+ "fit_model",
37
+ "fit_pme",
38
+ "fit_from_case",
39
+ "build_report",
40
+ "print_report",
41
+ "plot_scree_plot",
42
+ "plot_variance_retained",
43
+ "plot_nmse_by_source",
44
+ "plot_variance_by_source",
45
+ "plot_variable_modes",
46
+ "plot_modes",
47
+ "save_all_plots",
48
+ "source_colors",
49
+ "apply_filters",
50
+ "FilterResult",
51
+ "build_weights",
52
+ "build_wf",
53
+ "build_wc",
54
+ "ensure_case_inputs",
55
+ ]
@@ -0,0 +1,46 @@
1
+ import json
2
+ from pathlib import Path
3
+ import numpy as np
4
+
5
+
6
+ def backmapping(model, x, active_idx=None):
7
+ """
8
+ Perform PME backmapping from reduced variables x to original variables u.
9
+
10
+ Parameters
11
+ ----------
12
+ model : PMEModel
13
+ Trained PME model.
14
+ x : array_like
15
+ Reduced variables (Ndim,)
16
+ active_idx : array_like or None
17
+ Indices of active variables. If None all variables assumed active.
18
+
19
+ Returns
20
+ -------
21
+ u : ndarray
22
+ Reconstructed original variables.
23
+ """
24
+
25
+ x = np.asarray(x)
26
+
27
+ if active_idx is None:
28
+ u = model.inverse_full(x)
29
+ else:
30
+ u = model.inverse_active(x, active_idx)
31
+
32
+ return u
33
+
34
+
35
+ def run_backmapping(model, x, output_file=None):
36
+ """
37
+ Run backmapping and optionally save result.
38
+ """
39
+
40
+ u = backmapping(model, x)
41
+
42
+ if output_file is not None:
43
+ output_file = Path(output_file)
44
+ np.savetxt(output_file, u)
45
+
46
+ return u
pme_toolkit/cli.py ADDED
@@ -0,0 +1,26 @@
1
+ import argparse
2
+
3
+ from .run_case import main as run_case_main
4
+ from .run_back import main as run_back_main
5
+
6
+
7
+ def main():
8
+ parser = argparse.ArgumentParser(prog="pme-toolkit")
9
+ subparsers = parser.add_subparsers(dest="command", required=True)
10
+
11
+ run_parser = subparsers.add_parser("run", help="Run a PME case from case.json")
12
+ run_parser.add_argument("config", help="Path to case.json")
13
+
14
+ back_parser = subparsers.add_parser("back", help="Run backmapping from backmapping.json")
15
+ back_parser.add_argument("config", help="Path to backmapping.json")
16
+
17
+ args = parser.parse_args()
18
+
19
+ if args.command == "run":
20
+ run_case_main(args.config)
21
+ elif args.command == "back":
22
+ run_back_main(args.config)
23
+
24
+
25
+ if __name__ == "__main__":
26
+ main()
@@ -0,0 +1,66 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from pathlib import Path
5
+ from typing import Any
6
+
7
+
8
+ def _resolve_path(base_dir: Path, value: str | None) -> str | None:
9
+ """Resolve a possibly-relative path against the case.json directory."""
10
+ if value is None or value == "":
11
+ return None
12
+
13
+ path = Path(value).expanduser()
14
+ if path.is_absolute():
15
+ return str(path.resolve())
16
+
17
+ return str((base_dir / path).resolve())
18
+
19
+
20
+ def _resolve_case_paths(cfg: dict[str, Any], base_dir: Path) -> dict[str, Any]:
21
+ """Resolve the path-like fields used by the current repository schema."""
22
+ out = dict(cfg)
23
+
24
+ io_cfg = dict(out.get("io", {}) or {})
25
+ if "dbfile" in io_cfg:
26
+ io_cfg["dbfile"] = _resolve_path(base_dir, io_cfg.get("dbfile"))
27
+ if "outdir" in io_cfg and io_cfg.get("outdir"):
28
+ io_cfg["outdir"] = _resolve_path(base_dir, io_cfg.get("outdir"))
29
+ out["io"] = io_cfg
30
+
31
+ vars_cfg = dict(out.get("vars", {}) or {})
32
+ if "Urange_file" in vars_cfg:
33
+ vars_cfg["Urange_file"] = _resolve_path(base_dir, vars_cfg.get("Urange_file"))
34
+ out["vars"] = vars_cfg
35
+
36
+ return out
37
+
38
+
39
+ def load_case_json(case_json: str | Path) -> tuple[dict[str, Any], Path]:
40
+ """Load a case.json file and resolve repository-relative paths.
41
+
42
+ Returns
43
+ -------
44
+ cfg
45
+ Parsed JSON configuration with resolved paths.
46
+ base_dir
47
+ Directory containing case.json.
48
+ """
49
+ case_path = Path(case_json).expanduser().resolve()
50
+ if not case_path.is_file():
51
+ raise FileNotFoundError(f"case.json not found: {case_path}")
52
+
53
+ cfg = json.loads(case_path.read_text(encoding="utf-8"))
54
+ if not isinstance(cfg, dict):
55
+ raise TypeError("case.json must decode to a JSON object")
56
+
57
+ base_dir = case_path.parent
58
+ cfg = _resolve_case_paths(cfg, base_dir)
59
+
60
+ return cfg, base_dir
61
+
62
+
63
+ def load_config(case_json: str | Path) -> dict[str, Any]:
64
+ """Compatibility wrapper for the earlier scaffold test."""
65
+ cfg, _ = load_case_json(case_json)
66
+ return cfg
@@ -0,0 +1,268 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ import shutil
5
+ import zipfile
6
+ from pathlib import Path
7
+ from typing import Any
8
+ from urllib.request import urlopen
9
+
10
+
11
+ def _resolve_required_paths(cfg: dict[str, Any]) -> tuple[Path | None, Path | None]:
12
+ io_cfg = dict(cfg.get("io", {}) or {})
13
+ vars_cfg = dict(cfg.get("vars", {}) or {})
14
+
15
+ dbfile = io_cfg.get("dbfile")
16
+ urange_file = vars_cfg.get("Urange_file")
17
+
18
+ db_path = Path(dbfile).expanduser().resolve() if dbfile else None
19
+ ur_path = Path(urange_file).expanduser().resolve() if urange_file else None
20
+
21
+ return db_path, ur_path
22
+
23
+
24
+ def _all_required_exist(cfg: dict[str, Any]) -> tuple[bool, list[str]]:
25
+ db_path, ur_path = _resolve_required_paths(cfg)
26
+
27
+ missing: list[str] = []
28
+
29
+ if db_path is None or not db_path.is_file():
30
+ missing.append("dbfile")
31
+
32
+ if ur_path is not None and not ur_path.is_file():
33
+ missing.append("Urange_file")
34
+
35
+ return len(missing) == 0, missing
36
+
37
+
38
+ def _candidate_dataset_json_paths(cfg: dict[str, Any], base_dir: Path) -> list[Path]:
39
+ """
40
+ Search for dataset.json in the most relevant locations.
41
+
42
+ Priority:
43
+ 1. case directory and its parents
44
+ 2. parent directories of the expected dbfile path
45
+ 3. parent directories of the expected Urange_file path
46
+ """
47
+ candidates: list[Path] = []
48
+
49
+ # ---------------------------------------------------------
50
+ # (A) walk upward from the case directory
51
+ # ---------------------------------------------------------
52
+ cur = base_dir.resolve()
53
+ for parent in [cur] + list(cur.parents):
54
+ p = parent / "dataset.json"
55
+ if p.is_file():
56
+ candidates.append(p)
57
+
58
+ # ---------------------------------------------------------
59
+ # (B) walk upward from expected dbfile location
60
+ # ---------------------------------------------------------
61
+ db_path, ur_path = _resolve_required_paths(cfg)
62
+
63
+ if db_path is not None:
64
+ for parent in [db_path.parent] + list(db_path.parent.parents):
65
+ p = parent / "dataset.json"
66
+ if p.is_file():
67
+ candidates.append(p)
68
+
69
+ # ---------------------------------------------------------
70
+ # (C) walk upward from expected Urange_file location
71
+ # ---------------------------------------------------------
72
+ if ur_path is not None:
73
+ for parent in [ur_path.parent] + list(ur_path.parent.parents):
74
+ p = parent / "dataset.json"
75
+ if p.is_file():
76
+ candidates.append(p)
77
+
78
+ # unique while preserving order
79
+ uniq: list[Path] = []
80
+ seen = set()
81
+ for p in candidates:
82
+ rp = p.resolve()
83
+ if rp not in seen:
84
+ uniq.append(rp)
85
+ seen.add(rp)
86
+
87
+ return uniq
88
+
89
+ def _load_dataset_json(dataset_json: Path) -> dict[str, Any]:
90
+ data = json.loads(dataset_json.read_text(encoding="utf-8"))
91
+ if not isinstance(data, dict):
92
+ raise TypeError(f"dataset.json must decode to a JSON object: {dataset_json}")
93
+ return data
94
+
95
+
96
+ def _resolve_dataset_dir(meta: dict[str, Any], dataset_json: Path) -> Path:
97
+ """
98
+ Decide where the shared dataset lives.
99
+
100
+ Priority:
101
+ 1. meta["shared_dataset_dir"]
102
+ 2. directory containing dataset.json
103
+ """
104
+ shared = meta.get("shared_dataset_dir")
105
+ if shared:
106
+ return Path(shared).expanduser().resolve()
107
+
108
+ return dataset_json.parent.resolve()
109
+
110
+
111
+ def _download_with_progress(url: str, dst: Path) -> None:
112
+ print(f"[dataset] archive url: {url}")
113
+ print("[dataset] downloading archive...")
114
+
115
+ with urlopen(url) as response:
116
+ total = response.headers.get("Content-Length")
117
+ total_bytes = int(total) if total is not None else None
118
+
119
+ if total_bytes is not None:
120
+ size_mb = total_bytes / (1024 * 1024)
121
+ print(f"[dataset] size {size_mb:.1f} MB")
122
+
123
+ dst.parent.mkdir(parents=True, exist_ok=True)
124
+
125
+ chunk_size = 1024 * 1024
126
+ downloaded = 0
127
+
128
+ with dst.open("wb") as f:
129
+ while True:
130
+ chunk = response.read(chunk_size)
131
+ if not chunk:
132
+ break
133
+ f.write(chunk)
134
+ downloaded += len(chunk)
135
+
136
+ if total_bytes:
137
+ pct = 100.0 * downloaded / total_bytes
138
+ dl_mb = downloaded / (1024 * 1024)
139
+ tot_mb = total_bytes / (1024 * 1024)
140
+ print(f"[dataset] downloaded {pct:6.2f} % ({dl_mb:.1f} / {tot_mb:.1f} MB)")
141
+ else:
142
+ dl_mb = downloaded / (1024 * 1024)
143
+ print(f"[dataset] downloaded {dl_mb:.1f} MB")
144
+
145
+ print(f"[dataset] archive saved to: {dst}")
146
+
147
+
148
+ def _extract_archive(archive_path: Path, dataset_dir: Path) -> None:
149
+ print("[dataset] extracting archive...")
150
+ with zipfile.ZipFile(archive_path, "r") as zf:
151
+ zf.extractall(dataset_dir)
152
+ print(f"[dataset] extracted to: {dataset_dir}")
153
+
154
+
155
+ def _flatten_extracted_tree(dataset_dir: Path) -> None:
156
+ """
157
+ Move .mat/.txt/.json files from nested folders into dataset_dir when needed.
158
+ This mirrors the MATLAB behavior of tolerating archives with an extra top-level folder.
159
+ """
160
+ movable_suffixes = {".mat", ".txt", ".json", ".csv"}
161
+
162
+ nested_files = []
163
+ for p in dataset_dir.rglob("*"):
164
+ if not p.is_file():
165
+ continue
166
+ if p.parent == dataset_dir:
167
+ continue
168
+ if p.suffix.lower() in movable_suffixes:
169
+ nested_files.append(p)
170
+
171
+ if not nested_files:
172
+ return
173
+
174
+ print("[dataset] flattening extracted files...")
175
+ for src in nested_files:
176
+ dst = dataset_dir / src.name
177
+ if dst.exists():
178
+ continue
179
+ shutil.move(str(src), str(dst))
180
+
181
+ # attempt to remove empty directories
182
+ for p in sorted(dataset_dir.rglob("*"), reverse=True):
183
+ if p.is_dir():
184
+ try:
185
+ p.rmdir()
186
+ except OSError:
187
+ pass
188
+
189
+
190
+ def _find_dataset_json_or_raise(cfg: dict[str, Any], base_dir: Path) -> Path:
191
+ candidates = _candidate_dataset_json_paths(cfg, base_dir)
192
+ if not candidates:
193
+ raise FileNotFoundError(
194
+ "[dataset] dataset.json not found near case directory or expected dataset paths: "
195
+ f"{base_dir}"
196
+ )
197
+ return candidates[0]
198
+
199
+ def ensure_case_inputs(cfg: dict[str, Any], base_dir: Path) -> dict[str, Any]:
200
+ """
201
+ Ensure that dbfile and Urange_file exist.
202
+
203
+ If they are missing, try to recover them from dataset.json by:
204
+ - reading archive_url / archive_name
205
+ - downloading the archive
206
+ - extracting it
207
+ - flattening extracted files
208
+ - rechecking inputs
209
+
210
+ Returns
211
+ -------
212
+ meta : dict
213
+ Dataset metadata actually used (possibly empty if no download needed).
214
+ """
215
+ ok, missing = _all_required_exist(cfg)
216
+ if ok:
217
+ print("[dataset] all required inputs already available.")
218
+ return {}
219
+
220
+ print(f"[dataset] missing inputs detected: {', '.join(missing)}")
221
+
222
+ dataset_json = _find_dataset_json_or_raise(cfg, base_dir)
223
+ meta = _load_dataset_json(dataset_json)
224
+
225
+ dataset_dir = _resolve_dataset_dir(meta, dataset_json)
226
+ dataset_dir.mkdir(parents=True, exist_ok=True)
227
+
228
+ print(f"[dataset] shared dataset directory: {dataset_dir}")
229
+
230
+ download = dict(meta.get("download", {}) or {})
231
+
232
+ archive_url = meta.get("archive_url")
233
+ if not archive_url:
234
+ archive_url = download.get("archive_url")
235
+
236
+ archive_name = meta.get("archive_name")
237
+ if not archive_name:
238
+ archive_name = download.get("archive_name")
239
+
240
+ if not archive_url:
241
+ raise FileNotFoundError(
242
+ "[dataset] required inputs are missing and dataset.json does not define archive_url "
243
+ "(neither at top level nor under 'download')"
244
+ )
245
+
246
+ if not archive_name:
247
+ archive_name = Path(str(archive_url)).name or "dataset_archive.zip"
248
+
249
+
250
+ archive_path = dataset_dir / str(archive_name)
251
+
252
+ if not archive_path.is_file():
253
+ _download_with_progress(str(archive_url), archive_path)
254
+ else:
255
+ print(f"[dataset] archive already available: {archive_path}")
256
+
257
+ _extract_archive(archive_path, dataset_dir)
258
+ _flatten_extracted_tree(dataset_dir)
259
+
260
+ ok_after, missing_after = _all_required_exist(cfg)
261
+ if not ok_after:
262
+ raise FileNotFoundError(
263
+ "[dataset] archive extracted but required inputs are still missing: "
264
+ + ", ".join(missing_after)
265
+ )
266
+
267
+ print("[dataset] required inputs successfully restored.")
268
+ return meta