Monthly & Normals docs

src/.vuepress/config.js

@@ -225,6 +225,14 @@ module.exports = {
               title: 'Daily Data',
               path: 'daily'
             },
+            {
+              title: 'Monthly Data',
+              path: 'monthly'
+            },
+            {
+              title: 'Climate Normals',
+              path: 'normals'
+            },
             {
               title: 'Contributing',
               path: 'contributing'
@@ -348,6 +356,62 @@ module.exports = {
                   title: 'meteostat.Daily.clear_cache',
                   path: 'api/daily/clear_cache'
                 },
+                {
+                  title: 'meteostat.Monthly',
+                  path: 'api/monthly/'
+                },
+                {
+                  title: 'meteostat.Monthly.normalize',
+                  path: 'api/monthly/normalize'
+                },
+                {
+                  title: 'meteostat.Monthly.aggregate',
+                  path: 'api/monthly/aggregate'
+                },
+                {
+                  title: 'meteostat.Monthly.interpolate',
+                  path: 'api/monthly/interpolate'
+                },
+                {
+                  title: 'meteostat.Monthly.convert',
+                  path: 'api/monthly/convert'
+                },
+                {
+                  title: 'meteostat.Monthly.coverage',
+                  path: 'api/monthly/coverage'
+                },
+                {
+                  title: 'meteostat.Monthly.fetch',
+                  path: 'api/monthly/fetch'
+                },
+                {
+                  title: 'meteostat.Monthly.count',
+                  path: 'api/monthly/count'
+                },
+                {
+                  title: 'meteostat.Monthly.clear_cache',
+                  path: 'api/monthly/clear_cache'
+                },
+                {
+                  title: 'meteostat.Normals',
+                  path: 'api/normals/'
+                },
+                {
+                  title: 'meteostat.Normals.convert',
+                  path: 'api/normals/convert'
+                },
+                {
+                  title: 'meteostat.Normals.coverage',
+                  path: 'api/normals/coverage'
+                },
+                {
+                  title: 'meteostat.Normals.fetch',
+                  path: 'api/normals/fetch'
+                },
+                {
+                  title: 'meteostat.Normals.count',
+                  path: 'api/normals/count'
+                },
                 {
                   title: 'meteostat.units',
                   path: 'api/units'

src/guide.md

@@ -11,7 +11,7 @@ Help Meteostat provide free weather and climate data by donating via [PayPal](ht
 Meteostat provides multiple interfaces for retrieving weather and climate data. Please choose from one of the following options:
 
 * [JSON API](/api/): Simple and fast access of Meteostat data in JSON format
-* [Python Library](/python/): Analyze historical weather data for thousands of weather stations
+* [Python Library](/python/): Analyze historical weather data for thousands of weather stations using Pandas
 * [Bulk Data](/bulk/): Download full data dumps of individual weather stations
 
 ## About Meteostat

src/python/README.md

@@ -1,6 +1,6 @@
 # Python Library
 
-The Meteostat Python library provides a simple programming interface for accessing open weather and climate data. The historical observations and statistics are obtained from Meteostat's [bulk data interface](/bulk/) and consist of data provided by different public interfaces, most of which are governmental. Among the [data sources](/docs/sources.html) are national weather services like the National Oceanic and Atmospheric Administration (NOAA) and Germany's national meteorological service (DWD).
+The Meteostat Python library provides simple access to open weather and climate data using Pandas. Historical observations and statistics are obtained from Meteostat's [bulk data interface](/bulk/) and consist of data provided by different public interfaces, most of which are governmental. Among the [data sources](/docs/sources.html) are national weather services like the National Oceanic and Atmospheric Administration (NOAA) and Germany's national meteorological service (DWD).
 
 ::: tip Donation
 Help Meteostat provide free weather and climate data by donating via [PayPal](https://paypal.me/meteostat).

src/python/api/daily/README.md

@@ -4,7 +4,7 @@ title: meteostat.Daily | API | Python Library
 
 # meteostat.Daily
 
-Query daily weather data for one or multiple weather stations.
+Query daily weather data for one or multiple weather stations or a single geographical point.
 
 ## Parameters
 

src/python/api/daily/coverage.md

@@ -8,7 +8,7 @@ The `coverage` method provides information about the completeness of data. It ca
 
 ## Parameters
 
-You can specify an optional `parameter` to look for. This can be any [response parameter](/python/daily.html#response-parameters) of the `Daily` class (e.g. `tmax` for the maximum temperature).
+You can specify an optional `parameter` to look for. This can be any [response parameter](/python/daily.html#data-structure) of the `Daily` class (e.g. `tmax` for the maximum temperature).
 
 | **Parameter** | **Description**                                      | **Type** | **Default** |
 |:--------------|:-----------------------------------------------------|:---------|:------------|

src/python/api/hourly/README.md

@@ -4,7 +4,7 @@ title: meteostat.Hourly | API | Python Library
 
 # meteostat.Hourly
 
-Query hourly weather data for one or multiple weather stations.
+Query hourly weather data for one or multiple weather stations or a single geographical point.
 
 ## Parameters
 

src/python/api/hourly/coverage.md

@@ -8,7 +8,7 @@ The `coverage` method provides information about the completeness of data. It ca
 
 ## Parameters
 
-You can specify an optional `parameter` to look for. This can be any [response parameter](/python/hourly.html#response-parameters) of the `Hourly` class (e.g. `temp` for the temperature).
+You can specify an optional `parameter` to look for. This can be any [response parameter](/python/hourly.html#data-structure) of the `Hourly` class (e.g. `temp` for the temperature).
 
 | **Parameter** | **Description**                                      | **Type** | **Default** |
 |:--------------|:-----------------------------------------------------|:---------|:------------|

src/python/api/monthly/README.md

@@ -0,0 +1,51 @@
+---
+title: meteostat.Monthly | API | Python Library
+---
+
+# meteostat.Monthly
+
+Query monthly weather data for one or multiple weather stations or a single geographical point.
+
+## Parameters
+
+The `loc` parameter is required. You can pass a [meteostat.Point](/python/api/point), a `DataFrame` returned by the [meteostat.Stations.fetch](/python/api/stations/fetch) method or provide one (String) or multiple Meteostat weather station identifiers (Tuple or List).
+
+| **Parameter** | **Description**                  | **Type**                                                     | **Default** |
+|:--------------|:---------------------------------|:-------------------------------------------------------------|:------------|
+| loc           | Weather station(s) or Point      | DataFrame, [Point](/python/api/point), String, Tuple or List | undefined   |
+| start         | Start date of the desired period | Datetime                                                     | None        |
+| end           | End date of the desired period   | Datetime                                                     | None        |
+| model         | Include model data               | Boolean                                                      | True        |
+
+## Attributes
+
+Attributes allow the configuration of general settings and behaviour.
+
+| **Parameter** | **Description**                                    | **Type** | **Default**        |
+|:--------------|:---------------------------------------------------|:---------|:-------------------|
+| cache_dir     | The path of the cache directory                    | String   | ~/.meteostat/cache |
+| cache_subdir  | The subdirectory of the cache                      | String   | monthly            |
+| max_age       | Maximum age of a cached file in seconds            | Integer  | 86400              |
+| max_threads   | Maximum number of threads used for data processing | Integer  | 1                  |
+
+You can disable caching completely by setting `max_age` to `0`.
+
+When changing attributes, make sure to do so before creating a class instance:
+
+```python{3}
+from meteostat import Monthly
+
+Monthly.cache_dir = '/my/path/goes/here'
+
+data = Monthly('10637')
+```
+
+## Methods
+
+* [meteostat.Monthly.normalize](normalize)
+* [meteostat.Monthly.aggregate](aggregate)
+* [meteostat.Monthly.interpolate](interpolate)
+* [meteostat.Monthly.convert](convert)
+* [meteostat.Monthly.coverage](coverage)
+* [meteostat.Monthly.fetch](fetch)
+* [meteostat.Monthly.count](count)

src/python/api/monthly/aggregate.md

@@ -0,0 +1,54 @@
+---
+title: meteostat.Monthly.aggregate | API | Python Library
+---
+
+# meteostat.Monthly.aggregate
+
+Aggregation is an important tool in data analysis. Meteostat allows both time-wise and spatial aggregation.
+
+## Parameters
+
+The `freq` parameter specifies the time series frequency. For full specification of available frequencies, please see [here](https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#offset-aliases). If you want to aggregate across all weather stations, just set the `spatial` parameter to `true`.
+
+| **Parameter** | **Description**                            | **Type** | **Default** |
+|:--------------|:-------------------------------------------|:---------|:------------|
+| freq          | Group by the specified frequency           | String   | '1M'        |
+| spatial       | Calculate averages across weather stations | Boolean  | False       |
+
+## Returns
+
+`Monthly` class instance
+
+### Aggregate Functions
+
+Meteostat uses the following aggregate functions:
+
+* `tavg` => `mean`
+* `tmin` => `min`
+* `tmax` => `max`
+* `prcp` => `sum`
+* `snow` => `mean`
+* `wdir` => `mean`
+* `wspd` => `mean`
+* `wpgt` => `max`
+* `pres` => `mean`
+* `tsun` => `sum`
+
+## Example
+
+Get annual data for Frankfurt Airport from 2000 to 2018.
+
+```python{9}
+from datetime import datetime
+from meteostat import Monthly
+
+start = datetime(2000, 1, 1)
+end = datetime(2018, 12, 31)
+
+data = Monthly('10637', start, end)
+data = data.normalize()
+data = data.aggregate('1Y')
+data = data.fetch()
+
+print(data)
+```

src/python/api/monthly/clear_cache.md

@@ -0,0 +1,31 @@
+---
+title: meteostat.Monthly.clear_cache | API | Python Library
+---
+
+# meteostat.Monthly.clear_cache
+
+This method cleans up the local `Monthly` cache by removing files which are older than `meteostat.Monthly.max_age`. The method is automatically called when initializing a new instance of the class.
+
+**Important:** This method does only affect files cached in the context of the `Monthly` class.
+
+## Parameters
+
+If you want to overwrite the default maximum age, just pass any number of seconds using the `max_age` parameter.
+
+| **Parameter** | **Description**                  | **Type** | **Default**               |
+|:--------------|:---------------------------------|:---------|:--------------------------|
+| max_age       | Maximum age of a file in seconds | Integer  | meteostat.Monthly.max_age |
+
+## Returns
+
+`None`
+
+## Example
+
+Remove stale files from the local `Monthly` cache.
+
+```python{3}
+from meteostat import Monthly
+
+Monthly.clear_cache()
+```

src/python/api/monthly/convert.md

@@ -0,0 +1,33 @@
+---
+title: meteostat.Monthly.convert | API | Python Library
+---
+
+# meteostat.Monthly.convert
+
+Convert specific attributes to a different unit.
+
+## Parameters
+
+The `units` parameter takes a dictionary which specifies column-unit pairs.
+
+| **Parameter** | **Description**                                    | **Type**   | **Default** |
+|:--------------|:---------------------------------------------------|:-----------|:------------|
+| units         | Dictionary which maps attributes to a certain unit | Dictionary | undefined   |
+
+## Returns
+
+`Monthly` class instance
+
+## Example
+
+Get monthly weather data for Atlanta International Airport and convert to imperial units.
+
+```python{4}
+from meteostat import Monthly, units
+
+data = Monthly('72219')
+data = data.convert(units.imperial)
+data = data.fetch()
+
+print(data)
+```

src/python/api/monthly/count.md

@@ -0,0 +1,28 @@
+---
+title: meteostat.Monthly.count | API | Python Library
+---
+
+# meteostat.Monthly.count
+
+The `count()` method returns the total number of records in the query result as an integer.
+
+## Parameters
+
+This method does not take any parameters.
+
+## Returns
+
+Integer
+
+## Example
+
+Get the total number of records ever recorded at Atlanta International Airport.
+
+```python{4}
+from meteostat import Monthly
+
+data = Monthly('72219')
+count = data.count()
+
+print(count)
+```

src/python/api/monthly/coverage.md

@@ -0,0 +1,36 @@
+---
+title: meteostat.Monthly.coverage | API | Python Library
+---
+
+# meteostat.Monthly.coverage
+
+The `coverage` method provides information about the completeness of data. It can be used to determine the coverage of records or individual parameters.
+
+## Parameters
+
+You can specify an optional `parameter` to look for. This can be any [response parameter](/python/monthly.html#data-structure) of the `Monthly` class (e.g. `tmax` for the maximum temperature).
+
+| **Parameter** | **Description**                                      | **Type** | **Default** |
+|:--------------|:-----------------------------------------------------|:---------|:------------|
+| parameter     | Check coverage of a certain meteorological parameter | String   | None        |
+
+## Returns
+
+Integer between 0 (no records) and 1 (all records)
+
+## Example
+
+Check completeness of records for Sydney Airport in 2019.
+
+```python{8}
+from datetime import datetime
+from meteostat import Monthly
+
+start = datetime(2019, 1, 1)
+end = datetime(2019, 12, 31)
+
+data = Monthly('94767', start, end)
+coverage = data.coverage()
+
+print(coverage)
+```

src/python/api/monthly/fetch.md

@@ -0,0 +1,28 @@
+---
+title: meteostat.Monthly.fetch | API | Python Library
+---
+
+# meteostat.Monthly.fetch
+
+You can access the resulting `DataFrame` of your query using the `fetch()` method.
+
+## Parameters
+
+This method does not take any parameters.
+
+## Returns
+
+Pandas `DataFrame`
+
+## Example
+
+Get all data ever recorded at Atlanta International Airport.
+
+```python{4}
+from meteostat import Monthly
+
+data = Monthly('72219')
+data = data.fetch()
+
+print(data)
+```