djura 0.1.0

Scientific Python toolkit for earthquake engineering: GCIM-based ground motion record selection, hazard consistency, vulnerability modelling, and storey loss functions.

djura

djura is a scientific Python toolkit for earthquake engineering. It bundles into a single installable package the core algorithms used across the DJURA research stack — ground motion record selection, hazard-consistent intensity measure analysis, structural vulnerability modelling, and storey loss function generation — with no web-server, database, or cloud-storage dependencies.

The package is intended for research and educational use, and is released under the GNU AGPL-3.0-or-later license so that it composes cleanly with other copyleft scientific tools (e.g. openquake.engine).

AGPL-3.0 notice - If you use djura as part of a network-accessible service (API, web application, SaaS backend), the AGPL requires that you make the complete corresponding source code available to your users. Running djura in a private research environment or on your own workstation is not affected. See the LICENSE file for the full terms.

Submodules

Import path	Purpose
djura.record_selection	GCIM-based ground motion record selection
djura.hazard_consistency	Hazard-consistent intensity measure analysis
djura.edp_im	ML-based EDP-IM relationship prediction
djura.fragility_converter	Fragility/vulnerability model conversion across IMs
djura.vulnerability_modeller	Seismic vulnerability and loss modelling (incl. ML models)
djura.slf	Storey loss function generation

Installation

pip install djura

Optional runtime extras:

pip install "djura[plot]"   # adds matplotlib
pip install "djura[hdf5]"   # adds h5py
pip install "djura[all]"    # all of the above

For contributors — install development and/or documentation dependencies using Poetry dependency groups:

poetry install --with dev        # testing and linting (pytest, flake8)
poetry install --with docs       # Sphinx + furo for building the docs
poetry install --with dev,docs   # everything

sphinx-autodoc-typehints in the docs group requires Python ≥ 3.12 and is skipped automatically on earlier versions.

Quickstart

import djura

print(djura.__version__)

# Per-submodule example imports
from djura import record_selection
from djura import hazard_consistency
from djura import edp_im
from djura import vulnerability_modeller
from djura import slf

(Per-submodule quickstarts will be added as code is migrated in.)

Bundled dataset (NGA-West2)

The NGA-West2 metadata pickle (~107 MB uncompressed) is not shipped inside the wheel. It is hosted as a gzip-compressed asset on a GitHub Release and downloaded automatically the first time it is needed:

from djura.data_loader import load_data, clear_cache

data = load_data()       # downloads on first call, then loads from cache
clear_cache()            # delete the cached file to force a re-download

The cache lives at ~/.cache/djura/NGA_W2_v2.pickle.

The dataset is derived from the NGA-West2 Ground Motion Database (PEER, UC Berkeley). It contains metadata only — no waveform records — and has been extended with fields computed by this project. See src/djura/record_selection/assets/ATTRIBUTION.md for full attribution and instructions on downloading the underlying waveforms from PEER.

Publishing a new data release (maintainers)

The release is produced by the release-data GitHub Actions workflow, which compresses the pickle and uploads it to a tagged GitHub Release. Trigger it manually with the GitHub CLI:

gh workflow run release-data.yml -f version=data-v1

After the release is published, update GITHUB_RELEASE_URL in src/djura/data_loader.py to point at the new tag.

How to cite

If you use djura in academic or research work, please cite the package and the paper(s) backing the submodule(s) you use.

import djura

# Umbrella package citation
print(djura.cite())

# Per-submodule citation
print(djura.cite("vulnerability_modeller"))

# All citations
print(djura.cite(all=True))

Submodule	Reference
record_selection	Shahnazaryan, D., Ozsarac, V., & O'Reilly, G. J. (2025). DJURA Ground Motion Record Selector: A Software Solution for Earthquake Engineering. COMPDYN 2025.
hazard_consistency	Shahnazaryan, D., Ozsarac, V., & O'Reilly, G. J. (2025). DJURA Ground Motion Record Selector: A Software Solution for Earthquake Engineering. COMPDYN 2025.
edp_im	Shahnazaryan, D., & O'Reilly, G. J. (2024). Next-generation non-linear and collapse prediction models for short- to long-period systems via machine learning methods. Engineering Structures, 306, 117801. doi:10.1016/j.engstruct.2024.117801
vulnerability_modeller	O'Reilly, G. J., & Shahnazaryan, D. (2024). On the utility of story loss functions for regional seismic vulnerability modeling and risk assessment. Earthquake Spectra, 40(3), 1933–1955. doi:10.1177/87552930241245940
fragility_converter	O'Reilly, G. J., Ozsarac, V., & Shahnazaryan, D. (2025). Conversion of seismic fragility and vulnerability models to alternative intensity measures for regional risk analysis. Earthquake Spectra (Under Review).
slf	Shahnazaryan, D., Ozsarac, V., & O'Reilly, G. J. (2025). The Role of Story Loss Functions in Regional Seismic Vulnerability Modelling and Risk Assessment.

A CITATION.cff file is provided so that GitHub renders a "Cite this repository" button automatically.

Contributing

Contributions are welcome. By submitting a Contribution, you agree to the terms of the Contributor License Agreement, which (among other things) allows the maintainer to relicense the project — for example, to offer a separate commercial license alongside AGPL-3.0.

License

Copyright © 2025–2026 Djura | Risk - Data - Engineering S.r.l.

Licensed under the GNU Affero General Public License v3.0 or later (SPDX: AGPL-3.0-or-later). See LICENSE for the full text.

This package vendors a subset of code adapted from the OpenQuake Engine (© GEM Foundation, AGPL-3.0-or-later); see src/djura/record_selection/gsim/NOTICE.md for attribution details.