jump-diffusion-estimation 0.2.0__py3-none-any.whl

jump_diffusion/validation/__init__.py

@@ -0,0 +1,14 @@
+"""
+Validation and Testing Tools
+
+This module provides tools for validating estimation methods
+through Monte Carlo experiments and diagnostic tests.
+"""
+
+from .monte_carlo import ValidationExperiment
+from .distribution_comparison import JumpDistributionComparison
+
+__all__ = [
+    "ValidationExperiment",
+    "JumpDistributionComparison",
+]

jump_diffusion/validation/distribution_comparison.py

@@ -0,0 +1,270 @@
+"""
+Jump-distribution goodness-of-fit comparison.
+
+This module fits JumpDiffusionEstimator under several candidate jump-size
+distributions on the same data and compares how well each one fits, via
+information criteria (AIC/BIC) and a Kolmogorov-Smirnov goodness-of-fit
+test whose p-value is obtained by parametric bootstrap, so it accounts for
+the fact that the parameters were estimated from the same data. The KS
+machinery only relies on ``JumpDistribution.rvs`` (through model
+simulation), so it works the same way for any current or future jump
+distribution.
+"""
+
+from typing import Any, Dict, Optional, Tuple
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+from scipy.stats import ks_2samp
+
+from ..distributions import JumpDistribution
+from ..estimation import JumpDiffusionEstimator
+from ..models.jump_diffusion import JumpDiffusionModel
+
+
+class JumpDistributionComparison:
+    """
+    Fits several jump-size distributions to the same data and compares
+    their goodness of fit.
+    """
+
+    def __init__(self, data: np.ndarray, dt: float):
+        """
+        Parameters:
+        -----------
+        data : np.ndarray
+            One-dimensional array of observed increments.
+        dt : float
+            Time step size between consecutive increments.
+        """
+        self.data = data
+        self.dt = dt
+        self.results: Dict[str, Dict[str, Any]] = {}
+
+    def _simulate_increments(
+        self,
+        model: JumpDiffusionModel,
+        size: int,
+        seed: Optional[int],
+    ) -> np.ndarray:
+        """Simulate ``size`` increments from ``model`` at this object's dt."""
+        _, path, _ = model.simulate(T=size * self.dt, n_steps=size, x0=0.0, seed=seed)
+        return np.diff(path)
+
+    def _parametric_bootstrap_ks_pvalue(
+        self,
+        jump_distribution: JumpDistribution,
+        fitted_model: JumpDiffusionModel,
+        ks_observed: float,
+        n_obs: int,
+        reference_size: int,
+        n_bootstrap: int,
+        seed: Optional[int],
+        estimate_kwargs: Dict[str, Any],
+    ) -> float:
+        """
+        Monte Carlo p-value for the KS goodness-of-fit statistic.
+
+        A plain two-sample KS p-value is invalid here because the reference
+        distribution was estimated from the very data being tested, which
+        makes the naive p-value strongly anti-conservative. The parametric
+        bootstrap restores validity: under the fitted (null) model we
+        simulate ``n_bootstrap`` datasets of the observed size, **re-fit** the
+        model on each, and recompute the KS distance of each dataset to its
+        own re-fitted model. The fraction of these bootstrap distances that
+        equal or exceed the observed one estimates the p-value, with the
+        usual ``(1 + count) / (n_successful + 1)`` small-sample correction.
+        Re-fitting inside the loop is what makes the test account for
+        estimation error.
+
+        Returns ``nan`` if ``n_bootstrap <= 0`` or no replicate converged.
+        """
+        if n_bootstrap <= 0:
+            return float("nan")
+
+        exceed = 0
+        n_successful = 0
+        for b in range(n_bootstrap):
+            data_seed = None if seed is None else seed + 1000 + b
+            boot_data = self._simulate_increments(fitted_model, n_obs, data_seed)
+
+            estimator = JumpDiffusionEstimator(
+                boot_data, self.dt, jump_distribution=jump_distribution
+            )
+            rep_result = estimator.estimate(**estimate_kwargs)
+            if not rep_result["convergence"]:
+                continue
+
+            model_b = JumpDiffusionModel(
+                jump_distribution=jump_distribution, **rep_result["parameters"]
+            )
+            ref_seed = None if seed is None else seed + 100_000 + b
+            reference_b = self._simulate_increments(model_b, reference_size, ref_seed)
+            ks_b = float(ks_2samp(boot_data, reference_b).statistic)
+            if ks_b >= ks_observed:
+                exceed += 1
+            n_successful += 1
+
+        if n_successful == 0:
+            return float("nan")
+        return (1.0 + exceed) / (n_successful + 1.0)
+
+    def fit(
+        self,
+        name: str,
+        jump_distribution: JumpDistribution,
+        seed: Optional[int] = None,
+        n_bootstrap: int = 199,
+        ks_reference_size: Optional[int] = None,
+        **estimate_kwargs: Any,
+    ) -> Dict[str, Any]:
+        r"""
+        Fit ``jump_distribution`` to the data and record its goodness of fit.
+
+        The KS statistic is the distance between the data and the fitted
+        model's distribution, the latter approximated by a large simulated
+        reference sample so that simulation noise in the statistic itself is
+        negligible. Its p-value is obtained by parametric bootstrap (see
+        :meth:`_parametric_bootstrap_ks_pvalue`), which is the dominant cost
+        of this method.
+
+        Parameters:
+        -----------
+        name : str
+            Label used to identify this fit in ``results``/``compare()``.
+        jump_distribution : JumpDistribution
+            Jump-size distribution to fit.
+        seed : int, optional
+            Base random seed. When given, the reference sample, the plotting
+            sample and every bootstrap replicate use distinct derived seeds,
+            so the whole ``fit`` is reproducible.
+        n_bootstrap : int
+            Number of parametric bootstrap replicates for the KS p-value.
+            Each re-fits the model, so cost scales linearly; set to ``0`` to
+            skip the p-value (it is then reported as ``nan``).
+        ks_reference_size : int, optional
+            Size of the reference sample used to evaluate the KS statistic.
+            Defaults to ``max(20 * n_obs, 20000)``. Larger values give a
+            more stable statistic at higher simulation cost.
+        \*\*estimate_kwargs : dict
+            Additional arguments forwarded to
+            ``JumpDiffusionEstimator.estimate`` (also used for every
+            bootstrap re-fit).
+
+        Returns:
+        --------
+        dict
+            The estimation results, extended with ``ks_statistic``,
+            ``ks_pvalue`` (parametric bootstrap), ``ks_n_bootstrap`` and
+            ``simulated_increments`` (an observation-sized sample kept for
+            :meth:`plot_comparison`).
+        """
+        estimator = JumpDiffusionEstimator(
+            self.data, self.dt, jump_distribution=jump_distribution
+        )
+        result = dict(estimator.estimate(**estimate_kwargs))
+
+        fitted_model = JumpDiffusionModel(
+            jump_distribution=jump_distribution, **result["parameters"]
+        )
+        n_obs = len(self.data)
+        reference_size = (
+            ks_reference_size
+            if ks_reference_size is not None
+            else max(20 * n_obs, 20000)
+        )
+
+        # Stable KS distance to the fitted model, via a large reference
+        # sample so the statistic is not dominated by simulation noise.
+        ref_seed = None if seed is None else seed
+        reference_increments = self._simulate_increments(
+            fitted_model, reference_size, ref_seed
+        )
+        ks_statistic = float(ks_2samp(self.data, reference_increments).statistic)
+
+        # A same-size sample kept only for the histogram overlay in
+        # plot_comparison (not used by the statistic).
+        plot_seed = None if seed is None else seed + 1
+        simulated_increments = self._simulate_increments(fitted_model, n_obs, plot_seed)
+
+        ks_pvalue = self._parametric_bootstrap_ks_pvalue(
+            jump_distribution,
+            fitted_model,
+            ks_statistic,
+            n_obs,
+            reference_size,
+            n_bootstrap,
+            seed,
+            estimate_kwargs,
+        )
+
+        result["ks_statistic"] = ks_statistic
+        result["ks_pvalue"] = ks_pvalue
+        result["ks_n_bootstrap"] = n_bootstrap
+        result["simulated_increments"] = simulated_increments
+
+        self.results[name] = result
+        return result
+
+    def compare(self) -> pd.DataFrame:
+        """
+        Summarize all fitted distributions, ranked by AIC (best first).
+        """
+        if not self.results:
+            print("No fits yet. Call fit() first.")
+            return pd.DataFrame()
+
+        rows = [
+            {
+                "distribution": name,
+                "log_likelihood": result["log_likelihood"],
+                "aic": result["aic"],
+                "bic": result["bic"],
+                "ks_statistic": result["ks_statistic"],
+                "ks_pvalue": result["ks_pvalue"],
+                "convergence": result["convergence"],
+            }
+            for name, result in self.results.items()
+        ]
+        return pd.DataFrame(rows).sort_values("aic").reset_index(drop=True)
+
+    def plot_comparison(
+        self,
+        bins: int = 50,
+        figsize: Tuple[float, float] = (12, 6),
+    ) -> None:
+        """
+        Overlay a histogram of the real data with each fitted
+        distribution's simulated sample.
+        """
+        if not self.results:
+            print("No fits yet. Call fit() first.")
+            return
+
+        plt.figure(figsize=figsize)
+        plt.hist(
+            self.data,
+            bins=bins,
+            density=True,
+            alpha=0.35,
+            color="black",
+            label="Datos reales",
+        )
+        for name, result in self.results.items():
+            plt.hist(
+                result["simulated_increments"],
+                bins=bins,
+                density=True,
+                alpha=0.35,
+                histtype="step",
+                linewidth=2,
+                label=f"Simulado ({name})",
+            )
+
+        plt.title("Comparación de distribuciones de salto")
+        plt.xlabel("Incremento")
+        plt.ylabel("Densidad")
+        plt.legend()
+        plt.grid(True, alpha=0.3)
+        plt.show()

jump_diffusion/validation/monte_carlo.py

@@ -0,0 +1,349 @@
+"""
+Monte Carlo validation experiments for jump-diffusion estimators.
+
+This module provides tools to validate estimation methods through
+controlled experiments with known parameters.
+"""
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+from typing import Dict, Any, List, Optional
+from ..simulation import JumpDiffusionSimulator
+from ..estimation import JumpDiffusionEstimator
+from ..distributions import JumpDistribution
+
+
+class ValidationExperiment:
+    """
+    Monte Carlo validation experiment for jump-diffusion estimators.
+
+    This class orchestrates validation experiments where we simulate
+    data with known parameters and test how well our estimators
+    can recover those parameters.
+    """
+
+    def __init__(
+        self,
+        true_params: Dict[str, float],
+        jump_distribution: Optional[JumpDistribution] = None,
+    ):
+        """
+        Initialize validation experiment.
+
+        Parameters:
+        -----------
+        true_params : dict
+            True parameter values to use for simulation
+        jump_distribution : JumpDistribution, optional
+            Jump size distribution to use for simulation and estimation
+        """
+        self.true_params = true_params
+        self.jump_distribution = jump_distribution
+        self.results: pd.DataFrame = pd.DataFrame()
+        self.completed_experiments = 0
+
+    def run_experiment(
+        self,
+        n_simulations: int = 10,
+        T: float = 1.0,
+        n_steps: int = 252,
+        x0: float = 100.0,
+        seed_base: int = 42,
+    ) -> pd.DataFrame:
+        """
+        Run Monte Carlo validation experiment.
+
+        Parameters:
+        -----------
+        n_simulations : int
+            Number of simulation runs
+        T : float
+            Time horizon for each simulation
+        n_steps : int
+            Number of time steps per simulation
+        x0 : float
+            Initial value
+        seed_base : int
+            Base seed for reproducibility
+
+        Returns:
+        --------
+        pd.DataFrame
+            Results of all experiments
+        """
+        print(f"Running {n_simulations} validation experiments...")
+        print(f"True parameters: {self.true_params}")
+
+        # Create simulator.
+        simulator = JumpDiffusionSimulator(
+            jump_distribution=self.jump_distribution,
+            **self.true_params,  # type: ignore[arg-type]
+        )
+
+        results: List[Dict[str, Any]] = []
+        successful_runs = 0
+
+        for i in range(n_simulations):
+            try:
+                # Simulate data
+                times, path, jumps = simulator.simulate_path(
+                    T=T, n_steps=n_steps, x0=x0, seed=seed_base + i
+                )
+
+                # Estimate parameters
+                increments = np.diff(path)
+                dt = times[1] - times[0]
+
+                estimator = JumpDiffusionEstimator(
+                    increments,
+                    dt,
+                    jump_distribution=self.jump_distribution,
+                )
+                est_results = estimator.estimate()
+
+                if est_results["convergence"]:
+                    # Store results
+                    row = {
+                        "simulation_id": i + 1,
+                        "seed": seed_base + i,
+                        "convergence": True,
+                        "log_likelihood": est_results["log_likelihood"],
+                        "aic": est_results["aic"],
+                        "bic": est_results["bic"],
+                    }
+
+                    # Add estimated parameters
+                    for param, value in est_results["parameters"].items():
+                        row[f"{param}_est"] = value
+                        row[f"{param}_true"] = self.true_params[param]
+                        row[f"{param}_error"] = value - self.true_params[param]
+                        row[f"{param}_rel_error"] = (
+                            (value - self.true_params[param])
+                            / self.true_params[param]
+                            * 100
+                        )
+
+                    results.append(row)
+                    successful_runs += 1
+                    print(
+                        f"✓ Experiment {i+1}/{n_simulations} completed "
+                        f"successfully",
+                    )
+                else:
+                    message = "✗ Experiment {}/{} failed to converge".format(
+                        i + 1,
+                        n_simulations,
+                    )
+                    print(message)
+
+            except Exception as e:
+                print(
+                    f"✗ Experiment {i+1}/{n_simulations} failed with error: "
+                    f"{str(e)}",
+                )
+
+        print(
+            f"\nCompleted: {successful_runs}/{n_simulations} successful "
+            f"experiments",
+        )
+
+        if successful_runs == 0:
+            print("No successful experiments. Cannot proceed with analysis.")
+            return pd.DataFrame()
+
+        self.results = pd.DataFrame(results)
+        self.completed_experiments = successful_runs
+
+        return self.results
+
+    def analyze_results(self) -> Dict[str, Any]:
+        """
+        Analyze validation results and compute statistics.
+
+        Returns:
+        --------
+        dict
+            Analysis results including bias, RMSE, etc.
+        """
+        if len(self.results) == 0:
+            print("No results to analyze. Run experiment first.")
+            return {}
+
+        param_names = [col[:-4] for col in self.results.columns if col.endswith("_est")]
+        analysis = {}
+
+        print("\n" + "=" * 60)
+        print("VALIDATION ANALYSIS RESULTS")
+        print("=" * 60)
+
+        for param in param_names:
+            true_val = self.true_params[param]
+            estimated_vals = self.results[f"{param}_est"]
+            errors = self.results[f"{param}_error"]
+            rel_errors = self.results[f"{param}_rel_error"]
+
+            stats = {
+                "true_value": true_val,
+                "mean_estimate": np.mean(estimated_vals),
+                "bias": np.mean(errors),
+                "rmse": np.sqrt(np.mean(errors**2)),
+                "mae": np.mean(np.abs(errors)),
+                "mean_rel_error": np.mean(rel_errors),
+                "std_estimate": np.std(estimated_vals),
+                "coverage_95": np.mean(
+                    np.abs(rel_errors) <= 5
+                ),  # Within 5% of true value
+            }
+
+            analysis[param] = stats
+
+            print(f"\n{param.upper()} (true: {true_val:.4f})")
+            print(f"  Mean estimate:    {stats['mean_estimate']:.6f}")
+            print(f"  Bias:            {stats['bias']:.6f}")
+            print(f"  RMSE:            {stats['rmse']:.6f}")
+            print(f"  Mean rel. error: {stats['mean_rel_error']:.2f}%")
+            print(f"  Std deviation:   {stats['std_estimate']:.6f}")
+            print(f"  95% accuracy:    {stats['coverage_95']:.1%}")
+
+        return analysis
+
+    def plot_results(self, figsize: tuple = (15, 10)):
+        """Create plots summarizing parameter estimation accuracy.
+
+        Parameters
+        ----------
+        figsize : tuple, optional
+            Width and height of the Matplotlib figure in inches.
+
+        Notes
+        -----
+        Generates a grid of subplots showing scatter plots for
+        each parameter and a summary bar chart of bias and RMSE. The
+        :meth:`run_experiment` method must be called beforehand to
+        populate ``self.results``. This function displays the plots
+        directly and returns ``None``.
+        """
+        if len(self.results) == 0:
+            print("No results to plot. Run experiment first.")
+            return
+
+        param_names = [col[:-4] for col in self.results.columns if col.endswith("_est")]
+        label_map = {
+            "mu": "Drift (μ)",
+            "sigma": "Volatility (σ)",
+            "jump_prob": "Jump Prob (p)",
+            "jump_scale": "Jump Scale",
+            "jump_skew": "Skewness (α)",
+            "jump_loc": "Jump Location",
+            "jump_nu": "Kurtosis (ν)",
+            "jump_xi": "Asymmetry (ξ)",
+            "jump_df": "Degrees of Freedom (df)",
+            "jump_prob_up": "Jump Prob Up (p_up)",
+            "jump_scale_up": "Jump Scale Up (η_up)",
+            "jump_scale_down": "Jump Scale Down (η_down)",
+        }
+        param_labels = [
+            label_map.get(p, p.replace("_", " ").title()) for p in param_names
+        ]
+
+        n_plots = len(param_names) + 1
+        n_cols = 3
+        n_rows = int(np.ceil(n_plots / n_cols))
+
+        fig, axes = plt.subplots(n_rows, n_cols, figsize=figsize)
+        axes = axes.flatten()
+
+        # Parameter accuracy plots
+        for i, (param, label) in enumerate(zip(param_names, param_labels)):
+            ax = axes[i]
+
+            true_val = self.true_params[param]
+            estimated_vals = self.results[f"{param}_est"]
+
+            # Scatter plot: estimated vs true
+            ax.scatter(
+                np.full_like(estimated_vals, true_val),
+                estimated_vals,
+                alpha=0.6,
+                s=50,
+            )
+
+            # Perfect estimation line
+            ax.axline(
+                (true_val, true_val),
+                slope=1,
+                color="red",
+                linestyle="--",
+                alpha=0.8,
+                label="Perfect Estimation",
+            )
+
+            # Confidence bands (±10% and ±20%)
+            ax.axhspan(
+                true_val * 0.9,
+                true_val * 1.1,
+                alpha=0.2,
+                color="green",
+                label="±10% band",
+            )
+            ax.axhspan(
+                true_val * 0.8,
+                true_val * 1.2,
+                alpha=0.1,
+                color="yellow",
+                label="±20% band",
+            )
+
+            ax.set_xlabel("True Value")
+            ax.set_ylabel("Estimated Value")
+            ax.set_title(f"{label}")
+            ax.grid(True, alpha=0.3)
+
+            if i == 0:  # Add legend to first plot
+                ax.legend()
+
+        # Summary statistics plot
+        ax = axes[len(param_names)]
+        param_biases = []
+        for param in param_names:
+            param_biases.append(np.mean(self.results[f"{param}_rel_error"]))
+        param_rmses = [
+            np.sqrt(np.mean(self.results[f"{param}_error"] ** 2))
+            / self.true_params[param]
+            * 100
+            for param in param_names
+        ]
+
+        x = np.arange(len(param_names))
+        width = 0.35
+
+        ax.bar(
+            x - width / 2,
+            np.abs(param_biases),
+            width,
+            label="|Bias| (%)",
+            alpha=0.7,
+        )
+        ax.bar(
+            x + width / 2,
+            param_rmses,
+            width,
+            label="Rel. RMSE (%)",
+            alpha=0.7,
+        )
+
+        ax.set_xlabel("Parameters")
+        ax.set_ylabel("Error (%)")
+        ax.set_title("Estimation Accuracy Summary")
+        ax.set_xticks(x)
+        ax.set_xticklabels(param_labels, rotation=45)
+        ax.legend()
+        ax.grid(True, alpha=0.3)
+
+        # Delete unused subplots
+        for j in range(n_plots, len(axes)):
+            fig.delaxes(axes[j])
+
+        plt.tight_layout()
+        plt.show()