OasisLMF/OasisLMF

[](https://badge.fury.io/py/oasislmf) [](https://colab.research.google.com/github/OasisLMF/OasisLMF/blob/main/fm_testing_tool/FmTesting.ipynb) [](https://github.com/OasisLMF/OasisLMF/actions/workflows/unittest.yml) [](https://github.com/OasisLMF/OasisLMF/actions/workflows/code-quality.yml) [](https://github.com/OasisLMF/OasisLMF/actions/workflows/piwind-test.yml) [](https://github.com/OasisLMF/OasisLMF/actions/workflows/piwind-mdk.yml) # OasisLMF `oasislmf` Python 包，通常被称为 *模型开发套件 (MDK)* 或 *MDK 包*，提供了一个命令行工具集，用于在本地或通过 Oasis API 远程进行 Oasis 模型的端到端开发、测试和运行。它可以生成总损失 (GUL)、直接/已保险损失 (IL) 和再保险损失 (RIL)。它还可以在所有这些层级生成确定性损失。 ## 版本控制与更新 ### 当前稳定版本（积极支持中） * `2.3.x` [stable/2.3.x](https://github.com/OasisLMF/OasisLMF/tree/stable/2.3.x) 自 2024 年起 * `2.4.x` [stable/2.4.x](https://github.com/OasisLMF/OasisLMF/tree/stable/2.4.x) 自 2025 年起 * `2.5.x` [stable/2.5.x](https://github.com/OasisLMF/OasisLMF/tree/stable/2.4.x) 自 2026 年起 ### 发布计划 从 2023 年开始，我们转为对我们的稳定版本采用年度发布周期。在每年年初，我们会发布一个新的稳定版本，其 **minor** 版本号 `{major}.{minor}.{patch}` 会增加。 该版本的 oaisislmf 随后被“冻结”到与新版本号匹配的分支中，因此对于发布版本 `{major}.{minor}.0`，代码库会被复制到与版本 `stable/{major}.{minor}.x` 匹配的分支，这些分支是应用向后移植的功能和修复的地方。 通常，我们力求在每个稳定版本内保持输出数字的一致性。（不包括输出错误等 bug） #### 每月稳定版更新 每个月我们会为被视为“积极维护”的最后三个稳定版本提供更新。 因此，在可能的情况下，无需请求，bug 修复就会被向后移植并应用。 较旧的版本可以更新，但需根据请求进行。 当稳定版本有每月更新发布时，其 **patch** 版本号会递增，即从 `{major}.{minor}.{n}` 变为 `{major}.{minor}.{n + 1}`。 ## 功能 对于本地运行模型，CLI 提供了一个 `model` 子命令，包含以下选项： * `model generate-exposure-pre-analysis`：使用用户自定义代码生成新的暴露输入（例如：地理编码、暴露增强或拆分等） * `model generate-keys`：从模型查找生成 Oasis keys 文件；这些本质上是（位置 ID、风险 ID、险种类型 ID、区域风险 ID、易损性 ID）的行项目，其中风险 ID 和险种类型 ID 涵盖了模型支持的全部风险和险种类型集合；如果查找是针对复杂/自定义模型的，keys 文件将具有相同的格式，只是区域风险 ID 和易损性 ID 被模型数据 JSON 字符串替换 * `model generate-oasis-files`：生成用于损失计算的 Oasis 输入 CSV 文件（GUL、GUL + IL 或 GUL + IL + RIL）；它需要提供源暴露数据，以及可选的源账户、再保险信息和范围文件（OED 格式），以及用于实例化模型查找和生成 keys 文件的资产 * `model generate-losses`：从一组预先存在的 Oasis 文件生成损失（GUL、或 GUL + IL、或 GUL + IL + RIL） * `model run`：通过从源暴露数据（以及可选的源账户、再保险信息和范围文件，OED 或 RMS 格式），以及与查找实例化和 keys 文件生成相关的资产开始，全程运行模型以生成损失（GUL、或 GUL + IL、或 GUL + IL + RIL） 可选的 `--summarise-exposure` 标志可以与 `model generate-oasis-files` 和 `model run` 一起使用，以生成按险种类型和风险分组的总保险价值 (TIV) 摘要。这会生成 `exposure_summary_report.json` 文件。 对于远程模型执行，`api` 子命令提供以下主要子命令： * `api run`：通过 Oasis API 远程运行模型（与 `model run` 相同） 为了生成确定性损失，提供了一个 `exposure run` 子命令： * `exposure run`：生成确定性损失（GUL、或 GUL + IL、或 GUL + IL + RIL） 可复用的库被组织成几个子包，从模型开发者或用户的角度来看，最相关的是： * `api_client` * `model_preparation` * `model_execution` * `utils` ## 最低 Python 要求 从 2019 年 1 月 1 日起，Pandas 将不再支持 Python 2。由于 Pandas 是 MDK 的关键依赖项，自本版本 (1.3.4) 起，我们将 **停止对 Python 2 (2.7) 的支持**。最后一个仍支持 Python 2.7 的版本是版本 `1.3.3`（发布于 12/03/2019）。 此外，对于本版本（及所有未来版本），**最低需要 Python 3.10**。 ## 安装 可以使用 `pip` 安装最新发布的版本或特定的包版本： ``` pip install oasislmf[==] ``` 或者，您可以使用以下命令安装最新的开发版本： ``` pip install git+{https,ssh}://git@github.com/OasisLMF/OasisLMF ``` 您也可以使用以下命令从特定分支 `` 安装： ``` pip install [-v] git+{https,ssh}://git@github.com/OasisLMF/OasisLMF.git@#egg=oasislmf ``` ### macOS Apple Silicon (M1/M2/M3/M4) OasisLMF 可以通过 `pip install oasislmf` 在 Apple Silicon Mac 上原生安装。请确保您具备： - **Python 3.10+**（macOS 的系统 Python 是 3.9 —— 通过 `brew install python@3.12` 或 pyenv 安装） - **macOS 12 (Monterey) 或更高版本**（scipy ARM64 wheels 需要） 对于可选的地理空间额外功能（`pip install oasislmf[extra]`），还需安装： ``` brew install spatialindex geos ``` 有关完整详情、故障排除和 ktools 信息，请参阅 [docs/installation_for_mac.md](docs/installation_for_mac.md)。 ## 启用 Bash 补全 Bash 补全是一项功能，bash 通过在用户输入命令时按 Tab 键呈现可能的选项来帮助用户输入命令。 安装 oasislmf 后，您需要通过 source 一个 bash 文件来激活该功能。（只需运行一次） ### 本地 ``` oasislmf admin enable-bash-complete ``` ### 全局 ``` echo 'complete -C completer_oasislmf oasislmf' | sudo tee /usr/share/bash-completion/completions/oasislmf ``` ## JIT 缓存预热 OasisLMF 使用 Numba JIT 编译进行性能关键型计算。安装后的第一次运行会产生一次性的编译开销（2-6 分钟）。最好预编译所有约 191 个 JIT 函数，以减少开销和内存峰值，可以使用： ``` oasislmf warmup ``` 遗憾的是，目前这在 docker 上效果不佳，除非您能保证运行发生在相同类型的机器上。 在这种情况下，您可以在安装后运行此命令。 ``` RUN pip install oasislmf && oasislmf warmup ``` ## 依赖项 ### 系统 该包提供了一个内置的查找框架（`oasislmf.model_preparation.lookup.OasisLookup`），它使用 Rtree Python 包，而 Rtree 又需要 `libspatialindex` 空间索引 C 库。 https://libspatialindex.github.io/index.html Linux 用户可以使用 `apt` 从命令行安装 `libspatialindex` 的开发版本。 ``` [sudo] apt install -y libspatialindex-dev ``` OS X 用户可以通过 `brew` 执行相同的操作。 ``` brew install spatialindex ``` PiWind 演示模型使用内置的查找框架，因此运行 PiWind 或任何使用内置查找的模型都需要安装 `libspatialindex`。 #### GNU/Linux 对于 GNU/Linux，以下是所需系统库的具体列表 * **Debian**：g++ compiler build-essential, libtool, zlib1g-dev autoconf on debian distros sudo apt install g++ build-essential libtool zlib1g-dev autoconf * **Red Hat**：'Development Tools' and zlib-devel ### Python 包的 Python 依赖项由 `pip-tools` 控制。要首先安装开发依赖项，请使用以下命令安装 `pip-tools`： ``` pip install pip-tools ``` 并运行： ``` pip-sync ``` 要将新依赖项添加到开发需求中，请将包名称添加到 `requirements.in`，或者 要将新依赖项添加到已安装的包中，请将包名称添加到 `requirements-package.in`。 可以向包提供版本说明符，但这些应尽可能保持宽松，以便 所有包都可以轻松更新，并且在安装时会有更少的冲突。 将包添加到任一 `*.in` 文件后： ``` pip-compile && pip-sync ``` 应运行此命令以确保开发依赖项保持最新。 ### ods_tools OasisLMF 使用 ods_tools 包读取暴露文件和设置文件 与每个 OasisLMF 兼容的版本在需求文件中管理。 以下是摘要： - OasisLMF 2.3.x => 使用 ods_tools [3.2.x](https://github.com/OasisLMF/ODS_Tools/tree/stable/3.2.x) 或更高版本 - OasisLMF 2.4.x => 使用 ods_tools [4.0.x](https://github.com/OasisLMF/ODS_Tools/tree/stable/4.0.x) 或更高版本 - OasisLMF 2.5.x => 使用 ods_tools [5.0.x](https://github.com/OasisLMF/ODS_Tools/tree/stable/5.0.x) 或更高版本 ## 测试 要测试代码风格，请运行： ``` flake8 ``` 要针对所有支持的 Python 版本进行测试，请运行： ``` tox ``` 要针对当前安装的 Python 版本进行测试，请运行： ``` py.test ``` 要运行完整的测试套件，请运行： ``` ./runtests.sh ``` ## 发布 在发布最新版本的包之前，请确保增加 `oasislmf/__init__.py` 中的 `__version__` 值，并提交更改。您还需要安装 `twine` Python 包，`setuptools` 使用它在 PyPI 上发布包。如果要发布 wheels，您还需要安装 `wheel` Python 包。 ### 使用 `setup.py` 中的 `publish` 子命令 分发格式可以是源代码分发或特定平台的 wheel。要发布源代码分发包，请运行： ``` python setup.py publish --sdist ``` 或者发布特定平台的 wheel，请运行： ``` python setup.py publish --wheel ``` ### 为另一个平台创建 bdist 要为非主机平台创建分发，请使用 `--plat-name` 标志： ``` python setup.py bdist_wheel --plat-name Linux_x86_64 or python setup.py bdist_wheel --plat-name Darwin_x86_64 ``` ### 手动发布，带 GPG 签名 第一步是使用所需格式创建分发包：对于源代码分发，请运行： ``` python setup.py sdist ``` 这将在 `dist` 子文件夹中创建一个 `.tar.gz` 文件，或者对于特定平台的 wheel，请运行： ``` python setup.py bdist_wheel ``` 这将在 `dist` 子文件夹中创建 `.whl` 文件。要使用您的默认私钥附加 GPG 签名，您可以运行： ``` gpg --detach-sign -a dist/.{tar.gz,whl} ``` 这将创建名为 `.{tar.gz,whl}.asc` 的 `.asc` 签名文件。您可以直接使用签名发布包： ``` twine upload dist/.{tar.gz,whl} dist/.{tar.gz,whl}.asc ``` ## 文档 * Issues * Releases * General Oasis documentation * Model Development Kit (MDK) * Modules ## 许可证 本项目中的代码根据 BSD 3-clause 许可证授权。

标签：API, MDK, OasisLMF, Python, 保险损失, 保险科技, 再保险, 地面损失, 巨灾模型, 开源, 损失建模, 文档结构分析, 无后门, 模型开发包, 精算, 自然灾害, 逆向工具, 量化分析, 金融建模, 风险分析