djura-risk-data-engineering/djura
GitHub: djura-risk-data-engineering/djura
djura 是一个用于基于性能的地震工程分析的 Python 工具包，提供从地面运动记录选择到结构损失建模的完整研究流程支持。
Stars: 4 | Forks: 1
# djura
[](https://github.com/djura-risk-data-engineering/djura/actions/workflows/ci.yml)
[](https://pypi.org/p/djura)
[](https://djura.readthedocs.io)
[](https://www.python.org/)
[](LICENSE)
**djura** 是一个由 Djura | Risk - Data - Engineering S.r.l. 开发和维护的科学 Python 工具包，用于通用工程应用。它将 djura 研究技术栈中使用的核心算法打包到一个可安装的包中：地面运动记录选择、危险一致性的强度测量分析、结构脆弱性建模，以及楼层损失函数生成，且不依赖任何 web 服务器、数据库或云存储。
该软件包仅供**研究和教育用途**使用，并在 **GNU AGPL-3.0-or-later** 许可证下发布，以便与其他 copyleft 科学工具（例如 `openquake.engine`）完美结合。
## 子模块
| 导入路径 | 用途 |
| --------------------------------- | ----------------------------------------------------------- |
| `djura.record_selection` | 基于 GCIM 的地面运动记录选择 |
| `djura.hazard_consistency` | 危险一致性的强度测量分析 |
| `djura.edp_im` | 基于 ML 的 EDP-IM 关系预测 |
| `djura.fragility_converter` | 跨 IM 的脆弱性/易损性模型转换 |
| `djura.vulnerability_modeller` | 地震脆弱性与损失建模（包括 ML 模型） |
| `djura.slf` | 楼层损失函数生成 |
## 安装说明
```
pip install djura
```
**可选的运行时附加组件：**
```
pip install "djura[hdf5]" # adds h5py
pip install "djura[all]" # all of the above
```
**贡献者** — 使用 Poetry 依赖组安装开发及/或文档依赖：
```
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
```
## 文档
有关如何使用各种 djura 包的文档，以及示例应用和教程，请参阅 [readthedocs](https://djura.readthedocs.io/en/latest/index.html) 资源。
此外，还创建了几篇 [博客文章](https://www.djura.it/blog)，其中包含有关如何通过我们网站 [www.djura.it](https://apps.djura.it/login) 上提供的用户界面使用这些包的补充材料。
## 快速入门
```
import djura
print(djura.__version__)
# Per-submodule 示例导入
from djura import record_selection
from djura import hazard_consistency
from djura import edp_im
from djura import vulnerability_modeller
from djura import slf
```
（随着代码的迁移，将逐步添加各子模块的快速入门指南。）
## 内置数据集（NGA-West2 + ESM）
内置的元数据 pickle 文件（解压后约 220 MB）**并不**包含在 wheel 包中。它作为 gzip 压缩的资源托管在 GitHub Release 上，并会在首次需要时自动下载：
```
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
```
缓存文件位于 `~/.cache/djura/flatfile_shallow.pickle`。
您也可以使用自己的元数据文件代替内置数据集：任何映射到相同 schema 的数据库都可以无需修改即可与选择例程配合使用。请参阅 [自定义元数据指南](https://djura.readthedocs.io/en/latest/custom_metadata.html) 获取 schema 参考和分步示例。
默认的 `flatfile_shallow` 数据集结合了来自两个来源的记录：
- [NGA-West2 Ground Motion Database](https://ngawest2.berkeley.edu)
（PEER，UC Berkeley），以及
- [ESM (Engineering Strong-Motion) flatfile](https://esm-db.eu/#/products/flat_file)。
它仅包含元数据，不包含波形记录，并且已扩展了由本项目计算的字段。有关完整的归属说明以及如何从 PEER 和 ESM 下载底层波形的说明，请参阅 [`src/djura/record_selection/assets/ATTRIBUTION.md`](src/djura/record_selection/assets/ATTRIBUTION.md)。
### 发布新数据版本（维护者）
该版本由 `release-data` GitHub Actions workflow 生成，它会压缩 pickle 文件并将其上传到带有标签的 GitHub Release。使用 GitHub CLI 手动触发它：
```
gh workflow run release-data.yml -f version=data-v1
```
发布版本后，更新 `src/djura/data_loader.py` 中的 `GITHUB_RELEASE_URL`，使其指向新标签。
## 如何引用
如果您在学术或研究工作中使用了 **djura**，请引用该软件包**以及**支持您所使用子模块的论文。
```
import djura
# Umbrella package 引用
print(djura.cite())
# Per-submodule 引用
print(djura.cite("vulnerability_modeller"))
# 所有引用
print(djura.cite(all=True))
```
| 子模块 | 参考文献 |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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*. 10th International Conference on Computational Methods in Structural Dynamics and Earthquake Engineering (COMPDYN 2025), Rhodes, Greece, Jun. 2025, pp. 780–804. doi: [10.7712/120125.12447.25302](https://doi.org/10.7712/120125.12447.25302) |
项目中提供了一个 `CITATION.cff` 文件，以便 GitHub 自动渲染“引用此仓库”按钮。
## 许可证
Copyright © 2025–2026 Djura | Risk - Data - Engineering S.r.l. (Italy). All rights reserved.
djura 采用**双重许可**：
- **开源许可证** — GNU Affero General Public License v3.0 or later
(SPDX: `AGPL-3.0-or-later`)。完整文本请参阅 [LICENSE](LICENSE)。这是默认适用的许可证，涵盖学术、研究及其他兼容 AGPL 的开源用途。
- **商业许可证** — 可向 Djura | Risk - Data - Engineering S.r.l. 获取。请参阅下方的 [商业授权](#commercial-licensing)。
此软件包内嵌了改编自
[OpenQuake Engine](https://github.com/gem/oq-engine) 的部分代码
(© GEM Foundation, AGPL-3.0-or-later)；归属详细信息请参阅
[`src/djura/record_selection/gsim/NOTICE.md`](src/djura/record_selection/gsim/NOTICE.md)。
衍生自 OpenQuake 的部分在所有发行版中均保留在 AGPL-3.0-or-later 许可证下。
## 商业授权
AGPL-3.0-or-later 规定了严格的 copyleft 义务：如果您分发 djura，或通过网络（API、Web 应用、SaaS 后端、托管分析服务等）公开其功能，您必须根据 AGPL 许可证向您的应用用户提供**完整的对应源代码**。
如果这与您的商业模式不兼容——例如，您希望将 djura 用于**商业或盈利目的**，包括：
- 将 djura 嵌入到**闭源商业产品**中；
- 提供**专有 SaaS** 或由 djura 支持的托管服务，而不根据 AGPL 发布您自己的源代码；
- 在**内部商业工作流**中使用 djura，而不根据 AGPL 发布您的源代码；
- 获得AGPL明确拒绝的**担保、赔偿或商业支持**；
那么您需要向版权所有者 **Djura | Risk - Data - Engineering S.r.l.** (Italy) 申请**商业许可证**。
如需申请商业许可证，请联系：
📧 **[info@djura.it](mailto:info@djura.it)**
请在邮件中简要描述您的预期用例（组织、产品、部署模式、预期用户群）。我们将回复授权条款。
标签：Apex, Python, 地震工程, 安全规则引擎, 无后门, 机器学习, 灾害损失评估, 科研工具, 结构脆弱性, 逆向工具