added description, /close #275

mlair/helpers/statistics.py

@@ -155,20 +155,47 @@ def min_max_apply(data: Data, min: Data, max: Data) -> Data:
 
 
 def log(data: Data, dim: Union[str, int]) -> Tuple[Data, Dict[(str, Data)]]:
+    """
+    Apply logarithmic transformation (and standarization) to data. This method first uses the logarithm for
+    transformation and second applies the `standardise` method additionally. A logarithmic function numpy's log1p is
+    used (`res = log(1+x)`) instead of the pure logarithm to be applicable to values of 0 too.
+
+    :param data: transform this data
+    :param dim: name (xarray) or axis (pandas) of dimension which should be transformed
+    :return: transformed data, and option dictionary with keys method, mean, and std
+    """
     transformed_standardized, opts = standardise(np.log1p(data), dim)
     opts.update({"method": "log"})
     return transformed_standardized, opts
 
 
-def log_apply(data: Data, mean: Data, std: Data) -> Data:
-    return standardise_apply(np.log1p(data), mean, std)
-
-
 def log_inverse(data: Data, mean: Data, std: Data) -> Data:
+    """
+    Apply inverse log transformation (therefore exponential transformation). Because `log` is using `np.log1p` this
+    method is based on the equivalent method `np.exp1m`. Data are first rescaled using `standardise_inverse` and then
+    given to the exponential function.
+
+    :param data: apply inverse log transformation on this data
+    :param mean: mean of the standarization
+    :param std: std of the standarization
+    :return: inverted data
+    """
     data_rescaled = standardise_inverse(data, mean, std)
     return np.expm1(data_rescaled)
 
 
+def log_apply(data: Data, mean: Data, std: Data) -> Data:
+    """
+    Apply numpy's log1p on given data. Further information can be found in description of `log` method.
+
+    :param data: transform this data
+    :param mean: mean of the standarization
+    :param std: std of the standarization
+    :return: transformed data
+    """
+    return standardise_apply(np.log1p(data), mean, std)
+
+
 def mean_squared_error(a, b):
     """Calculate mean squared error."""
     return np.square(a - b).mean()