Commit 3fe40c94 authored by Niklas Selke's avatar Niklas Selke
Browse files

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.
parent 34eb056b
# 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:
......
......@@ -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
"""
```
......@@ -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 ---------------------------------------------------
......
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
......
......@@ -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
)
......
[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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment