pyreto 0.2.0__py3-none-any.whl

pyreto/__init__.py

@@ -0,0 +1,6 @@
+"""Pyreto: Tail risk management library."""
+
+from .distributions import fit
+
+__version__ = "0.2.0"
+__all__ = ["fit"]

pyreto/distributions/__init__.py

@@ -0,0 +1,8 @@
+"""Distributions module."""
+
+from .fit import fit
+from .student_t import StudentT
+from .alpha_stable import AlphaStable
+from .normal_inverse_gaussian import NormalInverseGaussian
+
+__all__ = ["fit", "StudentT", "AlphaStable", "NormalInverseGaussian"]

pyreto/distributions/alpha_stable.py

@@ -0,0 +1,103 @@
+"""Alpha-Stable distribution."""
+
+import numpy as np
+from scipy.optimize import minimize
+from scipy.integrate import quad
+from scipy.optimize import brentq
+from scipy.stats import norm
+from .base import DistributionFitter
+
+
+class AlphaStable(DistributionFitter):
+    """Alpha-Stable distribution."""
+    
+    def _char_func(self, t, alpha, beta, c, mu):
+        if alpha == 1:
+            return np.exp(1j * mu * t - c * np.abs(t) * (1 + 1j * beta * np.sign(t) * np.log(np.abs(t))))
+        else:
+            return np.exp(1j * mu * t - c**alpha * np.abs(t)**alpha * 
+                         (1 - 1j * beta * np.sign(t) * np.tan(np.pi * alpha / 2)))
+    
+    def _pdf(self, x, alpha, beta, c, mu):
+        if alpha == 2.0:
+            return norm.pdf(x, loc=mu, scale=c)
+        
+        t = np.linspace(-50, 50, 1024)
+        x = np.atleast_1d(x)
+        results = np.zeros_like(x)
+        
+        for i, xi in enumerate(x):
+            cf = self._char_func(t, alpha, beta, c, mu - xi)
+            dt = t[1] - t[0]
+            cf_sym = np.concatenate([cf, np.conj(cf[-1:0:-1])])
+            pdf_component = np.fft.ifft(cf_sym).real[:len(t)] * len(t) / (2 * np.pi)
+            results[i] = np.abs(pdf_component[0])
+        
+        return np.maximum(results, 1e-10)
+    
+    def fit(self) -> dict:
+        """Fit using MLE. Returns dict with alpha, beta, c, mu."""
+        def neg_loglik(params):
+            alpha, beta, c, mu = params
+            if not (0.1 < alpha <= 2.0) or not (-1 <= beta <= 1) or c <= 0:
+                return 1e10
+            try:
+                pdf_vals = self._pdf(self.returns, alpha, beta, c, mu)
+                if np.any(pdf_vals <= 0):
+                    return 1e10
+                return -np.sum(np.log(pdf_vals))
+            except:
+                return 1e10
+        
+        mu0 = np.mean(self.returns)
+        c0 = np.std(self.returns) / np.sqrt(2)
+        alpha0 = 1.8
+        beta0 = 0.0
+        x0 = np.array([alpha0, beta0, c0, mu0])
+        bounds = [(0.1, 2.0), (-0.999, 0.999), (1e-6, 10.0), (None, None)]
+        
+        res = minimize(neg_loglik, x0, method='Nelder-Mead',
+                      options={'maxiter': 500, 'xatol': 1e-6, 'fatol': 1e-6})
+        
+        alpha, beta, c, mu = res.x
+        self.params = {'alpha': alpha, 'beta': beta, 'c': c, 'mu': mu}
+        return self.params
+    
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        params = self.params
+        return self._pdf(x, params['alpha'], params['beta'], params['c'], params['mu'])
+    
+    def cdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        x = np.atleast_1d(x)
+        results = np.zeros_like(x)
+        for i, xi in enumerate(x):
+            results[i], _ = quad(lambda xx: self.pdf(np.array([xx]))[0], -np.inf, xi)
+        return results
+    
+    def ppf(self, q: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        q = np.atleast_1d(q)
+        results = np.zeros_like(q)
+        for i, qi in enumerate(q):
+            def f(x):
+                return self.cdf(np.array([x]))[0] - qi
+            results[i] = brentq(f, -10, 10)
+        return results
+    
+    def es(self, alpha: float) -> float:
+        if not (0 < alpha < 1):
+            raise ValueError("Alpha must be between 0 and 1")
+        if not self.params:
+            self.fit()
+        var = self.var(alpha)
+        
+        def integrand(x):
+            return x * self.pdf(np.array([x]))[0]
+        
+        es_val, _ = quad(integrand, -np.inf, var)
+        return es_val / alpha

pyreto/distributions/base.py

@@ -0,0 +1,48 @@
+"""Base class for distribution fitters."""
+
+import numpy as np
+from abc import ABC, abstractmethod
+
+
+class DistributionFitter(ABC):
+    """Abstract base class for distribution fitting."""
+    
+    def __init__(self, returns: np.ndarray):
+        returns = np.array(returns, dtype=np.float64).flatten()
+        if not np.isfinite(returns).all():
+            raise ValueError("Returns must be finite (no NaN or Inf)")
+        if len(returns) == 0:
+            raise ValueError("Returns cannot be empty")
+        self.returns = returns
+        self.params = {}
+    
+    @abstractmethod
+    def fit(self) -> dict:
+        """Fit distribution and return parameters."""
+        pass
+    
+    @abstractmethod
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        """Probability density function."""
+        pass
+    
+    @abstractmethod
+    def cdf(self, x: np.ndarray) -> np.ndarray:
+        """Cumulative distribution function."""
+        pass
+    
+    @abstractmethod
+    def ppf(self, q: np.ndarray) -> np.ndarray:
+        """Percent point function (inverse CDF)."""
+        pass
+    
+    @abstractmethod
+    def es(self, alpha: float) -> float:
+        """Expected Shortfall at significance level alpha."""
+        pass
+    
+    def var(self, alpha: float) -> float:
+        """Value at Risk (quantile) at significance level alpha."""
+        if not (0 < alpha < 1):
+            raise ValueError("Alpha must be between 0 and 1")
+        return self.ppf(np.array([alpha]))[0]

pyreto/distributions/fit.py

@@ -0,0 +1,86 @@
+"""Main fit function."""
+
+import numpy as np
+from .student_t import StudentT
+from .alpha_stable import AlphaStable
+from .normal_inverse_gaussian import NormalInverseGaussian
+
+
+MODEL_MAP = {
+    'student_t': StudentT,
+    'alpha_stable': AlphaStable,
+    'nig': NormalInverseGaussian,
+    'normal_inverse_gaussian': NormalInverseGaussian
+}
+
+
+def load_returns(data, column=None):
+    """Load and validate returns from various input types."""
+    try:
+        import polars as pl
+    except ImportError:
+        raise ImportError("Polars is required for DataFrame/CSV support. Install with: pip install polars")
+    
+    if isinstance(data, str):
+        df = pl.read_csv(data)
+        if column is None:
+            numeric_cols = [col for col, dtype in df.schema.items() 
+                           if dtype in [pl.Float64, pl.Float32, pl.Int64, pl.Int32]]
+            if len(numeric_cols) == 1:
+                column = numeric_cols[0]
+            else:
+                raise ValueError("Multiple numeric columns found. Specify column parameter.")
+        returns = df[column].to_numpy()
+    elif hasattr(data, 'to_numpy'):
+        if column is None:
+            numeric_cols = [col for col, dtype in data.schema.items() 
+                           if dtype in [pl.Float64, pl.Float32, pl.Int64, pl.Int32]]
+            if len(numeric_cols) == 1:
+                column = numeric_cols[0]
+            else:
+                raise ValueError("Multiple numeric columns found. Specify column parameter.")
+        returns = data[column].to_numpy()
+    elif isinstance(data, np.ndarray):
+        returns = data.flatten()
+    elif isinstance(data, list):
+        returns = np.array(data)
+    else:
+        raise TypeError(f"Unsupported data type: {type(data)}")
+    
+    returns = returns.astype(np.float64)
+    if not np.isfinite(returns).all():
+        raise ValueError("Returns contain non-finite values (NaN or Inf)")
+    if len(returns) == 0:
+        raise ValueError("Returns cannot be empty")
+    
+    return returns
+
+
+def fit(data, column=None, model='student_t'):
+    """Fit a single distribution model to returns data.
+    
+    Parameters
+    ----------
+    data : str, DataFrame, np.ndarray, or list
+        Returns data
+    column : str, optional
+        Column name if data is DataFrame or CSV
+    model : str
+        Model to fit: 'student_t', 'alpha_stable', 'nig'
+        
+    Returns
+    -------
+    DistributionFitter
+        Fitted distribution object
+    """
+    returns = load_returns(data, column)
+    model_name = model.lower()
+    
+    if model_name not in MODEL_MAP:
+        raise ValueError(f"Unknown model: {model}. Available: {list(MODEL_MAP.keys())}")
+    
+    ModelClass = MODEL_MAP[model_name]
+    instance = ModelClass(returns)
+    instance.fit()
+    
+    return instance

pyreto/distributions/normal_inverse_gaussian.py

@@ -0,0 +1,83 @@
+"""Normal-Inverse Gaussian distribution."""
+
+import numpy as np
+from scipy.optimize import minimize
+from scipy.special import kv as bessel_k
+from scipy.integrate import quad
+from scipy.optimize import brentq
+from .base import DistributionFitter
+
+
+class NormalInverseGaussian(DistributionFitter):
+    """Normal-Inverse Gaussian distribution."""
+    
+    def _pdf(self, x, alpha, beta, delta, mu):
+        gamma = np.sqrt(alpha**2 - beta**2)
+        z = (x - mu) / delta
+        factor = alpha * delta * np.sqrt(1 + z**2)
+        numerator = alpha * delta * bessel_k(1, factor)
+        denominator = np.pi * np.sqrt(1 + z**2)
+        return (numerator / denominator) * np.exp(delta * gamma + beta * (x - mu))
+    
+    def fit(self) -> dict:
+        """Fit using MLE. Returns dict with alpha, beta, delta, mu."""
+        def neg_loglik(params):
+            alpha, beta, delta, mu = params
+            if alpha <= 0 or delta <= 0 or abs(beta) >= alpha:
+                return 1e10
+            try:
+                pdf_vals = self._pdf(self.returns, alpha, beta, delta, mu)
+                return -np.sum(np.log(pdf_vals))
+            except:
+                return 1e10
+        
+        mu0 = np.mean(self.returns)
+        delta0 = np.std(self.returns) * 0.8
+        alpha0 = 2.0
+        beta0 = 0.0
+        x0 = np.array([alpha0, beta0, delta0, mu0])
+        bounds = [(1e-4, 50), (-49, 49), (1e-4, 50), (None, None)]
+        
+        res = minimize(neg_loglik, x0, method='SLSQP', bounds=bounds,
+                      options={'ftol': 1e-8, 'maxiter': 1000})
+        
+        alpha, beta, delta, mu = res.x
+        self.params = {'alpha': alpha, 'beta': beta, 'delta': delta, 'mu': mu, 
+                      'gamma': np.sqrt(alpha**2 - beta**2)}
+        return self.params
+    
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        return self._pdf(x, **{k: self.params[k] for k in ['alpha', 'beta', 'delta', 'mu']})
+    
+    def cdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        results = np.zeros_like(x)
+        for i, xi in enumerate(x):
+            results[i], _ = quad(lambda xx: self.pdf(np.array([xx]))[0], -np.inf, xi)
+        return results
+    
+    def ppf(self, q: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        results = np.zeros_like(q)
+        for i, qi in enumerate(q):
+            def f(x):
+                return self.cdf(np.array([x]))[0] - qi
+            results[i] = brentq(f, -10, 10)
+        return results
+    
+    def es(self, alpha: float) -> float:
+        if not (0 < alpha < 1):
+            raise ValueError("Alpha must be between 0 and 1")
+        if not self.params:
+            self.fit()
+        var = self.var(alpha)
+        
+        def integrand(x):
+            return x * self.pdf(np.array([x]))[0]
+        
+        es_val, _ = quad(integrand, -np.inf, var)
+        return es_val / alpha

pyreto/distributions/student_t.py

@@ -0,0 +1,44 @@
+"""Student's T distribution."""
+
+import numpy as np
+from scipy.stats import t as student_t
+from scipy.integrate import quad
+from .base import DistributionFitter
+
+
+class StudentT(DistributionFitter):
+    """Student's T distribution."""
+    
+    def fit(self) -> dict:
+        """Fit using MLE. Returns dict with df, loc, scale."""
+        df, loc, scale = student_t.fit(self.returns)
+        self.params = {'df': df, 'loc': loc, 'scale': scale}
+        return self.params
+    
+    def pdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        return student_t.pdf(x, **self.params)
+    
+    def cdf(self, x: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        return student_t.cdf(x, **self.params)
+    
+    def ppf(self, q: np.ndarray) -> np.ndarray:
+        if not self.params:
+            self.fit()
+        return student_t.ppf(q, **self.params)
+    
+    def es(self, alpha: float) -> float:
+        if not (0 < alpha < 1):
+            raise ValueError("Alpha must be between 0 and 1")
+        if not self.params:
+            self.fit()
+        var = self.var(alpha)
+        
+        def integrand(x):
+            return x * self.pdf(np.array([x]))[0]
+        
+        es_val, _ = quad(integrand, -np.inf, var)
+        return es_val / alpha

pyreto-0.2.0.dist-info/METADATA

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: pyreto
+Version: 0.2.0
+Summary: Tail risk management library
+Author-email: Developer <dev@example.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+
+# pyreto
+
+Tail risk management library.
+
+## Installation
+
+```bash
+pip install pyreto
+```
+
+Requires: numpy, scipy
+Optional: polars (for CSV/DataFrame support)
+
+## Usage
+
+```python
+import pyreto
+
+# Fit Student's T distribution
+model = pyreto.dist.fit('returns.csv', column='daily_return', model='student_t')
+
+# Calculate 1% Expected Shortfall
+es_1 = model.es(0.01)
+
+# Calculate 5% Value at Risk  
+var_5 = model.var(0.05)
+
+# Get fitted parameters
+params = model.params
+```
+
+## Models
+
+- `student_t`: Student's T distribution (recommended)
+- `alpha_stable`: Alpha stable distribution (flexible, slower)
+- `nig`: Normal-inverse Gaussian (good middle ground)
+
+## API
+
+All models support:
+- `fit()` - Fit parameters
+- `pdf(x)` - Density function
+- `cdf(x)` - Distribution function
+- `ppf(q)` - Quantile function
+- `var(alpha)` - Value at Risk
+- `es(alpha)` - Expected Shortfall
+- `params` - Fitted parameters dict
+
+## Example
+
+```python
+import numpy as np
+import pyreto
+
+# Generate heavy-tailed returns
+returns = np.random.standard_t(3, 1000) * 0.01
+
+# Fit and calculate tail risk
+model = pyreto.dist.fit(returns, model='student_t')
+print(f"5% VaR: {model.var(0.05):.4f}")
+print(f"5% ES:  {model.es(0.05):.4f}")
+```
+
+## Error Handling
+
+The library fails loudly on invalid inputs:
+- Non-finite values (NaN, Inf) throw `ValueError`
+- Invalid alpha values throw `ValueError`
+- Missing parameters throw `ValueError`

pyreto-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pyreto/__init__.py,sha256=yfQfScj6LZ9z_4kj9FUhYz5m5msxEcg3KW7ZQN0z44U,117
+pyreto/distributions/__init__.py,sha256=11IhaYFDoth3-b_HbMHT1nG4ZUmMpE6wgz8yLUE3eZI,250
+pyreto/distributions/alpha_stable.py,sha256=f5yktEuCPdHosY7FwaNvbrINec5JK6PQ_EPiwFBt9p8,3622
+pyreto/distributions/base.py,sha256=uBG6ksORlwBs1Tx3aJpDS0qlUp-GP7jhQRMzSLoW-WU,1474
+pyreto/distributions/fit.py,sha256=QAXixS7dAHmR1IMLtRQ_eX7ZkSDGcLyNZi6I6myjzFQ,2795
+pyreto/distributions/normal_inverse_gaussian.py,sha256=0phdT1BFucX58Ps34JfeyWL18m3OuW_dosYjMwmLAog,2964
+pyreto/distributions/student_t.py,sha256=WQdHxVHBn6AJKE3RkwfbaEU_cQug6Neoqg2TdicHIII,1318
+pyreto-0.2.0.dist-info/METADATA,sha256=ujtd_zw9UyLRql6x3caPjgvNVReNduIXztl1JZJbLBw,1732
+pyreto-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyreto-0.2.0.dist-info/top_level.txt,sha256=W3ftAjmrhZHXGDjIYS5P1eimmjeytWJ2FsSnViAyAGs,7
+pyreto-0.2.0.dist-info/RECORD,,

pyreto-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyreto-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyreto