add docstr and improve error msgs ; change example theory

validphys2/examples/data_theory_comparison_w_sv.yaml

@@ -5,7 +5,7 @@ meta:
 
 use_cuts: "internal"
 
-theoryid: 405 # define the central theory
+theoryid: 717 # define the central theory
 point_prescription: "3 point"
 theoryids:
   from_: scale_variation_theories

validphys2/src/validphys/dataplots.py

@@ -60,6 +60,7 @@ def plot_chi2dist(dataset, abs_chi2_data, chi2_stats, pdf):
 
 @figure
 def plot_chi2dist_sv(dataset, abs_chi2_data_thcovmat, pdf):
+    """Same as ``plot_chi2dist`` considering also the theory covmat in the calculation"""
     chi2_stats_thcovmat = chi2_stats(abs_chi2_data_thcovmat)
     return plot_chi2dist(dataset, abs_chi2_data_thcovmat, chi2_stats_thcovmat, pdf)
 
@@ -698,6 +699,7 @@ def plot_datasets_pdfs_chi2(data, each_dataset_chi2_pdfs, pdfs):
 
 @figure
 def plot_datasets_pdfs_chi2_sv(data, each_dataset_chi2_pdfs_sv, pdfs):
+    """Same as ``plot_datasets_pdfs_chi2_sv`` with the chi²s computed including scale variations"""
     return plot_datasets_pdfs_chi2(data, each_dataset_chi2_pdfs_sv, pdfs)
 
 

validphys2/src/validphys/results.py

@@ -150,6 +150,11 @@ def from_convolution(cls, pdf, dataset):
 
 
 class ThUncertaintiesResult(StatsResult):
+    """Class holding central theory predictions and the error bar corresponding to
+    the theory uncertainties considered.
+    The error members of this class correspond to central +- error_bar
+    """
+
     def __init__(self, central, std_err, label=None):
         # All should be (ndata, 1)
         self._central = central

validphys2/src/validphys/theorycovariance/construction.py

@@ -354,11 +354,41 @@ def compute_covs_pt_prescrip(
     seventheories=None,
 ):
     """Utility to compute the covariance matrix by prescription given the
-    shifts with respect to the central value for a given process as well as its name
-    If name2 (and deltas2) are not provided, it is understood that is the same process/dataset
+    shifts with respect to the central value for a pair of processes.
+
+    The processes are defined by the variables ``name1`` and ``name2`` with
+    ``deltas1`` and ``deltas2`` the associated shifts.
+
+    This utility also allows for the computation of the theory covmat for a single process
+    or dataset if ``names2=deltas2=None``.
+
+    Parameters
+    ---------
+        point_prescription: str
+            defines the point prescription to be utilized
+        l: int
+            Number of theory variations (counting the central theory)
+        name1: str
+            Process name of the first set of shifts
+        deltas1: list(np.ndarray)
+            list of shifts for each of the non-central theories
+        name2: str
+            Process name of the second set of shifts
+        deltas2: list(np.ndarray)
+            list of shifts for each of the non-central theories
+        fivetheories: str
+            5-point prescription variation
+        seventheories: str
+            7-point prescription variation
     """
-    if (name2 is None and deltas2 is not None) or (name2 is not None and deltas2 is None):
-        raise ValueError("WRONG")
+    if name2 is None and deltas2 is not None:
+        raise ValueError(
+            f"Error building theory covmat: predictions have been given with no associated process/dataset name"
+        )
+    elif deltas2 is None and name2 is not None:
+        raise ValueError(
+            f"Error building theory covmat: a process/dataset name has been given {name2} with no predictions"
+        )
 
     if name2 is None:
         name2 = name1