better docstrings

pyerrors/dirac.py

@@ -26,6 +26,11 @@ def epsilon_tensor(i, j, k):
     """Rank-3 epsilon tensor
 
     Based on https://codegolf.stackexchange.com/a/160375
+
+    Returns
+    -------
+    elem : int
+        Element (i,j,k) of the epsilon tensor of rank 3
     """
     test_set = set((i, j, k))
     if not (test_set <= set((1, 2, 3)) or test_set <= set((0, 1, 2))):
@@ -38,6 +43,12 @@ def epsilon_tensor_rank4(i, j, k, o):
     """Rank-4 epsilon tensor
 
     Extension of https://codegolf.stackexchange.com/a/160375
+
+
+    Returns
+    -------
+    elem : int
+        Element (i,j,k,o) of the epsilon tensor of rank 4
     """
     test_set = set((i, j, k, o))
     if not (test_set <= set((1, 2, 3, 4)) or test_set <= set((0, 1, 2, 3))):

pyerrors/fits.py

@@ -129,6 +129,11 @@ def func(a, x):
         If True, a quantile-quantile plot of the fit result is generated (default False).
     num_grad : bool
         Use numerical differentation instead of automatic differentiation to perform the error propagation (default False).
+
+    Returns
+    -------
+    output : Fit_result
+        Parameters and information on the fitted result.
     '''
     if priors is not None:
         return _prior_fit(x, y, func, priors, silent=silent, **kwargs)
@@ -180,7 +185,12 @@ def func(a, x):
 
     Notes
     -----
-    Based on the orthogonal distance regression module of scipy
+    Based on the orthogonal distance regression module of scipy.
+
+    Returns
+    -------
+    output : Fit_result
+        Parameters and information on the fitted result.
     '''
 
     output = Fit_result()
@@ -668,6 +678,11 @@ def fit_lin(x, y, **kwargs):
         a list of Obs, where the dvalues of the Obs are used as xerror for the fit.
     y : list
         List of Obs, the dvalues of the Obs are used as yerror for the fit.
+
+    Returns
+    -------
+    fit_parameters : list[Obs]
+        LIist of fitted observables.
     """
 
     def f(a, x):
@@ -687,6 +702,10 @@ def f(a, x):
 def qqplot(x, o_y, func, p):
     """Generates a quantile-quantile plot of the fit result which can be used to
        check if the residuals of the fit are gaussian distributed.
+
+    Returns
+    -------
+    None
     """
 
     residuals = []
@@ -711,7 +730,12 @@ def qqplot(x, o_y, func, p):
 
 
 def residual_plot(x, y, func, fit_res):
-    """ Generates a plot which compares the fit to the data and displays the corresponding residuals"""
+    """Generates a plot which compares the fit to the data and displays the corresponding residuals
+
+    Returns
+    -------
+    None
+    """
     sorted_x = sorted(x)
     xstart = sorted_x[0] - 0.5 * (sorted_x[1] - sorted_x[0])
     xstop = sorted_x[-1] + 0.5 * (sorted_x[-1] - sorted_x[-2])
@@ -741,7 +765,13 @@ def residual_plot(x, y, func, fit_res):
 
 
 def error_band(x, func, beta):
-    """Returns the error band for an array of sample values x, for given fit function func with optimized parameters beta."""
+    """Calculate the error band for an array of sample values x, for given fit function func with optimized parameters beta.
+
+    Returns
+    -------
+    err : np.array(Obs)
+        Error band for an array of sample values x
+    """
     cov = covariance(beta)
     if np.any(np.abs(cov - cov.T) > 1000 * np.finfo(np.float64).eps):
         warnings.warn("Covariance matrix is not symmetric within floating point precision", RuntimeWarning)
@@ -765,6 +795,10 @@ def ks_test(objects=None):
     ----------
     objects : list
         List of fit results to include in the analysis (optional).
+
+    Returns
+    -------
+    None
     """
 
     if objects is None:

pyerrors/input/bdio.py

@@ -18,6 +18,11 @@ def read_ADerrors(file_path, bdio_path='./libbdio.so', **kwargs):
     ----------
     file_path -- path to the bdio file
     bdio_path -- path to the shared bdio library libbdio.so (default ./libbdio.so)
+
+    Returns
+    -------
+    data : List[Obs]
+        Extracted data
     """
     bdio = ctypes.cdll.LoadLibrary(bdio_path)
 
@@ -169,6 +174,11 @@ def write_ADerrors(obs_list, file_path, bdio_path='./libbdio.so', **kwargs):
     ----------
     file_path -- path to the bdio file
     bdio_path -- path to the shared bdio library libbdio.so (default ./libbdio.so)
+
+    Returns
+    -------
+    success : int
+        returns 0 is successful
     """
 
     for obs in obs_list:
@@ -314,6 +324,11 @@ def read_mesons(file_path, bdio_path='./libbdio.so', **kwargs):
         Fixed step size between two measurements (default 1)
     alternative_ensemble_name : str
         Manually overwrite ensemble name
+
+    Returns
+    -------
+    data : dict
+        Extracted meson data
     """
 
     start = kwargs.get('start', 1)

pyerrors/input/dobs.py

@@ -106,6 +106,11 @@ def create_pobs_string(obsl, name, spec='', origin='', symbol=[], enstag=None):
         A list of symbols that describe the observables to be written. May be empty.
     enstag : str
         Enstag that is written to pobs. If None, the ensemble name is used.
+
+    Returns
+    -------
+    xml_str : str
+        XML formatted string of the input data
     """
 
     od = {}
@@ -196,6 +201,10 @@ def write_pobs(obsl, fname, name, spec='', origin='', symbol=[], enstag=None, gz
         Enstag that is written to pobs. If None, the ensemble name is used.
     gz : bool
         If True, the output is a gzipped xml. If False, the output is an xml file.
+
+    Returns
+    -------
+    None
     """
     pobsstring = create_pobs_string(obsl, name, spec, origin, symbol, enstag)
 
@@ -305,6 +314,14 @@ def read_pobs(fname, full_output=False, gz=True, separator_insertion=None):
         by "|%s" % (separator_insertion) when constructing the names of the replica.
         int: Insert the separator "|" at the position given by separator_insertion.
         None (default): Replica names remain unchanged.
+
+    Returns
+    -------
+    res : list[Obs]
+        Imported data
+    or
+    res : dict
+        Imported data and meta-data
     """
 
     if not fname.endswith('.xml') and not fname.endswith('.gz'):
@@ -402,6 +419,14 @@ def import_dobs_string(content, noempty=False, full_output=False, separator_inse
         True (default): separator "|" is inserted after len(ensname), assuming that the
         ensemble name is a prefix to the replica name.
         None or False: No separator is inserted.
+
+    Returns
+    -------
+    res : list[Obs]
+        Imported data
+    or
+    res : dict
+        Imported data and meta-data
     """
 
     root = et.fromstring(content)
@@ -567,6 +592,14 @@ def read_dobs(fname, noempty=False, full_output=False, gz=True, separator_insert
         True (default): separator "|" is inserted after len(ensname), assuming that the
         ensemble name is a prefix to the replica name.
         None or False: No separator is inserted.
+
+    Returns
+    -------
+    res : list[Obs]
+        Imported data
+    or
+    res : dict
+        Imported data and meta-data
     """
 
     if not fname.endswith('.xml') and not fname.endswith('.gz'):
@@ -669,6 +702,11 @@ def create_dobs_string(obsl, name, spec='dobs v1.0', origin='', symbol=[], who=N
     enstags : dict
         Provide alternative enstag for ensembles in the form enstags = {ename: enstag}
         Otherwise, the ensemble name is used.
+
+    Returns
+    -------
+    xml_str : str
+        XML string generated from the data
     """
     if enstags is None:
         enstags = {}
@@ -857,6 +895,10 @@ def write_dobs(obsl, fname, name, spec='dobs v1.0', origin='', symbol=[], who=No
         Otherwise, the ensemble name is used.
     gz : bool
         If True, the output is a gzipped XML. If False, the output is a XML file.
+
+    Returns
+    -------
+    None
     """
     if enstags is None:
         enstags = {}

pyerrors/input/hadrons.py

@@ -74,6 +74,11 @@ def read_meson_hd5(path, filestem, ens_id, meson='meson_0', idl=None, gammas=Non
         two-point function. The gammas argument dominateds over meson.
     idl : range
         If specified only configurations in the given range are read in.
+
+    Returns
+    -------
+    corr : Corr
+        Correlator of the source sink combination in question.
     '''
 
     files, idx = _get_files(path, filestem, idl)
@@ -129,6 +134,11 @@ def read_DistillationContraction_hd5(path, ens_id, diagrams=["direct"], idl=None
         List of strings of the diagrams to extract, e.g. ["direct", "box", "cross"].
     idl : range
         If specified only configurations in the given range are read in.
+
+    Returns
+    -------
+    result : dict
+        extracted DistillationContration data
     """
 
     res_dict = {}
@@ -258,6 +268,11 @@ def read_ExternalLeg_hd5(path, filestem, ens_id, idl=None):
         name of the ensemble, required for internal bookkeeping
     idl : range
         If specified only configurations in the given range are read in.
+
+    Returns
+    -------
+    result : Npr_matrix
+        read Cobs-matrix
     """
 
     files, idx = _get_files(path, filestem, idl)
@@ -298,6 +313,11 @@ def read_Bilinear_hd5(path, filestem, ens_id, idl=None):
         name of the ensemble, required for internal bookkeeping
     idl : range
         If specified only configurations in the given range are read in.
+
+    Returns
+    -------
+    result_dict: dict[Npr_matrix]
+        extracted Bilinears
     """
 
     files, idx = _get_files(path, filestem, idl)
@@ -354,6 +374,11 @@ def read_Fourquark_hd5(path, filestem, ens_id, idl=None, vertices=["VA", "AV"]):
         If specified only configurations in the given range are read in.
     vertices : list
         Vertex functions to be extracted.
+
+    Returns
+    -------
+    result_dict : dict
+        extracted fourquark matrizes
     """
 
     files, idx = _get_files(path, filestem, idl)