Skip to content

Commit 5394cb1

Browse files
kandersolarAdamRJensen
kandersolar
and
AdamRJensen
authored
Create weather data/iotools page in User's Guide (#1754)
* add a bit of content * Apply suggestions from code review Co-authored-by: Adam R. Jensen <[email protected]> * revisions * further improvements * Apply suggestions from code review Co-authored-by: Adam R. Jensen <[email protected]> * make :py:mod:`pvlib.iotools` link to API reference * move mention of iotools paper * cleanup * whatsnew --------- Co-authored-by: Adam R. Jensen <[email protected]>
1 parent dd68286 commit 5394cb1

File tree

4 files changed

+167
-0
lines changed

4 files changed

+167
-0
lines changed

‎docs/sphinx/source/reference/iotools.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
2+
.. py:module:: pvlib.iotools
3+
14
.. currentmodule:: pvlib
25

36
.. _iotools:

‎docs/sphinx/source/user_guide/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ User Guide
1414
timetimezones
1515
clearsky
1616
bifacial
17+
weather_data
1718
comparison_pvlib_matlab
1819
variables_style_rules
1920
singlediode

‎docs/sphinx/source/user_guide/weather_data.rst

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. _weatherdata:
2+
3+
Weather data
4+
============
5+
6+
Simulating the performance of a PV system requires irradiance and meteorological data
7+
as the inputs to a PV system model. Weather datasets are available
8+
from many sources and in many formats. The :py:mod:`pvlib.iotools` module
9+
contains functions to easily retrieve and import such datasets in a standardized
10+
form that is convenient to use with the rest of pvlib.
11+
12+
The primary focus of :py:mod:`pvlib.iotools` is time series solar resource
13+
data like the irradiance datasets from PVGIS and the NSRDB, but it also provides
14+
functionality for other types of data useful for certain aspects of PV modeling.
15+
For example, precipitation data is available from :py:func:`~pvlib.iotools.get_acis_prism`
16+
for soiling modeling and horizon profiles can be retrieved from
17+
:py:func:`~pvlib.iotools.get_pvgis_horizon` for horizon shade modeling.
18+
19+
For a complete list of functions related to retrieving and importing weather
20+
data, see :ref:`iotools`, and for a detailed comparison of the weather datasets
21+
available through pvlib, see [1]_.
22+
23+
24+
Types of weather data sources
25+
-----------------------------
26+
27+
Weather data can be grouped into a few fundamental categories. Which
28+
type is most useful depends on the application. Here we provide a high-level
29+
overview of different types of weather data, and when you might want to use
30+
them.
31+
32+
1. **Ground station measurements**:
33+
From in-situ monitoring equipment. If properly maintained and
34+
quality-controlled, these are the highest quality
35+
source of weather information. However, the coverage depends on
36+
a weather station having been set up in advance for the location and
37+
times of interest. Some ground station networks like the BSRN and SURFRAD
38+
make their measurement data publicly available. An global overview of ground
39+
stations is available at https://SolarStations.org.
40+
41+
Data from public ground station measurement networks are useful if you
42+
want accurate, high-resolution data but have flexibility around the
43+
specific measurement location.
44+
45+
2. **Satellite data**:
46+
These sources process satellite imagery (typically from geostationary
47+
satellites) to identify and classify clouds, and combine this with solar
48+
irradiance models and aerosol data to produce irradiance estimates. The
49+
quality is generally much higher than NWP, but still not as good as a well-maintained
50+
weather station. They have high spatial and temporal resolution
51+
corresponding to the source satellite imagery, and are generally
52+
optimised to estimate solar irradiance for PV applications. Free sources
53+
such as PVGIS, NSRDB, and CAMS are available, and commerical sources such
54+
as SolarAnywhere, Solcast, and Solargis provide paid options though often
55+
have free trials.
56+
57+
Satellite data is useful when suitable ground measurements are
58+
not available for the location and/or times of interest.
59+
60+
3. **Numerical Weather Prediction (NWP)**:
61+
These are mathematical simulations of weather systems.
62+
The data quality is much lower than that of measurements and
63+
satellite data, owing in part to coarser spatial and temporal
64+
resolution, as well as many models not being optimised for solar
65+
irradiance for PV applications. On the plus side, these models typically
66+
have worldwide coverage, with some regional models (e.g. HRRR) sacrifice
67+
global coverage for somewhat higher spatial and temporal resolution.
68+
Various forecast (e.g. GFS, ECMWF, ICON) and reanalysis sources (ERA5,
69+
MERRA2) exist.
70+
71+
NWP datasets are primarily useful for parts of the world not covered
72+
by satellite-based datasets (e.g. polar regions) or if extremely long time
73+
ranges are needed.
74+
75+
76+
Usage
77+
-----
78+
79+
With some exceptions, the :py:mod:`pvlib.iotools` functions
80+
provide a uniform interface for accessing data across many formats.
81+
Specifically, :py:mod:`pvlib.iotools` functions usually return two objects:
82+
a :py:class:`pandas.DataFrame` of the actual dataset, plus a metadata
83+
dictionary. Most :py:mod:`pvlib.iotools` functions also have
84+
a ``map_variables`` parameter to automatically translate
85+
the column names used in the data file (which vary widely from dataset to dataset)
86+
into standard pvlib names (see :ref:`variables_style_rules`).
87+
88+
Typical usage looks something like this:
89+
90+
.. code-block:: python
91+
92+
# get_pvgis_tmy returns two additional values besides df and metadata
93+
df, _, _, metadata = pvlib.iotools.get_pvgis_tmy(latitude, longitude, map_variables=True)
94+
95+
This code will fetch a Typical Meteorological Year (TMY) dataset from PVGIS,
96+
returning a :py:class:`pandas.DataFrame` containing the hourly weather data
97+
and a python dict with information about the dataset.
98+
99+
Most :py:mod:`pvlib.iotools` functions work with time series datasets.
100+
In that case, the returned ``df`` DataFrame has a datetime index, localized
101+
to the appropriate time zone where possible. Make sure to understand each
102+
dataset's timestamping convention (e.g. center versus end of interval), as
103+
pvlib will use these timestamps for solar position calculations.
104+
105+
The content of the metadata dictionary varies for each function/dataset.
106+
107+
108+
Data retrieval
109+
**************
110+
111+
Several :py:mod:`pvlib.iotools` functions access the internet to fetch data from
112+
online web APIs. For example, :py:func:`~pvlib.iotools.get_pvgis_hourly`
113+
downloads data from PVGIS's webservers and returns it as a python variable.
114+
Functions that retrieve data from the internet are named ``get_``, followed
115+
by the name of the data source: :py:func:`~pvlib.iotools.get_bsrn`,
116+
:py:func:`~pvlib.iotools.get_psm3`, :py:func:`~pvlib.iotools.get_pvgis_tmy`,
117+
and so on.
118+
119+
For satellite/reanalysis datasets, the location is specified by latitude and
120+
longitude in decimal degrees:
121+
122+
.. code-block:: python
123+
124+
latitude, longitude = 33.75, -84.39 # Atlanta, Georgia, United States
125+
df, metadata = pvlib.iotools.get_psm3(latitude, longitude, map_variables=True, ...)
126+
127+
128+
For ground station networks, the location identifier is the station ID:
129+
130+
.. code-block:: python
131+
132+
df, metadata = pvlib.iotools.get_bsrn(station='cab', start='2020-01-01', end='2020-01-31', ...)
133+
134+
Some of these data providers require registration. In those cases, your
135+
access credentials must be passed as parameters to the function. See the
136+
individual function documentation pages for details.
137+
138+
139+
Reading local files
140+
*******************
141+
142+
:py:mod:`pvlib.iotools` also provides functions for parsing data files
143+
stored locally on your computer.
144+
Functions that read and parse local data files are named ``read_``, followed by
145+
the name of the file format they parse: :py:func:`~pvlib.iotools.read_tmy3`,
146+
:py:func:`~pvlib.iotools.read_epw`, and so on.
147+
148+
For example, here is how to read a file in the TMY3 file format:
149+
150+
.. code-block:: python
151+
152+
df, metadata = pvlib.iotools.read_tmy3(r"C:\path\to\file.csv", map_variables=True)
153+
154+
155+
References
156+
----------
157+
.. [1] Jensen et al. "pvlib iotools—Open-source Python functions for seamless
158+
access to solar irradiance data". Solar Energy, 2023.
159+
:doi:`10.1016/j.solener.2023.112092`.

‎docs/sphinx/source/whatsnew/v0.10.3.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Testing
2424

2525
Documentation
2626
~~~~~~~~~~~~~
27+
* Create :ref:`weatherdata` User's Guide page. (:pull:`1754`)
2728
* Fixed a plotting issue in the IV curve gallery example (:pull:`1895`)
2829
* Fixed `detect_clearsky` example in `clearsky.rst` (:issue:`1914`)
2930

@@ -34,3 +35,6 @@ Contributors
3435
* Will Hobbs (:ghuser:`williamhobbs`)
3536
* Anton Driesse (:ghuser:`adriesse`)
3637
* :ghuser:`matsuobasho`
38+
* Harry Jack (:ghuser:`harry-solcast`)
39+
* Adam R. Jensen (:ghuser:`AdamRJensen`)
40+
* Kevin Anderson (:ghuser:`kandersolar`)

0 commit comments

Comments
 (0)