Merge pull request #25 from mu373/change-result-return-type

mu373 · web-flow · commit c75a6e1305df · 2025-04-11T16:25:09.000-04:00
Update documentation for result arguments
diff --git a/docs/api.rst b/docs/api.rst
@@ -1,5 +1,5 @@
 API Reference
-============
+=============
 
 This section provides detailed API documentation for the tailestim package.
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -23,11 +23,15 @@
 
 extensions = [
     'sphinx.ext.autodoc',
+    'numpydoc',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
 ]
 
+numpydoc_show_class_members = False
+autodoc_typehints = "none"
+
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = True
diff --git a/docs/estimators/hill.rst b/docs/estimators/hill.rst
@@ -1,5 +1,5 @@
 Hill Estimator
-=============
+===============
 
 .. currentmodule:: tailestim.estimators
 
diff --git a/docs/estimators/kernel.rst b/docs/estimators/kernel.rst
@@ -1,5 +1,5 @@
 Kernel-Type Estimator
-==================
+======================
 
 .. currentmodule:: tailestim.estimators
 
diff --git a/docs/estimators/moments.rst b/docs/estimators/moments.rst
@@ -1,5 +1,5 @@
 Moments Estimator
-================
+==================
 
 .. currentmodule:: tailestim.estimators
 
diff --git a/docs/estimators/pickands.rst b/docs/estimators/pickands.rst
@@ -1,5 +1,5 @@
 Pickands Estimator
-================
+==================
 
 .. currentmodule:: tailestim.estimators
 
diff --git a/docs/estimators/smooth_hill.rst b/docs/estimators/smooth_hill.rst
@@ -1,5 +1,5 @@
 Smooth Hill Estimator
-===================
+=====================
 
 .. currentmodule:: tailestim.estimators
 
diff --git a/docs/index.rst b/docs/index.rst
@@ -27,7 +27,7 @@ Contents
    api
 
 References
----------
+------------
 
 - I. Voitalov, P. van der Hoorn, R. van der Hofstad, and D. Krioukov. Scale-free networks well done. *Phys. Rev. Res.*, Oct. 2019, doi: `10.1103/PhysRevResearch.1.033034 <https://doi.org/10.1103/PhysRevResearch.1.033034>`_.
 - I. Voitalov. `ivanvoitalov/tail-estimation <https://github.com/ivanvoitalov/tail-estimation>`_, GitHub. Mar. 2018.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,3 +1,4 @@
 sphinx>=8.0.0
 pydata-sphinx-theme>=0.15.0
-sphinx-autodoc-typehints>=1.25.0
+sphinx-autodoc-typehints>=1.25.0
+numpydoc>=2.0.0
diff --git a/docs/result.rst b/docs/result.rst
@@ -5,3 +5,25 @@ Result Class
    :members:
    :undoc-members:
    :show-inheritance:
+
+Examples
+--------
+.. code-block:: python
+
+   from tailestim import TailData
+   from tailestim import HillEstimator
+   
+   data = TailData(name='Pareto').data
+   
+   # Initialize and fit Hill estimator
+   hill = HillEstimator()
+   hill.fit(data)
+   
+   # Get estimated parameters
+   result = hill.get_parameters() # This returns TailEstimatorResult class.
+   print(result)
+
+   # Access individual parameters
+   gamma = result.gamma  # Power-law exponent estimate
+   xi = result.xi  # Tail index estimate
+ 
diff --git a/examples/example.ipynb b/examples/example.ipynb
@@ -0,0 +1,153 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "id": "ec147002",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tailestim import TailData\n",
+    "from tailestim import HillEstimator, KernelTypeEstimator, MomentsEstimator"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "id": "982e732d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Load a built-in dataset\n",
+    "data = TailData(name='CAIDA_KONECT').data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 25,
+   "id": "f4f528d1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Example of loading a custom dataset\n",
+    "# custom_data = TailData(path='path/to/my/data.dat').data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "id": "31de6947",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "--------------------------------------------------\n",
+      "Estimator Type: HillEstimator\n",
+      "--------------------------------------------------\n",
+      "Fitted: Yes\n",
+      "Arguments:\n",
+      "  bootstrap: True\n",
+      "  base_seed: 1\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Initialize and fit the Hill estimator\n",
+    "estimator = HillEstimator(base_seed=1)\n",
+    "estimator.fit(data)\n",
+    "print(estimator)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "id": "f8820501",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get the estimated parameters\n",
+    "result = estimator.get_parameters()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "id": "a8fbf1b9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Get the power law exponent\n",
+    "gamma = result.gamma"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "1ae9abc5",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "--------------------------------------------------\n",
+      "Result\n",
+      "--------------------------------------------------\n",
+      "Order statistics: Array of shape (26474,) [1.0000, 2.0000, 3.0000, ...]\n",
+      "Tail index estimates: Array of shape (26474,) [0.2474, 0.3125, 0.2214, ...]\n",
+      "Optimal order statistic (k*): 22936\n",
+      "Tail index (ξ): 0.7651\n",
+      "Power law exponent (γ): 2.3070\n",
+      "Bootstrap Results: \n",
+      "  First Bootstrap: \n",
+      "    Fraction of order statistics: None\n",
+      "    AMSE values: None\n",
+      "    Minimum AMSE fraction: 0.8666\n",
+      "    Maximum index: 18532\n",
+      "  Second Bootstrap: \n",
+      "    Fraction of order statistics: None\n",
+      "    AMSE values: None\n",
+      "    Minimum AMSE fraction: 0.8666\n",
+      "    Maximum index: 13103\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Print full results\n",
+    "print(result)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4765595b",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "tailestim",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/src/tailestim/estimators/base.py b/src/tailestim/estimators/base.py
@@ -67,8 +67,16 @@ def get_parameters(self) -> TailEstimatorResult:
         Returns
         -------
         TailEstimatorResult
-            Object containing the estimated parameters.
-            The structure depends on the specific estimation method.
+            Object containing the estimated parameters. Parameters and results included varies by method.
+
+        Examples
+        --------
+        >>> hill = HillEstimator()
+        >>> hill.fit(data)
+        >>> result = hill.get_parameters()
+        >>> gamma = result.gamma  # Access the tail index
+        >>> xi = result.xi  # Access the shape parameter (if available)
+
         """
         if self.results is None:
             raise ValueError("Model not fitted yet. Call fit() first.")
diff --git a/src/tailestim/estimators/hill.py b/src/tailestim/estimators/hill.py
@@ -77,18 +77,27 @@ def _estimate(self, ordered_data: np.ndarray) -> Tuple:
 
     def get_parameters(self) -> TailEstimatorResult:
         """Get the estimated parameters.
-        
+
+        Attributes
+        ----------
+        xi_star : float
+            Optimal tail index estimate (ξ).
+        gamma : float
+            Power law exponent (γ).
+        k_arr : np.ndarray
+            Array of order statistics.
+        xi_arr : np.ndarray
+            Array of tail index estimates.
+        k_star : float
+            Optimal order statistic (k*).
+        bootstrap_results : dict
+            Bootstrap results.
+
         Returns
         -------
         TailEstimatorResult
-            Object containing:
-            - k_arr: Array of order statistics
-            - xi_arr: Array of tail index estimates
-            - k_star: Optimal order statistic (if bootstrap=True)
-            - xi_star: Optimal tail index estimate (if bootstrap=True)
-            - gamma: Power law exponent (if bootstrap=True)
-            - bootstrap_results: Bootstrap details (if bootstrap=True)
         """
+
         if self.results is None:
             raise ValueError("Model not fitted yet. Call fit() first.")
         
diff --git a/src/tailestim/estimators/kernel.py b/src/tailestim/estimators/kernel.py
@@ -89,17 +89,25 @@ def _estimate(self, ordered_data: np.ndarray) -> Tuple:
 
     def get_parameters(self) -> TailEstimatorResult:
         """Get the estimated parameters.
+
+        Attributes
+        ----------
+        xi_star : float
+            Optimal tail index estimate (ξ).
+        gamma : float
+            Power law exponent (γ).
+        k_arr : np.ndarray
+            Array of order statistics.
+        xi_arr : np.ndarray
+            Array of tail index estimates.
+        k_star : float
+            Optimal order statistic (k*).
+        bootstrap_results : dict
+            Bootstrap results.
         
         Returns
         -------
-        Dict[str, Any]
-            Dictionary containing:
-            - k_arr: Array of order statistics
-            - xi_arr: Array of tail index estimates
-            - k_star: Optimal order statistic (if bootstrap=True)
-            - xi_star: Optimal tail index estimate (if bootstrap=True)
-            - gamma: Power law exponent (if bootstrap=True)
-            - bootstrap_results: Bootstrap details (if bootstrap=True)
+        TailEstimatorResult
         """
         if self.results is None:
             raise ValueError("Model not fitted yet. Call fit() first.")
diff --git a/src/tailestim/estimators/moments.py b/src/tailestim/estimators/moments.py
@@ -77,17 +77,25 @@ def _estimate(self, ordered_data: np.ndarray) -> Tuple:
 
     def get_parameters(self) -> TailEstimatorResult:
         """Get the estimated parameters.
-        
+
+        Attributes
+        ----------
+        xi_star : float
+            Optimal tail index estimate (ξ).
+        gamma : float
+            Power law exponent (γ).
+        k_arr : np.ndarray
+            Array of order statistics.
+        xi_arr : np.ndarray
+            Array of tail index estimates.
+        k_star : float
+            Optimal order statistic (k*).
+        bootstrap_results : dict
+            Bootstrap results.
+
         Returns
         -------
-        Dict[str, Any]
-            Dictionary containing:
-            - k_arr: Array of order statistics
-            - xi_arr: Array of tail index estimates
-            - k_star: Optimal order statistic (if bootstrap=True)
-            - xi_star: Optimal tail index estimate (if bootstrap=True)
-            - gamma: Power law exponent (if bootstrap=True)
-            - bootstrap_results: Bootstrap details (if bootstrap=True)
+        TailEstimatorResult
         """
         if self.results is None:
             raise ValueError("Model not fitted yet. Call fit() first.")
diff --git a/src/tailestim/estimators/pickands.py b/src/tailestim/estimators/pickands.py
diff --git a/src/tailestim/estimators/result.py b/src/tailestim/estimators/result.py
diff --git a/src/tailestim/estimators/smooth_hill.py b/src/tailestim/estimators/smooth_hill.py
