more documentation

appletree/parameter.py

@@ -82,6 +82,8 @@ def sample_prior(self):
                 val = np.random.normal(**kwargs)
                 self._parameter_dict[par_name] = np.clip(val, *setting["allowed_range"])
             elif prior_type == "twohalfnorm":
+                # We need to convert errors to sigmas
+                # See the docstring of errors_to_two_half_norm_sigmas for details
                 sigmas = errors_to_two_half_norm_sigmas([args["sigma_pos"], args["sigma_neg"]])
                 kwargs = {
                     "mu": args["mu"],
@@ -152,6 +154,8 @@ def log_prior(self):
                 std = args["std"]
                 log_prior += -((val - mean) ** 2) / 2 / std**2
             elif prior_type == "twohalfnorm":
+                # We need to convert errors to sigmas
+                # See the docstring of errors_to_two_half_norm_sigmas for details
                 sigmas = errors_to_two_half_norm_sigmas([args["sigma_pos"], args["sigma_neg"]])
                 mu = args["mu"]
                 log_prior += TwoHalfNorm.logpdf(

appletree/utils.py

@@ -583,7 +583,16 @@ def check_unused_configs():
 
 def errors_to_two_half_norm_sigmas(errors):
     """This function solves the sigmas for a two-half-norm distribution, such that the 16 and 84
-    percentile corresponds to the given errors."""
+    percentile corresponds to the given errors.
+
+    In the two-half-norm distribution, the positive and negative errors are assumed to be
+    the std of the glued normal distributions. While we interpret the 16 and 84 percentile as
+    the input errors, thus we need to solve the sigmas for the two-half-norm distribution. The solution
+    is determined by the following conditions:
+    - The 16 percentile of the two-half-norm distribution should be the negative error.
+    - The 84 percentile of the two-half-norm distribution should be the positive error.
+    - The mode of the two-half-norm distribution should be 0.
+    """
 
     def _to_solve(x, errors, p):
         return [