Allow user to specify if distributional parameters are initialized

Author: StatMixedML

lightgbmlss/distributions/Beta.py

@@ -29,18 +29,25 @@ class Beta(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Cauchy.py

@@ -29,18 +29,25 @@ class Cauchy(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Expectile.py

@@ -25,11 +25,16 @@ class Expectile(DistributionClass):
         List of expectiles in increasing order.
     penalize_crossing: bool
         Whether to include a penalty term to discourage crossing of expectiles.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  expectiles: List = [0.1, 0.5, 0.9],
                  penalize_crossing: bool = False,
+                 initialize: bool = False,
                  ):
 
         # Input Checks
@@ -41,6 +46,8 @@ def __init__(self,
             raise ValueError("Expectiles must be between 0 and 1.")
         if not isinstance(penalize_crossing, bool):
             raise ValueError("penalize_crossing must be a boolean. Please choose from True or False.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Set the parameters specific to the distribution
         distribution = Expectile_Torch
@@ -61,7 +68,8 @@ def __init__(self,
                          distribution_arg_names=list(param_dict.keys()),
                          loss_fn="nll",
                          tau=torch.tensor(expectiles),
-                         penalize_crossing=penalize_crossing
+                         penalize_crossing=penalize_crossing,
+                         initialize=initialize,
                          )
 
 

lightgbmlss/distributions/Gamma.py

@@ -29,18 +29,25 @@ class Gamma(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Gaussian.py

@@ -29,18 +29,25 @@ class Gaussian(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Gumbel.py

@@ -29,18 +29,25 @@ class Gumbel(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Laplace.py

@@ -29,18 +29,25 @@ class Laplace(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/LogNormal.py

@@ -29,18 +29,25 @@ class LogNormal(DistributionClass):
         Loss function. Options are "nll" (negative log-likelihood) or "crps" (continuous ranked probability score).
         Note that if "crps" is used, the Hessian is set to 1, as the current CRPS version is not twice differentiable.
         Hence, using the CRPS disregards any variation in the curvature of the loss function.
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn: str = "exp",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll", "crps"]:
             raise ValueError("Invalid loss function. Please choose from 'nll' or 'crps'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Specify Response Functions
         response_functions = {"exp": exp_fn, "softplus": softplus_fn}
@@ -63,5 +70,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/Mixture.py

@@ -60,12 +60,18 @@ class Mixture(MixtureDistributionClass):
         approaches infty, the mixing probabilities become more uniform. For more information we refer to
 
             Jang, E., Gu, Shixiang and Poole, B. "Categorical Reparameterization with Gumbel-Softmax", ICLR, 2017.
+
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  component_distribution: torch.distributions.Distribution,
                  M: int = 2,
                  hessian_mode: str = "individual",
-                 tau: float = 1.0
+                 tau: float = 1.0,
+                 initialize: bool = False,
                  ):
 
         # Input Checks
@@ -86,6 +92,8 @@ def __init__(self,
             raise ValueError("tau must be a float.")
         if tau <= 0:
             raise ValueError("tau must be greater than 0.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         # Set the parameters specific to the distribution
         param_dict = component_distribution.param_dict
@@ -105,5 +113,6 @@ def __init__(self,
                          stabilization=component_distribution.stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=distribution_arg_names,
-                         loss_fn=component_distribution.loss_fn
+                         loss_fn=component_distribution.loss_fn,
+                         initialize=initialize,
                          )

lightgbmlss/distributions/NegativeBinomial.py

@@ -32,19 +32,26 @@ class NegativeBinomial(DistributionClass):
         "sigmoid" (sigmoid).
     loss_fn: str
         Loss function. Options are "nll" (negative log-likelihood).
+    initialize: bool
+        Whether to initialize the distributional parameters with unconditional start values. Initialization can help
+        to improve speed of convergence in some cases. However, it may also lead to early stopping or suboptimal
+        solutions if the unconditional start values are far from the optimal values.
     """
     def __init__(self,
                  stabilization: str = "None",
                  response_fn_total_count: str = "relu",
                  response_fn_probs: str = "sigmoid",
-                 loss_fn: str = "nll"
+                 loss_fn: str = "nll",
+                 initialize: bool = False,
                  ):
 
         # Input Checks
         if stabilization not in ["None", "MAD", "L2"]:
             raise ValueError("Invalid stabilization method. Please choose from 'None', 'MAD' or 'L2'.")
         if loss_fn not in ["nll"]:
             raise ValueError("Invalid loss function. Please select 'nll'.")
+        if not isinstance(initialize, bool):
+            raise ValueError("Invalid initialize. Please choose from True or False.")
 
         #  Specify Response Functions for total_count
         response_functions_total_count = {"exp": exp_fn, "softplus": softplus_fn, "relu": relu_fn}
@@ -75,5 +82,6 @@ def __init__(self,
                          stabilization=stabilization,
                          param_dict=param_dict,
                          distribution_arg_names=list(param_dict.keys()),
-                         loss_fn=loss_fn
+                         loss_fn=loss_fn,
+                         initialize=initialize,
                          )