OQ-VMTK v1.1.0

[mouayed-nafeh]

Summary

This branch introduces multiple changes to the OQ-VMTK workflow, mainly following a peer-review submission to Earthquake Spectra. This includes a suite of major feature additions, module-wide PEP8 refactoring, bug fixes, and CI/CD improvements. The changes span all core OQ-VMTK modules and bring the codebase to a more stable, maintainable, and feature-complete state.

---

New Features

Incremental Dynamic Analysis (IDA)

• Added do_ida_analysis() to modeller.py — runs nonlinear response history analyses at progressively scaled ground-motion intensities, supporting truncated and non-truncated hunt-and-fill procedures.
• Added process_ida_results() to postprocessor.py — post-processes IDA cloud data into fragility functions and vulnerability curves, including logistic regression and lognormal fitting.
• Added IDA plots to plotter.py — IDA stripe plots, fragility functions derived from IDA, and vulnerability function comparisons.
• Added IncrementalDynamicAnalysis demo notebook with the FEMA P695 far-field ground-motion record set (44 records, unscaled accelerations, time steps, and durations).

Modified Cloud Analysis (MCA) — MCMC Extension

• Added a Markov Chain Monte Carlo (MCMC) method for MCA fragility derivation in postprocessor.py.
• Added classical and bootstrap MCA plotter functions in plotter.py.
• Updated the ModifiedCloudAnalysis demo notebook accordingly.

IM Efficiency and Sufficiency Module (imselection.py)

• Created a new imselection.py module implementing:
  • Efficiency: dispersion-based IM ranking for MCA and IDA.
  • Practicality: slope-based linear regression metric.
  • Proficiency: combined efficiency + practicality metric (κ).
  • RSM (Relative Sufficiency Metric): log-likelihood-based comparison of two IMs.
  • compare_ims(): convenience method to compute and tabulate all metrics across multiple IMs for a given analysis type.
• Added corresponding unit tests in test_imselection.py.

RotDxx Spectral Calculations

• Added get_rotdxx() to imcalculator.py to compute RotD50/RotD100 and arbitrary rotation-percentile response spectra from two horizontal ground-motion components.

Structural Analysis Animations

• Added animations of SPO, CPO, and NRHA results (deformed shape over time/steps) directly from modeller.py via do_spo_analysis(), do_cpo_analysis(), and do_nrha_analysis().
• Added plot_modes() to plotter.py for animated mode shape visualisation.
• Updated all relevant demo notebooks with animated GIF outputs.

Calibration — Displacement-Based Design

• Updated calibration.py to a displacement-based design methodology.
• Renamed internal variables: pflag → pFlag, floor_heights → storey_heights across modeller.py, calibration.py, and all dependents.

AAL and AADP

• Refactored calculate_average_annual_loss() and calculate_average_annual_damage_probability() methods in postprocessor.py.
• Added COV calculation methods and DS threshold variability as an input argument for NLTHA post-processing.

---

Bug Fixes

Module	Fix
postprocessor.py	Fixed NoneType export for non-lognormal fragility methods
postprocessor.py	Stabilised logistic regression when bootstrap produces too few collapses
postprocessor.py	Fixed out-of-bound beta values
slfgenerator.py	Fixed sampling bug
plotter.py	Fixed RecursionError in _show() — changed self._show() to plt.show()
imcalculator.py	Fixed multiple bugs in IM calculation class
modeller.py	General stability fixes for analysis routines and node displacement/acceleration storage
modeller.py	Fixed openseespy import to be OS-conditional

---

Deprecation and Warning Fixes

• Replaced .values[0] scalar extraction with .item() to resolve NumPy DeprecationWarning.
• Replaced chained fillna assignment with direct assignment to resolve Pandas DeprecationWarning.
• Suppressed FigureCanvasAgg UserWarning from plt.show() in headless (CI) environments.
• Fixed Flake8 unterminated string literal issues across source and test files.

---

PEP8 Refactoring

All core modules were refactored for PEP8 compliance and improved readability:

• modeller.py, calibration.py, postprocessor.py, plotter.py
• imcalculator.py (renamed class from IMCalculator to imcalculator)
• slfgenerator.py (renamed from slf_generator.py)
• units.py, utilities.py
• All demo notebooks: IDA, MSA, MCA, NRHA, CA, Pushover, ModalAnalysis, ModelCompilation, SLF, IM Processing
• All unit tests updated accordingly.

---

CI/CD and Dependency Updates

• Added macOS ARM64 (macos_arm_test.yml) GitHub Actions workflow.
• Upgraded CI to Node.js 20 actions (replaced deprecated v3 actions).
• Added GITHUB_TOKEN to workflows to avoid API rate-limiting.
• Added Python 3.13 support in pyproject.toml and CI workflows.
• Pinned scipy>=1.15.3 to resolve installation issue.
• Added statsmodels wheel for macOS ARM64.
• Added platform-specific requirements files for Linux, Windows, and macOS ARM64.

---

Documentation and Demos

• Updated README.md with new feature descriptions and usage guidance.
• Updated Sphinx conf.py and documentation pages for all new modules.
• Updated CITATION.cff.
• Added README.md files for IDA, MSA, MCA, ModalAnalysis, and ModelCompilation demos.
• Updated .gitignore to exclude ipynb_checkpoints.
• Relocated input ground-motion records into organised in/records/ subdirectories within each demo.

---

Files Changed (source)

File	Change
openquake/vmtk/modeller.py	Added IDA, animations, modal plotting, variable renames, PEP8
openquake/vmtk/postprocessor.py	Added IDA/MCA/MCMC post-processing, AAL/AADP refactor, bug fixes
openquake/vmtk/plotter.py	Added IDA/MCA plots, animations, mode shapes, PEP8
openquake/vmtk/imcalculator.py	Added RotDxx, PEP8 refactor, renamed class
openquake/vmtk/imselection.py	New — IM efficiency/sufficiency module
openquake/vmtk/calibration.py	Displacement-based design, variable renames, PEP8
openquake/vmtk/slfgenerator.py	Sampling bug fix, PEP8
openquake/vmtk/units.py	PEP8 refactor
openquake/vmtk/utilities.py	PEP8 refactor

[vot4anto]

LGTM