catadjust 0.1.0__tar.gz

catadjust-0.1.0/.gitignore

@@ -0,0 +1,161 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+.DS_Store

catadjust-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mutahar Chalmers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

catadjust-0.1.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: catadjust
+Version: 0.1.0
+Summary: Adjustment tools for catastrophe models
+Project-URL: Homepage, https://github.com/MutaharChalmers/catadjust
+Author-email: Mutahar Chalmers <mutahar.chalmers@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Mutahar Chalmers
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Description-Content-Type: text/markdown
+
+# CatAdjust - Tools for adjusting catastrophe models
+Current tools:
+- Hazard ELT Adjustment Tool - Given a location-level ELT with hazard values, and a collection of *target* hazard EEF curves at all locations, this tool adjusts the rates of all events in the ELT, such that the hazard EEF curves from the rate-adjusted ELT match the target hazard EEF curves as closely as possible.
+
+Future tools:
+- Loss Adjustment Tool - Given a stochastic ELT or YLT from a catastrophe model, and some historic loss experience, this tool adjusts the losses in the ELT or YLT such that the adjusted OEP curve matches the empirical historic loss OEP curve over some user-defined range.
+
+- Industry Loss Conversion Tool - Given two stochastic industry ELTs or YLTs with losses at sub-national (e.g. CRESTA) level, scale the losses from one ELT/YLT such that the EP curves match the EP curves derived from the other ELT/YLT both at aggregate and sub-national level.
+ 
+

catadjust-0.1.0/README.md

@@ -0,0 +1,10 @@
+# CatAdjust - Tools for adjusting catastrophe models
+Current tools:
+- Hazard ELT Adjustment Tool - Given a location-level ELT with hazard values, and a collection of *target* hazard EEF curves at all locations, this tool adjusts the rates of all events in the ELT, such that the hazard EEF curves from the rate-adjusted ELT match the target hazard EEF curves as closely as possible.
+
+Future tools:
+- Loss Adjustment Tool - Given a stochastic ELT or YLT from a catastrophe model, and some historic loss experience, this tool adjusts the losses in the ELT or YLT such that the adjusted OEP curve matches the empirical historic loss OEP curve over some user-defined range.
+
+- Industry Loss Conversion Tool - Given two stochastic industry ELTs or YLTs with losses at sub-national (e.g. CRESTA) level, scale the losses from one ELT/YLT such that the EP curves match the EP curves derived from the other ELT/YLT both at aggregate and sub-national level.
+ 
+

catadjust-0.1.0/catadjust/__init__.py

@@ -0,0 +1 @@
+from .hazelt_adjust import HazardELTAdjustment

catadjust-0.1.0/catadjust/hazelt_adjust.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import numpy as np
+import pandas as pd
+from tqdm.auto import tqdm
+
+
+class HazardELTAdjustment:
+    """Adjust a catastrophe model location-level ELT with hazard values
+    to match arbitrary target location-level hazard EEF curves as closely
+    as possible by scaling event rates.
+    """
+    def __init__(self, elt_raw, loccol, eventcol, ratecol, hazcol):
+        """Load raw location-level ELT and pre-process.
+
+        Parameters
+        ----------
+        elt_raw : DataFrame
+            Raw location-level ELT.
+        loccol: str
+            Name of column containing locationIDs.
+        eventcol: str
+            Name of column containing eventIDs.
+        ratecol: str
+            Name of column containing event rates.
+        hazcol: str
+            Name of column containing event-location hazard intensity.
+        """
+
+        # Load ELT to be adjusted and pre-process
+        elt = elt_raw.astype({loccol: np.int64, eventcol: np.int64,
+                              ratecol: np.float64, hazcol: np.float64}
+                            ).drop_duplicates([loccol, eventcol]
+                                             ).sort_values([loccol, hazcol], ascending=[True, False])
+        self.loccol = loccol
+        self.eventcol = eventcol
+        self.ratecol = ratecol
+        self.hazcol = hazcol
+        self.elt = self.calc_eef(elt)
+        m = self.elt.shape[0]
+
+        # Sorted array of unique eventIDs
+        eventIDs_unique = np.sort(self.elt[eventcol].unique())
+        self.nevents = eventIDs_unique.size
+
+        # Convert eventIDs in ELT to indices in event array
+        self.loceventixs = np.searchsorted(eventIDs_unique, self.elt[eventcol])
+
+        # Indices in ELT where location changes
+        locbreaks = np.nonzero(np.diff(self.elt[loccol]))[0] + 1
+        self.loc_slicers = np.stack([np.r_[0, locbreaks], np.r_[locbreaks, m]]).T
+
+    def calc_eef(self, elt):
+        """Calculate EEFs from a location-level ELT sorted by descending hazard.
+
+        Parameters
+        ----------
+        elt : DataFrame
+            Processed and sorted (in descending hazard intensity) location-level ELT.
+
+        Returns
+        -------
+        elt : DataFrame
+            Input ELT with additional EEF column.
+        """
+
+        elt['eef'] = elt.groupby(self.loccol, sort=False)[self.ratecol].transform(np.cumsum)
+        return elt
+
+    def adjust(self, eefs_targ, x0=None, min_rate=1e-12, tol=1e-4, niter=1000, alpha=0.001):
+        """Adjust ELT to match location-level hazard curves.
+
+        Parameters
+        ----------
+        eefs_targ : Series or ndarray
+            Target EEFs in the same order as the processed ELT.
+        x0 : Series or ndarray, optional
+            Initial guess to use for rate adjustment.
+        min_rate : float, optional
+            Minimum allowable rate constraint.
+        tol : float, optional
+            Convergence criterion for cost function. Iteration stops
+            once the cost function (mean square error) is less than this value.
+        niter : int, optional
+            Maximum number of iterations.
+        alpha : float, optional
+            Learning rate in Adam gradient descent algorithm.
+
+        Returns
+        -------
+        elt_adj : DataFrame
+            Adjusted ELT.
+        res : dict
+            Results dict.
+        fs : ndarray
+            Learning curve.
+        """
+
+        if x0 is None:
+            x0 = self.elt.groupby(self.eventcol)[self.ratecol].mean().values
+        else:
+            x0 = np.array(x0)
+
+        eefs_targ = np.array(eefs_targ)
+        args = (eefs_targ,)
+        res, fs = self._adam(self._cost, x0, args, alpha=alpha, niter=niter, tol=tol, amin=min_rate)
+        elt_adj = self.elt.copy()
+        elt_adj[self.ratecol] = res['x'][self.loceventixs]
+        elt_adj = self.calc_eef(elt_adj)
+        return elt_adj, res, fs
+
+    def _cost(self, theta, eefs_targ):
+        """Cost function for fitting an ELT to a target EEF by adjusting event rates.
+
+        Parameters
+        ----------
+        theta : ndarray
+            Rates to calculate cost function for, in unique eventID order.
+        eefs_targ : ndarray
+            Target EEFs for location-events in the same order as the
+            pre-processed ELT.
+
+        Returns
+        -------
+        cost : float
+            Cost function evaluated at theta.
+        cost_grad : ndarray
+            Gradient of cost function.
+        """
+
+        # Calculate EEFs for each location by chunked cumulative sums
+        eefs_pred = np.empty_like(eefs_targ)
+
+        # Expand event rates to event-location rates
+        rates = theta[self.loceventixs]
+        for a, b in self.loc_slicers:
+            eefs_pred[a:b] = rates[a:b].cumsum()
+
+        # Calculate deltas and cost function for current parameters
+        deltas = eefs_pred - eefs_targ
+        cost = (deltas**2).mean()
+
+        # Calculate gradient of cost function wrt to event rates
+        grad_cost = np.zeros_like(theta)
+        for a, b in self.loc_slicers:
+            grad_cost[self.loceventixs[a:b]] += deltas[a:b][::-1].cumsum()[::-1]
+
+        return cost, 2*grad_cost/deltas.size
+
+    def _adam(self, fun, x0, args=(), alpha=0.001, beta1=0.9, beta2=0.999,
+              eps=1e-8, niter=1000, tol=1e-6, amin=-np.inf, amax=np.inf):
+        """Adaptive Moment Estimation gradient descent with weight clipping.
+
+        Parameters
+        ----------
+        cost : function
+            Cost function which returns cost and gradient.
+        x0 : ndarray
+            Initial values for optimisation.
+        args : tuple, optional
+            Arguments to be passed to cost function.
+        alpha : float, optional
+            Learning rate.
+        beta1 : float, optional
+            Exponential decay rate for gradient momentum.
+        beta2 : float, optional
+            Exponential decay rate for gradient variance.
+        tol : float, optional
+            Convergence criterion for cost function. Iteration stops
+            once the cost function (mean square error) is less than this value.
+        amin : float, optional
+            Minimum value allowed for input values.
+        amax : float, optional
+            Maximum value allowed for input values.
+
+        Returns
+        -------
+        cost : float
+            Cost function evaluated at theta.
+        cost_grad : ndarray
+            Gradient of cost function.
+        """
+
+        x, m, v = x0, 0, 0
+        fs = np.zeros(niter)
+
+        pbar = tqdm(range(niter))
+        for i in pbar:
+            fs[i], grad = fun(x, *args)
+
+            pbar.set_description(f'f={fs[i]:.2e}{">" if fs[i] > tol else "<="}{tol:.2e}')
+            if fs[i] < tol:
+                return dict(x=x, fun=fs[i], jac=grad, nit=i), fs
+
+            # Estimates of first and second moment of gradient
+            m = (1 - beta1)*grad + beta1*m
+            v = (1 - beta2)*grad**2 + beta2*v
+
+            # Bias correction
+            mhat = m/(1 - beta1**(i+1))
+            vhat = v/(1 - beta2**(i+1))
+
+            # Update step
+            x = x - alpha * mhat/(np.sqrt(vhat) + eps)
+
+            # Weight clipping
+            x = np.clip(x, amin, amax)
+
+        f, grad = fun(x, *args)
+        print('Warning: Iteration limit reached before cost function converged within tolerance')
+        return dict(x=x, fun=f, jac=grad, nit=i), fs

catadjust-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "catadjust"
+version = "0.1.0"
+description = "Adjustment tools for catastrophe models"
+authors = [
+           { name = "Mutahar Chalmers", email = "mutahar.chalmers@gmail.com" },
+]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+requires-python = ">=3.8"
+dependencies = [
+  "numpy>=1.24", "pandas>=2.0"
+]
+
+[project.urls]
+"Homepage" = "https://github.com/MutaharChalmers/catadjust"