add docs

.pre-commit-config.yaml

@@ -39,7 +39,6 @@ repos:
     hooks:
       - id: pydocstyle
         files: ^src/
-        args: ["--add-ignore=D107,D105"]
         additional_dependencies:
           - toml
   - repo: https://github.com/pre-commit/pre-commit

src/pinefarm/external/nnlojet/nnpdf_interface.py

@@ -1,7 +1,11 @@
 """
-    Read up all important information form an NNPDF dataset
+Read up all important information form an NNPDF dataset.
 
-    The selector generation is very flaky and is (mostly) up to the user for now
+The selector generation is very flaky and is (mostly) up to the user for now.
+
+Some examples:
+
+```yaml
     - histogram with selectors
     histograms:
         name: test
@@ -10,6 +14,7 @@
         extra_selectors:
             - "reject abs_ylp min = 1.37 max = 1.52"
             - "reject abs_ylm min = 1.37 max = 1.52"
+```
 """
 
 from copy import deepcopy
@@ -26,7 +31,7 @@
 
 
 def _legacy_nnpdf_translation(df, proc_type):
-    """When reading variables with k1/k2/k3 tries to figure out to which variables it corresponds"""
+    """When reading variables with k1/k2/k3 tries to figure out to which variables it corresponds."""
     from validphys.filters import KIN_LABEL
 
     new_vars = list(KIN_LABEL[proc_type])
@@ -37,8 +42,11 @@ def _legacy_nnpdf_translation(df, proc_type):
 
 
 def _df_to_bins(dataframe):
-    """Convert a dataframe containing min/mid/max for some kin variable
-    into a list of bins as NNLOJET understands it"""
+    """NNPDF kin dataframe to list of bins.
+
+    Convert a dataframe containing min/mid/max for some kin variable
+    into a list of bins as NNLOJET understands it.
+    """
     # If the NNPDF dataset has been implemented recently
     # we will have min/max
     # otherwise we have only mid and have to trick this
@@ -59,7 +67,7 @@ def _df_to_bins(dataframe):
 
 
 def _1d_histogram(kin_df, hist_var):
-    """Prepare the histogram for a 1d distribution"""
+    """Prepare the histogram for a 1d distribution."""
     histo_bins = _df_to_bins(kin_df[hist_var])
 
     if hist_var == "pT2":
@@ -77,7 +85,7 @@ def _1d_histogram(kin_df, hist_var):
 
 
 def _nnlojet_observable(observable, process):
-    """Try to automatically understand the NNLOJET observables given the NNPDF process and obs"""
+    """Try to automatically understand the NNLOJET observables given the NNPDF process and obs."""
     if observable in ("eta", "y", "etay"):
         if process.upper().startswith("Z"):
             return "yz"
@@ -97,7 +105,7 @@ def _nnlojet_observable(observable, process):
 
 
 def _generate_metadata(arxiv, hepdata, nnpdf_name, output):
-    """Generate a minimal ``metadata.txt`` file"""
+    """Generate a minimal ``metadata.txt`` file."""
     empty_fields = [
         "description",
         "x1_label",
@@ -118,8 +126,7 @@ def _generate_metadata(arxiv, hepdata, nnpdf_name, output):
 
 
 def select_selectors(experiment, process):
-    """A selection of default selectors to be selected
-    depending on the selected experiment
+    """A selection of default selectors to be selected depending on the selected experiment.
 
     The experiment defines the cuts to be applied to each variable.
     The process defines the name of the variables in NNLOJET
@@ -178,7 +185,7 @@ def select_selectors(experiment, process):
 
 
 def _generate_nnlojet_pinecard(runname, process, energy, experiment, histograms):
-    """Generate a pinecard for NNLOJET runs from an NNPDF dataset"""
+    """Generate a pinecard for NNLOJET runs from an NNPDF dataset."""
     selectors = select_selectors(experiment, process)
     histograms = deepcopy(histograms)
 
@@ -219,7 +226,7 @@ def _generate_nnlojet_pinecard(runname, process, energy, experiment, histograms)
 
 
 def generate_pinecard_from_nnpdf(nnpdf_dataset, scale="mz", output_path="."):
-    """Generate a NNLOJET pinecard from an NNPDF dataset"""
+    """Generate a NNLOJET pinecard from an NNPDF dataset."""
     # Load the NNPDF dataset
     from validphys.api import API
 

src/pinefarm/external/nnlojet/runcardgen.py

@@ -1,6 +1,7 @@
-"""
-    Module for the autogeneration of NNLOJET runcards using as input
-    yaml files containing the NNPDF dataset information
+"""Autogeneration of NNLOJET runcards.
+
+Module for the autogeneration of NNLOJET runcards using as input
+yaml files containing the NNPDF dataset information.
 """
 
 import logging
@@ -29,13 +30,15 @@
 
 @dataclass
 class Histogram:
+    """Holds histogram information."""
+
     name: str
     observable: str
     bins: list
     extra_selectors: list = None
     pineappl: bool = True
 
-    def to_str(self):
+    def to_str(self):  # noqa: D102
         hstr = f"{INDT}{self.observable} > {self.name} {self.bins}"
         if self.pineappl:
             hstr += " grid=pine"
@@ -50,11 +53,13 @@ def to_str(self):
 
 @dataclass
 class Selector:
+    """Holds selector information."""
+
     observable: str
     min: float = None
     max: float = None
 
-    def to_str(self):
+    def to_str(self):  # noqa: D102
         ret = f"{INDT}select {self.observable} "
         if self.min is not None:
             ret += f" min = {self.min}"
@@ -65,7 +70,7 @@ def to_str(self):
 
 @dataclass
 class YamlLOJET:
-    """Definition of the yaml runcard for sending NNLOJET jobs"""
+    """Definition of the yaml runcard for sending NNLOJET jobs."""
 
     runname: str
     process: dict
@@ -84,10 +89,13 @@ def __post_init__(self):
 
     @cached_property
     def channel_names_list(self):
+        """List of channels."""
         return list(self.channels.keys())
 
     def active_channels(self, active_channels=None):
-        """Loop over all channels in the yamlcard and check whether
+        """Digest active channels.
+
+        Loop over all channels in the yamlcard and check whether
         it correspond to one of the channels in the list `active_channels`
         e.g., if active_channels = [RR, RV], all RRa_n, RRb_n, and RV_n will be accepted
         If active_channels is None, return the whole thing for [LO, R, V, RR, RV, VV]
@@ -123,17 +131,20 @@ def active_channels(self, active_channels=None):
         return ret
 
     def get_channel_list(self, channel):
+        """Generate list of channels."""
         return self.channels[channel]
 
     @property
     def process_name(self):
+        """Get process name."""
         return self.process["proc"]
 
     def selector_definitions(self):
+        """Get definition of selectors."""
         return "\n".join(i.to_str() for i in self.selectors)
 
     def histogram_definitions(self):
-        """Return a string with the definition of all the histograms
+        """Return a string with the definition of all the histograms.
 
         In general the histogram is defined in the yaml file as a dict with:
             - name
@@ -145,13 +156,15 @@ def histogram_definitions(self):
 
 
 def parse_input_yaml(yaml_path):
+    """Parse the yaml runcard into a YamlLOJET object."""
     if not yaml_path.exists():
         raise FileNotFoundError(f"Yaml file {yaml_path} not found")
     yaml_dict = safe_load(yaml_path.open("r"))
     return YamlLOJET(**yaml_dict)
 
 
 def _fill_process(process):
+    """Fill process options."""
     process_name = process["proc"]
     sqrts = process["sqrts"]
     """Fill process block given the metadata for the process"""
@@ -165,6 +178,7 @@ def _fill_process(process):
 
 
 def _fill_run(runname, pdf, mode_line, techcut=1e-7, multi_channel=3):
+    """Fil run options."""
     if multi_channel == 0:
         multi_channel = ".false."
     return f"""
@@ -181,6 +195,7 @@ def _fill_run(runname, pdf, mode_line, techcut=1e-7, multi_channel=3):
 
 
 def _fill_parameters(theory_parameters):
+    """Fill physical parameters."""
     parameters = {
         "MASS[Z]": 91.1876,
         "WIDTH[Z]": 2.4952,
@@ -201,6 +216,7 @@ def _fill_parameters(theory_parameters):
 
 
 def _fill_selectors(metadata):
+    """Fill selectors."""
     return f"""
 SELECTORS
 {metadata.selector_definitions()}
@@ -209,7 +225,7 @@ def _fill_selectors(metadata):
 
 
 def _fill_histograms(metadata, empty=True):
-    """Create the histograms from the declarative definition"""
+    """Create the histograms from the declarative definition."""
     if empty:
         histogram_content = ""
     else:
@@ -223,6 +239,7 @@ def _fill_histograms(metadata, empty=True):
 
 
 def _fill_scales(scales):
+    """Fill in scales."""
     mur = scales.get("mur", 91.2)
     muf = scales.get("muf", 91.2)
 
@@ -234,7 +251,7 @@ def _fill_scales(scales):
 
 
 def region_str_generator(channel_name):
-    """Given the name of the channel, set up the region"""
+    """Given the name of the channel, set up the region."""
     order = channel_name.split("_", 1)[0]
     if order.endswith("a"):
         return "region = a"
@@ -244,6 +261,7 @@ def region_str_generator(channel_name):
 
 
 def _fill_channels(channels, region_str=""):
+    """Fill channels."""
     return f"""
 CHANNELS {region_str}
   {channels}
@@ -260,10 +278,10 @@ def generate_runcard(
     iterations: int = 1,
     output=Path("."),
 ):
-    """Generate a NNLOJET runcard given the metadata of the run in the folder defined by che channel name
-    The output path of the runcard will be ./channel/runcard_name_{warmup/production}.run
-    """
+    """Generate a NNLOJET runcard given the metadata of the run in the folder defined by che channel name.
 
+    The output path of the runcard will be ./channel/runcard_name_{warmup/production}.run.
+    """
     channel_dir = output / channel
     channel_dir.mkdir(exist_ok=True)
 
@@ -308,7 +326,7 @@ def generate_runcard(
 def generate_nnlojet_runcard(
     yamlinfo, channels=("LO",), output=Path("."), warmup=False
 ):
-    """Generate a nnlojet runcard from a yaml pinecard"""
+    """Generate a nnlojet runcard from a yaml pinecard."""
     yaml_metadata = YamlLOJET(**yamlinfo)
 
     output.mkdir(exist_ok=True, parents=True)

src/pinefarm/external/nnlojet/runner.py

@@ -18,7 +18,7 @@ def __init__(self, pinecard, theorycard, *args, **kwargs):
         self._yaml_dict = safe_load(yaml_card.open("r"))
 
     def preparation(self):
-        """Run the preparation step for NNLOJET"""
+        """Run the preparation step for NNLOJET."""
         # Update the yaml card according to the theory
         params = self._yaml_dict["parameters"]
 
@@ -55,14 +55,17 @@ def preparation(self):
         return True
 
     def run(self):
-        """Run the corresponding NNLOJET runcard"""
+        """Run the corresponding NNLOJET runcard."""
         raise NotImplementedError("NNLOJET running not implemented outside of dry mode")
 
     def collect_versions(self) -> dict:
+        """NNLOJET version."""
         return {"nnlojet_version": "secret"}
 
     def generate_pineappl(self):
+        """Not implemented."""
         print("Not yet")
 
     def results(self):
+        """Not implemented."""
         print("Good luck")