Minor Fixes for Earthquake Spectra Reviews

CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- `plotter.plot_vulnerability_function`: new optional `xlims` parameter (`[min, max]`) to restrict the plotted intensity range. Data arrays are filtered before plot creation so the violin axis is never distorted.
+
+### Changed
+- `plotter.plot_modes`: mode titles are now placed via `fig.text()` centred over both the X- and Y-displacement panels instead of being attached only to the left panel. Font sizes for node annotations, axis labels, tick marks, and panel titles, and the vertical spacing parameters (`hspace`, `top`), now scale adaptively with the number of grid rows and nodes per panel, preventing text and title overlap when plotting many modes.
+- `plotter.plot_vulnerability_function`: x-axis tick label font size reduced to prevent overlap when many intensity levels are present.
+- Demo `NonlinearTimeHistoryAnalysis`: introduction and section descriptions updated to match the concise style used across other demos; verbose bullet-point input/output argument lists removed.
+- Demo `PushoverAnalysis`: cyclic pushover protocol updated to a two-repetition-per-level scheme (ATC-24 / FEMA 461 style), producing 20 full hysteresis loops instead of 11.
+- Demo `StoreyLossFunctionApplication`: loss vs. IM fitting replaced with a power-law regression (OLS in log space, monotone by construction) paired with a Beta distribution dispersion model; COV estimated per quantile bin from the cloud scatter and propagated through the collapse-conditioning step using the law of total variance; summary tables of IML / mean loss / COV printed at both the non-conditioned and conditioned stages.
+- `README.md`: all module and demo descriptions updated; badge URLs corrected (`.svg` suffix removed from shields.io GitHub badges; Zenodo DOI badge migrated to shields.io static endpoint); contributor shield URLs fixed; installation, license, citation, and references sections added.
+- Demo `README.md` files: titles and descriptions corrected across `MultipleStripeAnalysis`, `FragilityAnalysis`, `IntensityMeasureProcessing`; `IntensityMeasureSelection/README.md` created; `demos/README.md` index updated to list all 13 demos.
+
+### Fixed
+- `plotter.plot_fragility_from_mca`: `title` parameter was silently ignored (variable was set but `ax.set_title()` was never called); title is now correctly applied to the figure.
+- `plotter.plot_vulnerability_function`: Beta distribution sampling returned all-NaN when CoV was zero (division by zero produced `inf` parameters); now returns a point mass at the mean for the degenerate case.
+
+### Renamed
+- `imcalculator.get_velocity_displacement_history` → `imcalculator.get_vel_disp_history`. Documentation and examples updated accordingly.
+
+---
+
 ## v1.1.0 — 2026-05-12
 
 ### Added

demos/FragilityAnalysis/README.md

@@ -1,7 +1,5 @@
-# Pushover Analysis Demo
+# Fragility Analysis Demo
 
-This Jupyter Notebook demonstrates an example application of monotonic static pushover and cyclic pushover analyses on a multi-degree-of-freedom (MDOF) stick model where global and local response quantities such as base shear, storey displacements and interstorey drifts are extracted.
+This Jupyter Notebook demonstrates the different fragility function functionalities available in OQ-VMTK and illustrates the effect of each of these methods on subsequent downstream applications including loss modelling and risk metrics calculation. All fragility fitting methods are applied to the same pre-computed Modified Cloud Analysis dataset using the `postprocessor` module, covering lognormal cumulative distribution function variants, generalised linear models (GLM logit and probit), and ordinal cumulative link models (CLM).
 
-The MDOF stick model is compiled in OpenSees using the `modeller` module, defining nodes, masses, elements, and storey-based force-deformation relationships in nonlinear springs (i.e., zero-length elements).
-
-The storey-based force-deformation relationships are calibrated using a target capacity curve defined for an equivalent Single-Degree-of-Freedom (SDOF) system expressed in terms of spectral acceleration and displacement and using the `calibration` module of OQ-VMTK. The SDOF capacity is converted into an MDOF target by distributing strength and stiffness across the stories based on a modal shape, typically the first mode.
+NOTE: Throughout the notebook, a demonstration of managing I/O in OQ-VMTK is presented. This is particularly valuable because it ensures that OQ-VMTK’s modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.

demos/IncrementalDynamicAnalysis/README.md

@@ -1,11 +1,7 @@
 # Incremental Dynamic Analysis Demo
 
-This Jupyter Notebook presents an example of Incremental Dynamic Analysis (IDA) carried out on a multi-degree-of-freedom (MDOF) stick model using the `modeller` module. Both global and local response quantities, such as peak storey drifts and peak floor accelerations, are extracted across a range of increasing intensity levels. To do so, the "Hunt, Trace and Fill" algorithm is employed to scale ground motion records until structural collapse is observed. Once structural collapse or dynamic instability is observed, the IDA curve is traced back and filled with smaller increments of scaling factor.
+This Jupyter Notebook presents an example of Incremental Dynamic Analysis carried out on a multi-degree-of-freedom stick model using the `modeller` module.  To do so, the "Hunt, Trace and Fill" algorithm is employed to scale ground motion records until structural collapse is observed. Once structural collapse or dynamic instability is observed, the IDA curve is traced back and filled with smaller increments of scaling factor.
 
-From these scaled results, the `postprocessor` module is then applied to derive fragility functions by fitting lognormal cumulative distribution functions based on the observed dynamic capacity (i.e., IDA curve) at specific demand-based damage states.
+From these scaled results, global response quantities, such as peak storey drifts, are extracted across a range of increasing intensity levels and the `postprocessor` module is then applied to derive fragility functions by fitting lognormal cumulative distribution functions based on the observed dynamic capacity (i.e., IDA curve) at specific demand-based damage states.
 
-A vulnerability, or loss model, is subsequently developed by combining these fragility-based probabilities of exceedance with a deterministic consequence model through damage-to-loss ratios. To account for the inherent uncertainty in losses at a given shaking intensity, a beta distribution is utilized.
-
-Finally, visual outputs using the the `plotter` module, include IDA curves, seismic demand profiles, fragility functions, and vulnerability models.
-
-NOTE: As an additional feature, the notebook demonstrates how to export NLTHA response quantities. This step is valuable because it ensures that OQ-VMTK’s postprocessor and plotter modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.
+NOTE: Throughout the notebook, a demonstration of managing I/O in OQ-VMTK is presented. This is particularly valuable because it ensures that OQ-VMTK’s modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.

demos/IntensityMeasureProcessing/IntensityMeasureProcessing.ipynb

@@ -27,9 +27,9 @@
     "   - Arias Intensity (AI), Cumulative Absolute Velocity (CAV), and Significant Duration (D595)\n",
     "   - Filtered Incremental Velocity 3 (FIV3)\n",
     "  \n",
-    "Please note that the class used \"imcalculator\" is always subject to updating to reflect state-of-the-art IM inclusion.\n",
+    "4. **Organize and Export Results**: Organize the extracted IM levels for each record, summarizing the results for analysis and potential use in structural modeling and assessment studies. The results are stored in a dictionary-type variable and exported into a pickle file.\n",
     "\n",
-    "4. **Organize and Export Results**: Organize the extracted IM levels for each record, summarizing the results for analysis and potential use in structural modeling and assessment studies. The results are stored in a dictionary-type variable and exported into a pickle file. "
+    "Please note that the class used \"imcalculator\" is always subject to updating to reflect state-of-the-art IM inclusion.\n"
    ]
   },
   {

demos/IntensityMeasureProcessing/README.md

@@ -1,5 +1,5 @@
 # Intensity Measure Processing Demo
 
-This Jupyter Notebook demonstrates an example application of monotonic static pushover and cyclic pushover analyses on a multi-degree-of-freedom (MDOF) stick model where global and local response quantities such as base shear, storey displacements and interstorey drifts are extracted.
+This Jupyter Notebook provides an example application of the `imcalculator` module for reading ground motion record files and extracting distinct intensity measure (IM) levels across various IM types. Ground motion IMs are essential parameters that characterize the ground shaking and helps the modeller in understanding better the demand imposed by ground motions on structural systems and eventually characterise a probabilistic demand-intensity model to building classes under investigation.
 
-This Jupyter Notebook provides an example application of the `IMCalculator` module for reading ground motion record files and extracting distinct intensity measure (IM) levels across various IM types. Ground motion IMs are essential parameters that characterize the ground shaking and helps the modeller in understanding better the demand imposed by ground motions on structural systems and eventually characterise a probabilistic demand-intensity model to building classes under investigation.
+NOTE: Throughout the notebook, a demonstration of managing I/O in OQ-VMTK is presented. This is particularly valuable because it ensures that OQ-VMTK’s modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.

demos/IntensityMeasureSelection/README.md

@@ -0,0 +1,7 @@
+# Intensity Measure Selection Demo
+
+This Jupyter Notebook demonstrates a framework for selecting optimal intensity measures (IMs) for seismic demand modelling using the `imselection` module. Four IM selection metrics are evaluated: Efficiency, Proficiency, Practicality, and the Relative Sufficiency Measure (RSM). Three different applications are supported in this demonstration notebook, mainly:
+
+- **Part I**: MCA-based IM selection — evaluating IM candidates against Modified Cloud Analysis results.
+- **Part II**: IDA-based IM selection — evaluating the same candidates against Incremental Dynamic Analysis results.
+- **Part III**: MCA vs. IDA comparison — assessing whether IM rankings are consistent across analysis methods.

demos/ModalAnalysis/README.md

@@ -1,7 +1,3 @@
 # Modal Analysis Demo
 
-This demonstration presents a structured workflow for the development and verification of simplified structural models in OpenSees for regional vulnerability and risk applications. The focus is on constructing idealised representations of typical buildings (i.e., stick-and-mass models), and evaluating their dynamic characteristics through modal analysis.
-
-This Jupyter Notebook provides an example application of the `modeller` and `calibration` modules for generating simplified structural representations of regional building stock and analysing their modal properties.
-
-The example presents the development of MDOF stick-and-mass models calibrated based on SDOF capacity. The calibration of MDOF models is carried out to achieve consistency with target global dynamic properties derived from the SDOF representations. This calibration procedure adjusts inter-storey stiffness and mass distributions so that the fundamental period and modal participation characteristics of the MDOF model align with the simplified SDOF system. Then, the stick-and-mass model is modelled where each floor is represented by a lumped mass connected through zero-length elements representing the lateral stiffness of load-resisting elements. This representation enables the computation of modal properties including natural frequencies, periods, and mode shapes that characterise the dynamic response of the structure.
+This demonstration presents a structured workflow for the development and verification of simplified structural models in OpenSeesPy for regional vulnerability and risk applications using the `modeller` and `calibration` modules. Then, the dynamic characteristics of the dealised systems are calculated for system verification purposes through modal analysis to compute modal properties including natural frequencies, periods, and mode shapes that characterise the dynamic response of the structure.

demos/ModelCompilation/README.md

@@ -1,11 +1,3 @@
 # Model Compilation Demo
 
-This demonstration presents a structured workflow for the calibration and development of simplified structural models in OpenSees for regional vulnerability/risk applications, with a focus on building models that represent typical structures yet in an idealised manner such as simplified single-degree-of-freedom (SDOF) and more realistic multi-degree-of-freedom (MDOF) stick-and-mass models with a calibration procedure linking the two approaches.
-
-This Jupyter Notebook provides an example application of the `modeller` and `calibration` modules for creating idealised structural representations of the regional building stock.
-
-The first example includes construction of SDOF representations by defining essential structural properties such as mass, height, and nonlinear capacity.
-
-The second example includes the development of MDOF stick-and-mass models, in which each floor is represented as a lumped mass connected by nonlinear springs capturing lateral stiffness, yielding and nonlinear behaviour.
-
-The third example considers the calibration of MDOF Models Based on SDOF capacity and parameters. Establishing consistency between the SDOF and MDOF representations is carried out by calibrating inter-story properties of the MDOF model using target capacity curves derived from the SDOF model.
+This demonstration presents an example application for the modelling, calibration and development of simplified structural models in OpenSeesPy for regional vulnerability/risk applications using the `modeller` and `calibration` modules, with a focus on building models that represent typical structures yet in an idealised manner such as simplified single-degree-of-freedom (SDOF) and more realistic multi-degree-of-freedom (MDOF) stick-and-mass models with a calibration procedure linking the two approaches.

demos/ModifiedCloudAnalysis/README.md

@@ -1,11 +1,5 @@
 # Modified Cloud Analysis Demo
 
-This Jupyter Notebook presents an example of nonlinear dynamic analysis, focusing on cloud analysis of a multi-degree-of-freedom (MDOF) stick model. Both global and local response quantities, such as peak storey drifts and peak floor accelerations, are extracted. A probabilistic seismic demand model (PSDM) is then fitted to the intensity measure (IM) and engineering demand parameter (EDP) data using linear regression in log–log space. From this model, fragility functions are derived for arbitrary demand-based damage states. A vulnerability, or loss model, is subsequently developed by combining the fragility-based probabilities of exceedance with a deterministic consequence model through damage-to-loss ratios, while also accounting for uncertainty in losses at a given shaking intensity using a beta distribution. Visual outputs of the PSDM, seismic demand profiles, fragility functions, and vulnerability models are included.
+This Jupyter Notebook presents an example of nonlinear time-history analysis (NLTHA), focusing on modified cloud analysis of a multi-degree-of-freedom (MDOF) stick model. First, engineering demand parameters (EDPs), such as peak storey drifts and peak floor accelerations, are extracted. Then, a probabilistic seismic demand model (PSDM) is fitted to the intensity measure (IM) and EDP data (i.e., cloud) using linear regression in log–log space and a logistic regression that handles the collapse/dynamic instability cases. From this model, and combining non-collapse and collapse cases using total probability theorem, fragility functions are derived for arbitrary demand-based damage states. 
 
-The MDOF stick model is implemented in OpenSees through the  `modeller` module. This involves defining nodes, masses, elements, and storey-level force–deformation relationships represented with nonlinear springs (i.e., zero-length elements). A single ground motion record is used to demonstrate nonlinear time-history analysis (NLTHA) within the  `modeller` framework.
-
-The `postprocessor` module is then applied to establish the IM–EDP relationships and to derive the fragility and vulnerability models.
-
-Finally, the `plotter` module is used to produce visualizations of the PSDM fit to the IM–EDP dataset, seismic demand profiles (peak storey drift and peak floor acceleration along the model height), and the fragility and vulnerability functions.
-
-NOTE: As an additional feature, the notebook demonstrates how to export NLTHA response quantities. This step is valuable because it ensures that OQ-VMTK’s postprocessor and plotter modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.
+NOTE: Throughout the notebook, a demonstration of managing I/O in OQ-VMTK is presented. This is particularly valuable because it ensures that OQ-VMTK’s modules receive input data in a consistent, ready-to-use format. Users are encouraged to follow this procedure for efficient data processing and analysis.