djura

djura is a scientific Python toolkit developed and maintained by Djura | Risk - Data - Engineering S.r.l. for general engineering applications. 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 only, 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).

Commercial use? djura is dual-licensed. The AGPL-3.0-or-later terms below apply to academic, research, and other open-source use only. If you want to use djura for commercial or revenue-generating purposes - including as part of a closed-source product, as part of an internal commercial workflow, or a network-accessible service without releasing your own source code under the AGPL - you need a separate commercial license. Contact info@djura.it to arrange one. See Commercial licensing below.

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

Installation

pip install djura

Optional runtime extras:

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.

Documentation

For documentation on how to use the various djura packages, as well as example applications and tutorials, please refer to the readthedocs resources.

A complete list of the supported ground motion models and intensity measure correlation models, with citations to their scientific publications, is given in MODELS.md.

Additionally, several blog posts have been created with supplemental material on how to use these packages via the user interface available at our website www.djura.it.

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 + ESM)

The bundled metadata pickle (~220 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/flatfile_shallow.pickle.

You can also use your own metadata file in place of the bundled dataset: any database mapped to the same schema works with the selection routines unmodified. See the custom metadata guide for the schema reference and a step-by-step example.

The default flatfile_shallow dataset combines records from two sources:

• the NGA-West2 Ground Motion Database (PEER, UC Berkeley), and
• the ESM (Engineering Strong-Motion) flatfile.

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 and ESM.

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.

The software itself has a persistent DOI: 10.60756/DJURA-HD26.

import djura

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

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

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

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

Contributing

Contributions are welcome. Please read the contributing guide for development setup, testing, and the pull-request process, and note that participation is governed by our Code of Conduct.

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.

Maintenance and sustainability

djura is actively developed and maintained by Djura | Risk - Data - Engineering S.r.l., with development led by the authors listed in CITATION.cff. The package consolidates the algorithms underpinning the company's research and commercial activity, which gives its continued maintenance a durable institutional basis beyond any single contributor or grant.

• Releases and versioning. The project follows semantic versioning, with versions derived automatically from git tags. Each release is published to PyPI and archived with a persistent DOI (10.60756/DJURA-HD26). Notable changes are recorded in CHANGELOG.md.
• Quality assurance. Every push and pull request runs continuous integration (linting, the test suite across Linux/macOS/Windows and the supported Python versions, and a packaging/metadata check). CodeQL scanning and Dependabot dependency updates are enabled.
• Issue tracking and support. Bugs and feature requests are handled through the GitHub issue tracker. Security reports follow the process in SECURITY.md.
• Contributions. External contributions are welcomed under the process in CONTRIBUTING.md and the Code of Conduct.
• Longevity. Should the company ever discontinue maintenance, the AGPL-3.0-or-later license and the public, DOI-archived releases ensure the community can continue to use, fork, and maintain the software.

License

Copyright © 2025–2026 Djura | Risk - Data - Engineering S.r.l. (Italy). All rights reserved.

djura is dual-licensed:

• Open-source license — GNU Affero General Public License v3.0 or later (SPDX: AGPL-3.0-or-later). See LICENSE for the full text. This is the license that applies by default and covers academic, research, and other AGPL-compatible open-source use.
• Commercial license — available from Djura | Risk - Data - Engineering S.r.l. See Commercial licensing below.

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. The OpenQuake-derived portions remain under AGPL-3.0-or-later in all distributions.

Commercial licensing

The AGPL-3.0-or-later imposes a strong copyleft obligation: if you distribute djura, or expose its functionality over a network (API, web app, SaaS backend, hosted analysis service, etc.), you must make the complete corresponding source code of your application available to its users under the AGPL.

If that is not compatible with your business — for example because you want to use djura for commercial or revenue-generating purposes, including:

• embedding djura in a closed-source commercial product;
• offering a proprietary SaaS or hosted service powered by djura without releasing your own source under the AGPL;
• using djura in internal commercial workflows without releasing your source code under the AGPL;
• receiving warranties, indemnification, or commercial support that the AGPL explicitly disclaims;

then you need a commercial license from Djura | Risk - Data - Engineering S.r.l. (Italy), the copyright holder.

To request a commercial license, please contact:

📧 info@djura.it

Please include a short description of the intended use case (organisation, product, deployment model, expected user base). We will reply with licensing terms.

Academic researchers, students, and other AGPL-compatible users do not need to contact us — the AGPL grant in LICENSE already covers you.