continued work on documentation

toargridding/grids.py

@@ -16,9 +16,13 @@ from toargridding.metadata import (
 from toargridding.variables import Variable, Coordinate
 
 GridType = Enum("GridType", ["regular"])
-
+"""list of available grids.
+"""
 
 class GridDefinition(ABC):
+    """factory and base class for definition of different grids
+
+    """
     cell_index_name = "cell_index"
 
     def __init__(self):
@@ -36,20 +40,33 @@ class GridDefinition(ABC):
     @property
     @abstractmethod
     def description(self):
+        """description of this grid
+        """
         pass
 
     @staticmethod
     def from_netcdf():
+        """loading of an arbitrary grid from a netCDF file
+
+        not yet implemented
+        """
         pass
 
     @abstractmethod
     def as_xarray(
         timeseries: dict[str, pd.DataFrame], metadata: pd.DataFrame
     ) -> dict[str, xr.Dataset]:
+        """conversion of panda Dataframes to an xarray dataset
+
+        This includes the required setup to store the results as netCDF file according to CF (https://cfconventions.org/cf-conventions/cf-conventions.html)
+        """
         pass
 
 
 class RegularGrid(GridDefinition):
+    """definition of a regular grid with longitude and latitude.
+    """
+
     Coord = namedtuple("Coord", ["lat", "lon"])
 
     def __init__(self, lat_resolution, lon_resolution):

toargridding/variables.py

@@ -5,9 +5,25 @@ import xarray as xr
 
 from toargridding.metadata import Variables, get_cf_metadata, Metadata
 
+from typing import Dict
 
 @dataclass
 class Variable:
+    """full variable including data and information according to CF 
+    
+    CF: https://cfconventions.org/cf-conventions/cf-conventions.html
+    
+    Parameters:
+    ----------
+    var: 
+        name of the TOAR variable
+    data:
+        array with data
+    attributes:
+        metadata according to CF
+    encoding:
+        encoding of data type
+    """
     var: Variables
     data: np.ndarray
     attributes: dict[str, str]
@@ -15,11 +31,15 @@ class Variable:
 
     @classmethod
     def from_data(cls, data, variable: Variables, metadata: Metadata | None, **kwargs):
+        """construction from analysis results
+        """
         cf_metadata = get_cf_metadata(variable, metadata=metadata)
         # print(variable.name, cf_metadata)
         return cls(variable, data, **cf_metadata, **kwargs)
 
-    def as_data_array(self, dims):
+    def as_data_array(self, dims) -> xr.DataArray:
+        """conversion to DataArray
+        """
         da = xr.DataArray(
             self.data,
             name=self.name,
@@ -31,29 +51,43 @@ class Variable:
 
     @property
     def name(self):
+        """shortcut to variable name
+        """
         return self.var.name
 
     @property
     def size(self):
+        """shortcut to length of data array
+        """
         return self.data.size
 
     @property
     def min(self):
+        """shortcut to minimum of data array
+        """
         return self.data.min()
 
     @property
     def max(self):
+        """shortcut to maximum of data array
+        """
         return self.data.max()
 
 
 @dataclass
 class Coordinate(Variable):
+    """coordinate axis
+    """
+
     step: float | str
 
     @classmethod
     def from_resolution(
         cls, variable: Variables, resolution: float, min: float, max: float
     ):
+        """construction from a data range and resolution
+        """
+
         span = max - min
         n = int(span / resolution)  # raise error if invalid inputs ?
         data = np.linspace(min, max, n + 1)
@@ -61,8 +95,12 @@ class Coordinate(Variable):
         return cls.from_data(data, variable, None, step=resolution)
 
     def as_data_array(self):
+        """conversion to data array
+        """
         return super().as_data_array(dims=self.name)
 
 
-def get_encoding(variables: list[Variable]):
+def get_encoding(variables: list[Variable]) -> Dict[str,Dict]:
+    """get dictionary encoding with encoding
+    """
     return {variable.name: variable.encoding for variable in variables}