Merge pull request #24 from mu373/dev

Add base_seed and change output type

Author: mu373

README.md

@@ -40,10 +40,10 @@ estimator.fit(data)
 result = estimator.get_parameters()
 
 # Get the power law exponent
-gamma = result['gamma']
+gamma = result.gamma
 
 # Print full results
-print(estimator)
+print(result)
 ```
 
 ### Using degree sequence from networkx graphs
@@ -63,10 +63,10 @@ estimator.fit(degree)
 result = estimator.get_parameters()
 
 # Get the power law exponent
-gamma = result['gamma']
+gamma = result.gamma
 
 # Print full results
-print(estimator)
+print(result)
 ```
 
 ## Available Estimators
@@ -96,22 +96,27 @@ The full result can be obtained by `estimator.get_parameters()`, which returns a
   - Optimal bandwidths or minimum AMSE fractions
 
 ## Example Output
-When you `print(estimator)` after fitting, you will get the following output.
+When you `print(result)` after fitting, you will get the following output.
 ```
-==================================================
-Tail Estimation Results (HillEstimator)
-==================================================
-
-Parameters:
---------------------
-Optimal order statistic (k*): 26708
-Tail index (ξ): 0.3974
-Gamma (powerlaw exponent) (γ): 3.5167
-
-Bootstrap Results:
---------------------
-First bootstrap minimum AMSE fraction: 0.2744
-Second bootstrap minimum AMSE fraction: 0.2745
+--------------------------------------------------
+Result
+--------------------------------------------------
+Order statistics: Array of shape (200,) [1.0000, 1.0000, 1.0000, ...]
+Tail index estimates: Array of shape (200,) [1614487461647431761920.0000, 1249994621547387551744.0000, 967791073562264862720.0000, ...]
+Optimal order statistic (k*): 25153
+Tail index (ξ): 0.5942
+Power law exponent (γ): 2.6828
+Bootstrap Results: 
+  First Bootstrap: 
+    Fraction of order statistics: None
+    AMSE values: None
+    H Min: 0.9059
+    Maximum index: None
+  Second Bootstrap: 
+    Fraction of order statistics: None
+    AMSE values: None
+    H Min: 0.9090
+    Maximum index: None
 ```
 
 ## Built-in Datasets

docs/api.rst

@@ -8,5 +8,6 @@ This section provides detailed API documentation for the tailestim package.
 
    base
    estimators/index
+   result
    data
 

docs/result.rst

@@ -0,0 +1,7 @@
+Result Class
+==========
+
+.. automodule:: tailestim.estimators.result
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/usage.rst

@@ -34,10 +34,10 @@ Using Built-in Datasets
 
     # Get the estimated parameters
     result = estimator.get_parameters()
-    gamma = result['gamma']
+    gamma = result.gamma
 
     # Print full results
-    print(estimator)
+    print(result)
 
 Using degree sequence from networkx graphs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -57,10 +57,10 @@ Using degree sequence from networkx graphs
 
     # Get the estimated parameters
     result = estimator.get_parameters()
-    gamma = result['gamma']
+    gamma = result.gamma
 
     # Print full results
-    print(estimator)
+    print(result)
 
 Available Estimators
 ------------------
@@ -84,7 +84,7 @@ The package provides several estimators for tail estimation. For details on each
 Results
 -------
 
-The full result can be obtained by ``estimator.get_parameters()``, which returns a dictionary. This includes:
+The full result can be obtained by ``result = estimator.get_parameters()``. You can either print the result, or access individual attributes (e.g., `result.gamma`). The output will include:
 
 - ``gamma``: Power law exponent (γ = 1 + 1/ξ)
 - ``xi_star``: Tail index (ξ)
@@ -96,24 +96,31 @@ The full result can be obtained by ``estimator.get_parameters()``, which returns
 Example Output
 ------------
 
-When you ``print(estimator)`` after fitting, you will get the following output:
+When you ``print(result)`` after fitting, you will get the following output:
 
 .. code-block:: text
 
-    ==================================================
-    Tail Estimation Results (HillEstimator)
-    ==================================================
+   --------------------------------------------------
+   Result
+   --------------------------------------------------
+   Order statistics: Array of shape (200,) [1.0000, 1.0000, 1.0000, ...]
+   Tail index estimates: Array of shape (200,) [1614487461647431761920.0000, 1249994621547387551744.0000, 967791073562264862720.0000, ...]
+   Optimal order statistic (k*): 25153
+   Tail index (ξ): 0.5942
+   Power law exponent (γ): 2.6828
+   Bootstrap Results: 
+   First Bootstrap: 
+      Fraction of order statistics: None
+      AMSE values: None
+      H Min: 0.9059
+      Maximum index: None
+   Second Bootstrap: 
+      Fraction of order statistics: None
+      AMSE values: None
+      H Min: 0.9090
+      Maximum index: None
 
-    Parameters:
-    --------------------
-    Optimal order statistic (k*): 26708
-    Tail index (ξ): 0.3974
-    Gamma (powerlaw exponent) (γ): 3.5167
 
-    Bootstrap Results:
-    --------------------
-    First bootstrap minimum AMSE fraction: 0.2744
-    Second bootstrap minimum AMSE fraction: 0.2745
 
 Built-in Datasets and Custom Data
 -------------------------------

examples/example.py

@@ -16,7 +16,7 @@
 result = estimator.get_parameters()
 
 # Get the power law exponent
-gamma = result['gamma']
+gamma = result.gamma
 
 # Print full results
 print(result)

src/tailestim/estimators/base.py

@@ -1,7 +1,9 @@
 """Base class for tail index estimation."""
 import numpy as np
 from abc import ABC, abstractmethod
-from typing import Dict, Any, Tuple
+from typing import Dict, Any, Tuple, Union
+from numpy.random import BitGenerator, SeedSequence, RandomState, Generator
+from .result import TailEstimatorResult
 
 class BaseTailEstimator(ABC):
     """Abstract base class for tail index estimation.
@@ -15,12 +17,19 @@ class BaseTailEstimator(ABC):
     bootstrap : bool, default=True
         Whether to use double-bootstrap for optimal threshold selection.
         May not be applicable for all methods.
+    base_seed: None | SeedSequence | BitGenerator | Generator | RandomState, default=None
+        Base random seed for reproducibility of bootstrap. Only used for methods with bootstrap.
     **kwargs : dict
         Additional parameters specific to each estimation method.
     """
 
-    def __init__(self, bootstrap: bool = True, **kwargs):
+    def __init__(
+            self,
+            bootstrap: bool = True,
+            base_seed: Union[None, SeedSequence, BitGenerator, Generator, RandomState] = None,
+            **kwargs):
         self.bootstrap = bootstrap
+        self.base_seed = base_seed
         self.kwargs = kwargs
         self.results = None
 
@@ -52,52 +61,39 @@ def fit(self, data: np.ndarray) -> None:
         self.results = self._estimate(ordered_data)
 
     @abstractmethod
-    def get_parameters(self) -> Dict[str, Any]:
+    def get_parameters(self) -> TailEstimatorResult:
         """Get the estimated parameters.
         
         Returns
         -------
-        Dict[str, Any]
-            Dictionary containing the estimated parameters.
+        TailEstimatorResult
+            Object containing the estimated parameters.
             The structure depends on the specific estimation method.
         """
         if self.results is None:
             raise ValueError("Model not fitted yet. Call fit() first.")
-        return {}
+        return TailEstimatorResult()
 
     def __str__(self) -> str:
-        """Format estimation results as a string."""
-        if self.results is None:
-            return "Model not fitted yet. Call fit() first."
-        
-        params = self.get_parameters()
-        
-        # Create header
-        header = "=" * 50 + "\n"
-        header += f"Tail Estimation Results ({self.__class__.__name__})\n"
-        header += "=" * 50 + "\n\n"
+        """Format estimation object as a string."""
+        # Create a string with the estimator type and fitted status
+        estim_str = "-" * 50 + "\n"
+        estim_str += f"Estimator Type: {self.__class__.__name__}\n"
+        estim_str += "-" * 50 + "\n"
+        estim_str += f"Fitted: {'Yes' if self.results is not None else 'No'}\n"
 
-        # Format main parameters
-        main_params = "Parameters:\n"
-        main_params += "-" * 20 + "\n"
+        # Add the arguments provided
+        estim_str += "Arguments:\n"
+        estim_str += f"  bootstrap: {self.bootstrap}\n"
+        estim_str += f"  base_seed: {self.base_seed}\n"
 
-        # Add method-specific parameter formatting
-        params_str = self._format_params(params)
+        # Add any additional kwargs
+        if self.kwargs:
+            for key, value in self.kwargs.items():
+                estim_str += f"  {key}: {value}\n"
 
-        return header + main_params + params_str
-
-    @abstractmethod
-    def _format_params(self, params: Dict[str, Any]) -> str:
-        """Format method-specific parameters as a string.
+        # If the model is not fitted, return just the estim_str 
+        if self.results is None:
+            return estim_str + "Model not fitted yet. Call fit() first."
 
-        Parameters
-        ----------
-        params : Dict[str, Any]
-            Dictionary of parameters to format.
-            
-        Returns
-        -------
-        str
-            Formatted parameter string.
-        """
-        pass
+        return estim_str 

src/tailestim/estimators/hill.py

@@ -1,7 +1,9 @@
 """Hill estimator implementation for tail index estimation."""
 import numpy as np
-from typing import Dict, Any, Tuple
+from typing import Dict, Any, Tuple, Union
+from numpy.random import BitGenerator, SeedSequence, RandomState, Generator
 from .base import BaseTailEstimator
+from .result import TailEstimatorResult
 from .tail_methods import hill_estimator as hill_estimate
 
 class HillEstimator(BaseTailEstimator):
@@ -27,6 +29,8 @@ class HillEstimator(BaseTailEstimator):
         Flag controlling bootstrap verbosity.
     diagn_plots : bool, default=False
         Flag to switch on/off generation of AMSE diagnostic plots.
+    base_seed: None | SeedSequence | BitGenerator | Generator | RandomState, default=None
+        Base random seed for reproducibility of bootstrap.
     """
 
     def __init__(
@@ -37,9 +41,10 @@ def __init__(
         eps_stop: float = 0.99,
         verbose: bool = False,
         diagn_plots: bool = False,
+        base_seed: Union[None, SeedSequence, BitGenerator, Generator, RandomState] = None,
         **kwargs
     ):
-        super().__init__(bootstrap=bootstrap, **kwargs)
+        super().__init__(bootstrap=bootstrap, base_seed=base_seed, **kwargs)
         self.t_bootstrap = t_bootstrap
         self.r_bootstrap = r_bootstrap
         self.eps_stop = eps_stop
@@ -66,16 +71,17 @@ def _estimate(self, ordered_data: np.ndarray) -> Tuple:
             r_bootstrap=self.r_bootstrap,
             verbose=self.verbose,
             diagn_plots=self.diagn_plots,
-            eps_stop=self.eps_stop
+            eps_stop=self.eps_stop,
+            base_seed=self.base_seed
         )
 
-    def get_parameters(self) -> Dict[str, Any]:
+    def get_parameters(self) -> TailEstimatorResult:
         """Get the estimated parameters.
         
         Returns
         -------
-        Dict[str, Any]
-            Dictionary containing:
+        TailEstimatorResult
+            Object containing:
             - k_arr: Array of order statistics
             - xi_arr: Array of tail index estimates
             - k_star: Optimal order statistic (if bootstrap=True)
@@ -116,38 +122,4 @@ def get_parameters(self) -> Dict[str, Any]:
                 }
             })
 
-        return params
-
-    def _format_params(self, params: Dict[str, Any]) -> str:
-        """Format Hill estimator parameters as a string.
-        
-        Parameters
-        ----------
-        params : Dict[str, Any]
-            Dictionary of parameters to format.
-            
-        Returns
-        -------
-        str
-            Formatted parameter string.
-        """
-        output = ""
-        
-        if 'k_star' in params:
-            output += f"Optimal order statistic (k*): {params['k_star']:.0f}\n"
-            output += f"Tail index (ξ): {params['xi_star']:.4f}\n"
-            output += f"Gamma (powerlaw exponent) (γ): {params['gamma']:.4f}\n"
-            
-            if self.bootstrap:
-                output += "\nBootstrap Results:\n"
-                output += "-" * 20 + "\n"
-                bs1 = params['bootstrap_results']['first_bootstrap']
-                bs2 = params['bootstrap_results']['second_bootstrap']
-                output += f"First bootstrap minimum AMSE fraction: {bs1['k_min']:.4f}\n"
-                output += f"Second bootstrap minimum AMSE fraction: {bs2['k_min']:.4f}\n"
-        else:
-            output += "Note: No bootstrap results available\n"
-            output += f"Number of order statistics: {len(params['k_arr'])}\n"
-            output += f"Range of tail index estimates: [{min(params['xi_arr']):.4f}, {max(params['xi_arr']):.4f}]\n"
-        
-        return output
+        return TailEstimatorResult(params)