docs: multiple minor docstring fixes (#274)

* harmonized use of np.ndarray in docstrings
* fixed type of LimitResults.observed_limit in docstring
* multiple minor docstring formatting fixes
* pre-commit updated

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/psf/black
-    rev: 21.7b0
+    rev: 21.8b0
     hooks:
     -   id: black
 -   repo: https://github.com/pre-commit/mirrors-mypy
@@ -22,7 +22,7 @@ repos:
     -   id: flake8
         additional_dependencies: [flake8-bugbear, flake8-import-order, flake8-print]
 -   repo: https://github.com/asottile/pyupgrade
-    rev: v2.23.3
+    rev: v2.25.0
     hooks:
     -   id: pyupgrade
         args: ["--py37-plus"]

src/cabinetry/contrib/histogram_creation.py

@@ -23,7 +23,7 @@ def from_uproot(
         ntuple_paths (List[pathlib.Path]): list of paths to ntuples
         pos_in_file (str): name of tree within ntuple
         variable (str): variable to bin histogram in
-        bins (numpy.ndarray): bin edges for histogram
+        bins (np.ndarray): bin edges for histogram
         weight (Optional[str], optional): event weight to extract, defaults to None (no
             weights applied)
         selection_filter (Optional[str], optional): filter to be applied on events,
@@ -85,9 +85,9 @@ def _bin_data(
     """Creates a histogram from unbinned data.
 
     Args:
-        observables (numpy.ndarray): values the histogram will be binned in
-        weights (numpy.ndarray): weights to apply for each histogram entry
-        bins (numpy.ndarray): bin edges for histogram
+        observables (np.ndarray): values the histogram will be binned in
+        weights (np.ndarray): weights to apply for each histogram entry
+        bins (np.ndarray): bin edges for histogram
 
     Returns:
         Tuple[np.ndarray, np.ndarray]:

src/cabinetry/fit/results_containers.py

@@ -7,8 +7,8 @@ class FitResults(NamedTuple):
     """Collects fit results in one object.
 
     Args:
-        bestfit (numpy.ndarray): best-fit results of parameters
-        uncertainty (numpy.ndarray): uncertainties of best-fit parameter results
+        bestfit (np.ndarray): best-fit results of parameters
+        uncertainty (np.ndarray): uncertainties of best-fit parameter results
         labels (List[str]): parameter labels
         corr_mat (np.ndarray): parameter correlation matrix
         best_twice_nll (float): -2 log(likelihood) at best-fit point
@@ -30,13 +30,13 @@ class RankingResults(NamedTuple):
     include the parameter of interest, since no impact for it is calculated.
 
     Args:
-        bestfit (numpy.ndarray): best-fit results of parameters
-        uncertainty (numpy.ndarray): uncertainties of best-fit parameter results
+        bestfit (np.ndarray): best-fit results of parameters
+        uncertainty (np.ndarray): uncertainties of best-fit parameter results
         labels (List[str]): parameter labels
-        prefit_up (numpy.ndarray): pre-fit impact in "up" direction
-        prefit_down (numpy.ndarray): pre-fit impact in "down" direction
-        postfit_up (numpy.ndarray): post-fit impact in "up" direction
-        postfit_down (numpy.ndarray): post-fit impact in "down" direction
+        prefit_up (np.ndarray): pre-fit impact in "up" direction
+        prefit_down (np.ndarray): pre-fit impact in "down" direction
+        postfit_up (np.ndarray): post-fit impact in "up" direction
+        postfit_down (np.ndarray): post-fit impact in "down" direction
     """
 
     bestfit: np.ndarray
@@ -70,7 +70,7 @@ class LimitResults(NamedTuple):
     """Collects parameter upper limit results in one object.
 
     Args:
-        observed_limit (np.ndarray): observed limit
+        observed_limit (float): observed limit
         expected_limit (np.ndarray): expected limit, including 1 and 2 sigma bands
         observed_CLs (np.ndarray): observed CLs values
         expected_CLs (np.ndarray): expected CLs values, including 1 and 2 sigma bands

src/cabinetry/histo.py

@@ -128,7 +128,7 @@ def yields(self) -> np.ndarray:
         """Returns the yields per histogram bin.
 
         Returns:
-            numpy.ndarray: yields per bin
+            np.ndarray: yields per bin
         """
         return self.values()
 
@@ -146,7 +146,7 @@ def stdev(self) -> np.ndarray:
         """Returns the stat. uncertainty per histogram bin.
 
         Returns:
-            numpy.ndarray: stat. uncertainty per bin
+            np.ndarray: stat. uncertainty per bin
         """
         return np.sqrt(self.variances())  # type: ignore
 
@@ -155,7 +155,7 @@ def stdev(self, value: np.ndarray) -> None:
         """Updates the variance (by specifying the standard deviation).
 
         Args:
-            value (numpy.ndarray): the standard deviation
+            value (np.ndarray): the standard deviation
         """
         self.view().variance = value ** 2  # type: ignore
 
@@ -164,7 +164,7 @@ def bins(self) -> np.ndarray:
         """Returns the bin edges.
 
         Returns:
-            numpy.ndarray: bin edges
+            np.ndarray: bin edges
         """
         return self.axes[0].edges
 

src/cabinetry/model_utils.py

@@ -448,7 +448,6 @@ def _strip_auxdata(model: pyhf.pdf.Model, data: List[float]) -> List[float]:
     Returns:
         List[float]: observed data yields
     """
-
     n_bins_total = sum(model.config.channel_nbins.values())
     if len(data) != n_bins_total:
         # strip auxdata, only observed yields are needed

src/cabinetry/template_builder.py

@@ -249,7 +249,7 @@ def _binning(region: Dict[str, Any]) -> np.ndarray:
         NotImplementedError: when the binning is not explicitly defined
 
     Returns:
-        numpy.ndarray: bin boundaries to be used for histogram
+        np.ndarray: bin boundaries to be used for histogram
     """
     if not region.get("Binning", False):
         raise NotImplementedError("cannot determine binning")

src/cabinetry/visualize/plot_model.py

@@ -44,8 +44,8 @@ def data_mc(
             saving it, defaults to False (enable when producing many figures to avoid
             memory issues, prevents rendering in notebooks)
 
-        Returns:
-            matplotlib.figure.Figure: the data/MC figure
+    Returns:
+        matplotlib.figure.Figure: the data/MC figure
     """
     mc_histograms_yields = []
     mc_labels = []
@@ -251,7 +251,7 @@ def templates(
             memory issues, prevents rendering in notebooks)
 
     Returns:
-            matplotlib.figure.Figure: the template figure
+        matplotlib.figure.Figure: the template figure
     """
     bin_width = bin_edges[1:] - bin_edges[:-1]
     bin_centers = 0.5 * (bin_edges[:-1] + bin_edges[1:])

src/cabinetry/workspace.py

@@ -362,7 +362,7 @@ def measurements(self) -> List[Dict[str, Any]]:
         return measurements
 
     def observations(self) -> List[Dict[str, Any]]:
-        """Returns the observations (data yields) for the workspace.
+        """Returns the observations object (with data yields) for the workspace.
 
         Returns:
             List[Dict[str, Any]]: observations for ``pyhf`` workspace