Skip to content

Commit

Permalink
docs test
Browse files Browse the repository at this point in the history
  • Loading branch information
@egagli
egagli committed Sep 22, 2024
1 parent 7293f59 commit 87f8a64
Show file tree
Hide file tree
Showing 2 changed files with 146 additions and 65 deletions.
205 changes: 143 additions & 62 deletions easysnowdata/automatic_weather_stations.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,46 @@


class StationCollection:
"""
A collection of automatic weather stations, including SNOTEL and CCSS stations.
This class manages a collection of weather stations, allowing for data retrieval,
spatial subsetting, and various data processing operations. It supports both
SNOTEL and CCSS station types.
Parameters
----------
snotel_stations : bool, optional
Whether to include SNOTEL stations in the collection. Default is True.
ccss_stations : bool, optional
Whether to include CCSS stations in the collection. Default is False.
Attributes
----------
all_stations : geopandas.GeoDataFrame
A GeoDataFrame containing all the stations in the collection.
chosen_stations : geopandas.GeoDataFrame
A GeoDataFrame containing the subset of stations chosen for analysis.
Examples
--------
Create a StationCollection with both SNOTEL and CCSS stations...
>>> station_collection = StationCollection(snotel_stations=True, ccss_stations=True)
>>> print(station_collection.all_stations)
Create a StationCollection with only SNOTEL stations and choose stations within a specific bounding box...
>>> snotel_collection = StationCollection(snotel_stations=True, ccss_stations=False)
>>> snotel_collection.choose_stations_by_bbox((-121.94, 46.72, -121.54, 46.99))
>>> print(snotel_collection.chosen_stations)
Notes
-----
Data sources:
SNOTEL: https://www.nrcs.usda.gov/wps/portal/wcc/home/quicklinks/imap
CCSS: https://cdec.water.ca.gov/snow/current/snow/
"""
def __init__(
self,
data_available: bool = True,
Expand Down Expand Up @@ -56,19 +96,18 @@ def __init__(
def get_all_stations(self):
"""
Fetches all weather stations from a GeoJSON file hosted on the snotel_ccss_stations GitHub repository.
The function allows filtering based on data availability and station network type. Optionally, a geometry
can be passed in to calculate the distance of each station to this geometry and sort the stations by this distance.
Parameters:
data_available (bool): If True, only stations with available data are included.
snotel_stations (bool): If True, stations from the SNOTEL network are included.
ccss_stations (bool): If True, stations from the CCSS network are included.
sortby_dist_to_geom (GeoDataFrame, tuple, Polygon): An optional geometry to calculate distances to.
Can be a GeoDataFrame, a tuple representing a point (longitude, latitude),
or a Shapely Polygon.
Returns:
GeoDataFrame: A GeoDataFrame containing the details of the stations. Optionally adds a 'dist_km' column, representing distance from each station to the input geometry.
This method retrieves station data, filters based on data availability, and optionally sorts stations
by distance to a specified geometry.
Returns
-------
None
Updates the all_stations attribute of the class.
Notes
-----
The method prints information about the retrieved stations and available data access methods.
"""
# Read the GeoJSON file
all_stations_gdf = gpd.read_file(
Expand Down Expand Up @@ -110,14 +149,28 @@ def get_all_stations(self):

def choose_stations(self, stations_gdf):
"""
Choose the stations to be used for further analysis.
Choose specific stations for further analysis.
Parameters:
- stations_gdf: gpd.GeoDataFrame, str, or list
This method allows selection of specific stations from the collection
for subsequent data processing and analysis.
Parameters
----------
stations_gdf : gpd.GeoDataFrame, str, or list
The name(s) or index(es) of the stations to be chosen.
Returns:
Returns
-------
None
Updates the stations attribute of the class.
Examples
--------
Choose stations by name:
>>> station_collection.choose_stations('Paradise')
Choose multiple stations by index:
>>> station_collection.choose_stations([0, 1, 2])
"""
if type(stations_gdf) is str:
stations_gdf = self.all_stations.loc[[stations_gdf]]
Expand All @@ -128,31 +181,29 @@ def choose_stations(self, stations_gdf):

def get_data(self, stations="679_WA_SNTL", variables=None, start_date='1900-01-01', end_date=today):
"""
Retrieves data for the specified stations and variables. Access retrieved data using the .{variable} or .data attribute.
Parameters:
- stations (geodataframe, str, or list): The stations to retrieve data for. Defaults to '679_WA_SNTL'.
- variables (str or list): The variables to retrieve data for. Defaults to None.
- start_date (str): The start date for the data. Defaults to '1900-01-01'.
- end_date (str): The end date for the data. Defaults to today's date.
Returns:
Retrieves data for the specified stations and variables.
This method fetches data for chosen stations and variables within a specified date range.
Parameters
----------
stations : geodataframe, str, or list, optional
The stations to retrieve data for. Default is '679_WA_SNTL'.
variables : str or list, optional
The variables to retrieve data for. Default is None.
start_date : str, optional
The start date for the data. Default is '1900-01-01'.
end_date : str, optional
The end date for the data. Default is today's date.
Returns
-------
None
Updates the data attribute of the class.
If only one station is chosen and variables is None, all variables for that station will be fetched.
If only one station is chosen and variables is specified, only the specified variables will be fetched for that station.
If multiple stations are chosen and variables is None, WTEQ (Water Equivalent) data will be fetched for all stations.
If multiple stations are chosen and variables is specified, only the specified variables will be fetched for all stations.
Example usage:
>>> stations = easysnowdata.automatic_weather_stations.Stations()
>>> stations.get_data(stations='679_WA_SNTL', variables=['WTEQ', 'SNWD'])
Retrieves SWE and snow depth data for the station '679_WA_SNTL'.
>>> bbox_gdf = gpd.read_file('https://github.com/egagli/sar_snowmelt_timing/raw/main/input/shapefiles/mt_rainier.geojson')
>>> stations = easysnowdata.automatic_weather_stations.Stations(sortby_dist_to_geom=bbox_gdf)
>>> stations.get_data(stations=stations.all_stations.iloc[0:4])
Retrieves all variables for the 4 stations closest to the input geometry.
Notes
-----
The behavior of this method varies based on the number of stations chosen and the specified variables.
"""

self.choose_stations(stations)
Expand Down Expand Up @@ -180,11 +231,25 @@ def get_single_station_data(
"""
Retrieves data for a single weather station.
Args:
variables (list, optional): List of variables to include in the data. Defaults to ['WTEQ','SNWD','PRCPSA','TAVG','TMIN','TMAX'].
This method fetches data for specified variables from a single station within a given date range.
Parameters
----------
variables : list, optional
List of variables to include in the data. Default is ['WTEQ','SNWD','PRCPSA','TAVG','TMIN','TMAX'].
start_date : str, optional
The start date for the data. Default is '1900-01-01'.
end_date : str, optional
The end date for the data. Default is today's date.
Returns
-------
None
Updates the data attribute of the class.
Returns:
None
Notes
-----
The method prints a message indicating that the data has been added to the Station object.
"""

single_station_df = pd.read_csv(
Expand All @@ -204,15 +269,27 @@ def get_single_station_data(

def get_multiple_station_data(self, variables="WTEQ", start_date='1900-01-01', end_date=today):
"""
Fetches the data for the specified variable(s) from the snotel_ccss_stations GitHub repository.
Fetches data for multiple stations and specified variables.
Parameters:
variables (str or list): The variable(s) to fetch. Default is 'WTEQ' (water equivalent of snow on the ground).
Can be a single variable as a string or multiple variables as a list.
This method retrieves data for multiple stations and specified variables within a given date range.
Returns:
DataFrame: A DataFrame containing the data for the specified variable(s).
Parameters
----------
variables : str or list, optional
The variable(s) to fetch. Default is 'WTEQ' (water equivalent of snow on the ground).
start_date : str, optional
The start date for the data. Default is '1900-01-01'.
end_date : str, optional
The end date for the data. Default is today's date.
Returns
-------
None
Updates the data attribute of the class with an xarray Dataset.
Notes
-----
The method prints messages indicating the progress of data retrieval and processing.
"""

dataarrays = []
Expand Down Expand Up @@ -273,21 +350,25 @@ def get_multiple_station_data(self, variables="WTEQ", start_date='1900-01-01', e

def get_entire_data_archive(self, refresh: bool = True, temp_dir: str = "/tmp/") -> xr.Dataset:
"""
Downloads, decompresses and processes automatic weather station data into an xarray Dataset.
Downloads, decompresses and processes the entire automatic weather station data archive.
This method retrieves a compressed file containing all station data, processes it, and creates an xarray Dataset.
This function downloads a compressed file containing weather station data from a specific URL,
decompresses the file, and processes the data into an xarray Dataset. The data is organized by station,
with each station's data stored in a separate CSV file. The function also adds additional coordinates
to the Dataset from a provided GeoDataFrame. Set the refresh parameter to True to redownload cached data.
Parameters
----------
refresh : bool, optional
If True, the compressed data file will be redownloaded. Default is True.
temp_dir : str, optional
The directory where the compressed data file will be downloaded and decompressed. Default is '/tmp/'.
Parameters:
all_stations_gdf (GeoDataFrame): A GeoDataFrame containing additional data for each station.
refresh (bool, optional): If True, the compressed data file will be redownloaded. Defaults to True.
temp_dir (str, optional): The directory where the compressed data file will be downloaded and decompressed.
Defaults to '/tmp/'.
Returns
-------
xarray.Dataset
An xarray Dataset containing the processed weather station data for all stations.
Returns:
xarray.Dataset: An xarray Dataset containing the processed weather station data.
Notes
-----
The method prints messages indicating the progress of data retrieval, decompression, and processing.
"""

github_tar_file_path = "https://github.com/egagli/snotel_ccss_stations/raw/main/data/all_station_data.tar.lzma"
Expand Down
6 changes: 3 additions & 3 deletions easysnowdata/hydroclimatology.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,11 +273,11 @@ def get_koppen_geiger_classes(
Examples
--------
Get Köppen-Geiger climate classification data for the entire globe with a 1-degree resolution, use custom plotting function...
```python
>>> koppen_data = get_koppen_geiger_classes(bbox_input=None, resolution="1 degree")
>>> koppen_data.attrs['plot_classes'](koppen_data)
```
Get Köppen-Geiger climate classification data for a specific region with a 1 km resolution, plot using xarray's built-in plotting function...
Get Köppen-Geiger climate classification data for a specific region with a 1 km resolution, plot using xarray's built-in plotting function...
>>> koppen_geiger_da = get_koppen_geiger_classes(bbox_input=(-121.94224976, 46.72842173, -121.54136001, 46.99728203), resolution="1 km")
>>> koppen_data.plot(cmap=koppen_data.attrs["cmap"])
Expand Down

0 comments on commit 87f8a64

Please sign in to comment.