Metadata-Version: 2.4
Name: djura
Version: 0.1.0
Summary: Scientific Python toolkit for earthquake engineering: GCIM-based ground motion record selection, hazard consistency, vulnerability modelling, and storey loss functions.
License: AGPL-3.0-later
License-File: LICENSE
Keywords: earthquake-engineering,seismic-hazard,ground-motion-selection,gcim,vulnerability,fragility,storey-loss-function,performance-based-engineering
Author: Djura | Risk - Data - Engineering S.r.l.
Author-email: info@djura.it
Requires-Python: >=3.10,<3.14
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Provides-Extra: all
Provides-Extra: hdf5
Provides-Extra: plot
Provides-Extra: xgboost
Requires-Dist: h5py (>=3.16,<4) ; extra == "all"
Requires-Dist: h5py (>=3.16,<4) ; extra == "hdf5"
Requires-Dist: joblib (>=1.5.3,<2.0.0)
Requires-Dist: matplotlib (>=3.9) ; extra == "all"
Requires-Dist: matplotlib (>=3.9) ; extra == "plot"
Requires-Dist: numba (>=0.59)
Requires-Dist: numpy (>=1.26)
Requires-Dist: pandas (>=2.2)
Requires-Dist: pwlf (>=2.5.2,<3.0.0)
Requires-Dist: pydantic (>=2.13.3,<3.0.0)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: scipy (>=1.14)
Requires-Dist: shapely (>=2.1.2,<3.0.0)
Requires-Dist: statsmodels (>=0.14.6,<0.15.0)
Requires-Dist: xgboost (>=1.7) ; extra == "all"
Requires-Dist: xgboost (>=1.7) ; extra == "xgboost"
Project-URL: Changelog, https://github.com/djura-risk-data-engineering/djura/blob/main/CHANGELOG.md
Project-URL: Homepage, https://github.com/djura-risk-data-engineering/djura
Project-URL: Issues, https://github.com/djura-risk-data-engineering/djura/issues
Project-URL: Repository, https://github.com/djura-risk-data-engineering/djura
Description-Content-Type: text/markdown

# djura

[![CI](https://github.com/djura-risk-data-engineering/djura/actions/workflows/ci.yml/badge.svg)](https://github.com/djura-risk-data-engineering/djura/actions/workflows/ci.yml)
[![Python](https://img.shields.io/badge/python-3.10%E2%80%933.13-blue.svg)](https://www.python.org/)
[![License: AGPL v3+](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)

**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](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

```bash
pip install djura
```

**Optional runtime extras:**

```bash
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:

```bash
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

```python
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:

```python
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](https://ngawest2.berkeley.edu)
(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`](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:

```bash
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.

```python
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](https://doi.org/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](https://doi.org/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](CLA.md), 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](LICENSE) for the full text.

This package vendors a subset of code adapted from the
[OpenQuake Engine](https://github.com/gem/oq-engine) (© GEM Foundation,
AGPL-3.0-or-later); see
[`src/djura/record_selection/gsim/NOTICE.md`](src/djura/record_selection/gsim/NOTICE.md)
for attribution details.

