diff --git a/.gitignore b/.gitignore
index 6cf629006c5908d7869a60a6bfe999a3c5024a10..785c09b535592bba74f802f6d97c3e97f0e557f8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,5 @@
# Ignore compiled files
*.pyc
+
+# Ignore package build directory
+/toarstats.egg-info/
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000000000000000000000000000000000000..9d7e2c35e16f860858b443411cd9a8832346992f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,8 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## v0.1.0 - 2021-09-05 - first experimental release of the package
+
+### general:
+* first working version is implemented
+* 50 statistics and metrics are included
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000000000000000000000000000000000000..acf77d3f6c1e4ce1682a1f38b40495c84a3cec3e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Forschungszentrum Jülich GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index d98689ad1b28cd466bfd3d99dbe7f324f1f268c5..4a78c3c6677e347d45192eb48868a0f9e84898ab 100644
--- a/README.md
+++ b/README.md
@@ -5,23 +5,94 @@ calculated on **hourly** data. The statistics in the `ozone_metrics.py`
file are specific to ozone data. The statistics in the `stats.py` file
can be calculated for other variables as well.
-To use this functionality import `toarstats` with:
+## Installation
+
+To install the package in a specific version and all dependencies run
+the following command from within the `dist` folder of this repository:
```
-from toarstats import toarstats
+python3 -m pip install toarstats-<version>-py3-none-any.whl
```
+It is advised to set up a virtual environment beforehand.
+
+## Usage
+
+### Import
+
+To use the package import `toarstats` with:
+```
+from toarstats import toarstats # or
+from toarstats import * # or
+import toarstats
+```
+
+### Interface
The `toarstats` 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.
+
+ This function is the public interface for the toarstats package and
+ acts as a wrapper around all statistics and metrics included in the
+ package.
+
+ :param sampling: temporal aggregation, one of ``daily``,
+ ``monthly``, ``seasonal``, ``vegseason``,
+ ``summer``, ``xsummer``, or ``annual``;
+ ``summer`` will pick the 6-months summer season in
+ 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``
+ :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
+ computed for the default seasons of the respective
+ metrics, normally, these are the four meteorological
+ seasons ``DJF``, ``MAM``, ``JJA`` and ``SON``;
+ 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
+ ``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
+ :param data_capture: a fractional value which will be used to
+ identify valid data periods;
+ the default is 0.75 for most statistics,
+ meaning that 75% of hourly values must be
+ present in a given interval in order to mark a
+ result as valid;
+ note that the ``value_count``, ``mean`` and
+ ``standard_deviation`` statistics do not use
+ this capture criterion, ``value_count`` counts
+ all values, ``mean`` and ``standard_deviation``
+ are calculated when there are at least 10 valid
+ hourly values in an interval;
+ the fraction may not always be applied to
+ original hourly values, but could for example
+ also be used to count the number of valid days
+ for a ``monthly``, ``seasonal``, or ``annual``
+ statistic
+ """
```
-Arguments:<br>
-sampling: temporal aggregation, e.g. 'daily', 'monthly', 'annual'<br>
-statistics: a list of statistics which should be calculated, names must
- be defined in `ozone_metrics.py` or `stats.py`<br>
-data: a data frame containing the hourly data<br>
-metadata: a named tuple containing the dataset metadata<br>
-seasons: a list of season names for seasonal statistics<br>
-crops: a list of crop types for 'vegseason' statistics<br>
-data_capture: a fractional value which will be used to identify valid
- data periods
diff --git a/dist/toarstats-0.1.0-py3-none-any.whl b/dist/toarstats-0.1.0-py3-none-any.whl
new file mode 100644
index 0000000000000000000000000000000000000000..8ff95d7e525f9c31fa18a901d1398af82076e93e
Binary files /dev/null and b/dist/toarstats-0.1.0-py3-none-any.whl differ
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000000000000000000000000000000000000..374b58cbf4636f1e28bacf987ac2fe89ed27ccba
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,6 @@
+[build-system]
+requires = [
+ "setuptools>=42",
+ "wheel"
+]
+build-backend = "setuptools.build_meta"
diff --git a/setup.cfg b/setup.cfg
new file mode 100644
index 0000000000000000000000000000000000000000..f70e7423720ab094881300cd24f46c932135f5f4
--- /dev/null
+++ b/setup.cfg
@@ -0,0 +1,23 @@
+[metadata]
+name = toarstats
+version = 0.1.0
+author = Niklas Selke
+author_email = n.selke@fz-juelich.de
+description = Collection of statistics for the TOAR community
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://gitlab.jsc.fz-juelich.de/esde/toar-public/toarstats
+classifiers =
+ Programming Language :: Python :: 3
+ Programming Language :: Python :: 3.6
+ Programming Language :: Python :: 3.7
+ Programming Language :: Python :: 3.8
+ Programming Language :: Python :: 3.9
+ License :: OSI Approved :: MIT License
+ Operating System :: OS Independent
+
+[options]
+packages = toarstats
+python_requires = >=3.6
+install_requires =
+ pandas>=1.0