Fixed the 'README.md'. Only the public interface is now documented in the...

Fixed the 'README.md'. Only the public interface is now documented in the 'docs' folder. Updated everything to the v0.2.0 release.

CHANGELOG.md

 # Changelog
 All notable changes to this project will be documented in this file.
 
+## v0.2.0 - 2022-01-03 - second experimental release of the package
+
+### general:
+* new interface: calculate_statistics
+* removed old interface
+
+### new features:
+* user inputs will be checked
+
+### technical:
+* constants and defaults are in their own separate modules
+
 ## v0.1.0 - 2021-09-05 - first experimental release of the package
 
 ### general:

README.md

@@ -18,24 +18,27 @@ It is advised to set up a virtual environment beforehand.
 
 ### Import
 
-To use the package import `toarstats` with:
+To use the package import `calculate_statistics` with:
 ```
-from toarstats import toarstats # or
+from toarstats import calculate_statistics # or
 from toarstats import * # or
 import toarstats
 ```
 
 ### Interface
 
-The `toarstats` interface is defined like this:
+The `calculate_statistics` interface is defined like this:
 ```
-toarstats(sampling, statistics, data, metadata, seasons=None,
-          crops=None, data_capture=None)
-    """Calculate the given statistics with the given sampling.
+calculate_statistics(
+    sampling=None, statistics=None, data=None, metadata=None, seasons=None,
+    crops=None, data_capture=None, datetimes=None, values=None,
+    station_lat=None, station_lon=None, station_climatic_zone=None
+)
+    """Calculate the requested statistics.
 
-    This function is the public interface for the toarstats package and
-    acts as a wrapper around all statistics and metrics included in the
-    package.
+    This function is the public interface for the ``toarstats`` package.
+    It takes all the user inputs and returns the result of all requested
+    statistics and metrics.
 
     :param sampling: temporal aggregation, one of ``daily``,
                      ``monthly``, ``seasonal``, ``vegseason``,
@@ -44,20 +47,25 @@ toarstats(sampling, statistics, data, metadata, seasons=None,
                      the hemisphere where the station is located;
                      ``xsummer`` does the same for a 7-months summer
                      season;
-                     ``vegseason`` requires also the crops argument and
-                     will then determine the appropriate growing seasons
-                     based on the ``climatic_zone`` metadata and crop
-                     type
-    :param statistics: a list of statistics and metrics to call, these
-                       must be defined in ``stats.py`` or
-                       ``ozone_metrics.py``;
-                       a single string can also be given
-    :param data: a data frame with datetime values with hourly
-                 resolution and a column with parameter values on which
-                 to calculate the requested statistics and metrics
-    :param metadata: a named tuple with metadata information for
-                     ``station_lat``, ``station_lon``, and
-                     ``station_climatic_zone``
+                     ``vegseason`` requires also the ``crops`` argument
+                     and will then determine the appropriate growing
+                     seasons based on the ``climatic_zone`` metadata and
+                     crop type
+    :param statistics: a single statistic or metric or a list of
+                       statistics and metrics to call, these must be
+                       defined in ``stats.py`` or ``ozone_metrics.py``
+    :param data: data containing a list of date time values and
+                 associated parameter values on which to calculate the
+                 statistics;
+                 if not given, both ``datetimes`` and ``values`` must be
+                 given instead
+    :param metadata: metadata information about the station's latitude,
+                     longitude and climatic zone (keys: ``station_lat``,
+                     ``station_lon`` and ``station_climatic_zone``);
+                     if not given and any requested statistic or metric
+                     needs metadata information, ``station_lat``,
+                     ``station_lon`` and ``station_climatic_zone`` must
+                     be given instead
     :param seasons: a list of season names for seasonal statistics;
                     for a definition of seasons, see ``stats_utils.py``;
                     if ``None`` is passed, seasonal statistics will be
@@ -67,16 +75,16 @@ toarstats(sampling, statistics, data, metadata, seasons=None,
                     if sampling is set to ``summer`` or ``xsummer``, the
                     correct season will be determined based on the
                     ``station_lat`` metadata;
-                    if sampling is ``vegseason`` and the crops argument
-                    is given, the appropriate growing seasons will be
-                    selected based on the crop type and
+                    if sampling is ``vegseason`` and the ``crops``
+                    argument is given, the appropriate growing seasons
+                    will be selected based on the crop type and
                     ``climatic_zone`` metadata;
-                    the growing seasons for wheat and rice will also be
-                    selected if sampling is ``seasonal`` and the chosen
-                    metrics contains ``aot40`` or ``w126``
-    :param crops: a list of crop types for ``vegseason`` statistics;
-                  default is ``["wheat", "rice"]``;
-                  a single string can also be given
+                    the growing seasons for ``wheat`` and ``rice`` will
+                    also be selected if sampling is ``seasonal`` and the
+                    chosen metrics contain ``aot40`` or ``w126``
+    :param crops: a single crop type or a list of crop types for
+                  ``vegseason`` statistics;
+                  default is ``["wheat", "rice"]``
     :param data_capture: a fractional value which will be used to
                          identify valid data periods;
                          the default is 0.75 for most statistics,
@@ -94,5 +102,15 @@ toarstats(sampling, statistics, data, metadata, seasons=None,
                          also be used to count the number of valid days
                          for a ``monthly``, ``seasonal``, or ``annual``
                          statistic
+    :param datetimes: must be given with ``values`` if the ``data``
+                      argument is missing
+    :param values: must be given with ``datetimes`` if the ``data``
+                   argument is missing
+    :param station_lat: station's latitude, used if missing in the
+                        ``metadata`` argument
+    :param station_lon: station's longitude, used if missing in the
+                        ``metadata`` argument
+    :param station_climatic_zone: station's climatic zone, used if
+                                  missing in the ``metadata`` argument
     """
 ```

docs/conf.py

@@ -21,6 +21,9 @@ project = 'toarstats'
 copyright = '2021, Forschungszentrum Jülich GmbH'
 author = 'Niklas Selke'
 
+# The full version, including alpha/beta/rc tags
+release = '0.2.0'
+
 
 # -- General configuration ---------------------------------------------------
 

docs/index.rst

 Welcome to toarstats's documentation!
 =====================================
 
-.. automodule:: toarstats.stats_main
-   :members:
-
-.. automodule:: toarstats.stats
-   :members:
-
-.. automodule:: toarstats.ozone_metrics
-   :members:
-
-.. automodule:: toarstats.stats_utils
-   :members:
-
-.. automodule:: toarstats.solar_position
-   :members:
+.. autofunction:: toarstats.interface.calculate_statistics
 
 .. toctree::
    :maxdepth: 2

docs/make.bat

@@ -21,7 +21,7 @@ if errorlevel 9009 (
 	echo.may add the Sphinx directory to PATH.
 	echo.
 	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
+	echo.https://www.sphinx-doc.org/
 	exit /b 1
 )
 

requirements.txt

-numpy==1.21.2
-pandas==1.3.2
+numpy==1.22.0
+pandas==1.3.5

setup.cfg

 [metadata]
 name = toarstats
-version = 0.1.0
+version = 0.2.0
 author = Niklas Selke
 author_email = n.selke@fz-juelich.de
 description = Collection of statistics for the TOAR community
@@ -13,6 +13,7 @@ classifiers =
     Programming Language :: Python :: 3.7
     Programming Language :: Python :: 3.8
     Programming Language :: Python :: 3.9
+    Programming Language :: Python :: 3.10
     License :: OSI Approved :: MIT License
     Operating System :: OS Independent