-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
232 lines (151 loc) · 10.9 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
---
output:
github_document:
html_preview: yes
---
<!--
Copyright 2022 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the License.
-->
```{r setup, include=FALSE, cache = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
knitr::opts_chunk$set(echo = FALSE
, comment = NA
, warning = FALSE
, error = FALSE
, message = FALSE
, tidy = TRUE)
library(rprojroot)
knitr::opts_knit$set(root.dir = rprojroot::find_rstudio_root_file()) # Ensure that the package will go to the root folder to look for data
```
# bcsnowdata
<!-- badges: start -->
[![img](https://img.shields.io/badge/Lifecycle-Maturing-007EC6)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
<!-- badges: end -->
## Project Status
This package is currently under development, and subject to future changes and iterations.
This package is maintained by River Forecast Centre, part of the Water Management Branch of the Ministry of Forest Lands, Natural Resource Operations and Rural Development within the Government of British Columbia.
## What does bcsnowdata do?
This package contains functions for retrieving snow-related data from the BC Data Catalogue, which can be found [here](https://catalogue.data.gov.bc.ca/dataset?q=snow&download_audience=Public&sort=score+desc%2C+record_publish_date+desc).
Data is collected from both manual and automated snow weather (ASWE) stations around the province. These sites, and data collection, is the responsibility of the Ministry of Environment and Climate Change Strategy’s Snow Survey Program, BC Hydro and other partners. Snow data includes snow water equivalent (SWE; both manual and automated stations), snow depth (ASWE and manual sites), precipitation (ASWE), and temperature (ASWE sites). The authors of this package are not responsible for any errors within the source data, and assume no responsibility or liability for subsequent use of any data resources compiled by these functions.
This package uses the [bcdata](https://github.com/bcgov/bcdata) package to access ASWE and manual snow data from the BC Data Catalogue, and provides a means of quickly accessing different records across the different types of data that exist for snow within the BC Data Catalogue.
### Features
This package features functions for retrieving BC snow data from the BC Data Catalogue for ASWE stations and manual snow surveys. It also contains functions for retrieving the location metadata of snow survey and automated snow weather stations, as well as snow basin administrative areas.
### Installation
The snow package can be installed from GitHub:
```
install.packages("remotes", repos = "http://cran.us.r-project.org")
remotes::install_github("bcgov/bcsnowdata")
library(bcsnowdata)
```
### Usage
This package contains seven functions for returning snow-associated data.
#### get_snow
The get_snow function retrieves either ASWE or manual data, and does not require the user to specify whether the site(s) they are retrieving data for are manual or ASWE sites.
The get_snow function is a wrapper for the get_aswe_databc() and get_manual_swe() functions detailed below.
Variables include:
- id: Station ID of the site(s) to retrieve data for. Can also be: "All"(all manual and ASWE sites), "automated" (all ASWE sites), or "manual" (all manual snow sites).
- get_year: water year you want to retrieve data for.
- survey_period: manual site survey period you want to retrieve data for (in "01-01" or "Jan-01" format). Only for manual data.
- parameter: Type of data you are retrieving for ASWE data. Only for ASWE data.
- timestep: Whether you are trying to retrieve hourly or daily ASWE data. Only for ASWE data.
```{r, get_snow, echo = T, include = TRUE, results = 'hide'}
library(bcsnowdata)
# Get hourly swe data for 2022 water year for 1A01P
aswe_test <- get_snow(id = "1A01P",
get_year = "2022",
parameter = "swe",
timestep = "hourly"
)
# Get manual snow data for all sites for the 2022 water year across all survey periods
manual_test <- get_snow(id = "1A06A",
get_year = "2022",
survey_period = "all"
)
```
#### Automated Snow Function
get_aswe_databc() retrieves data for automated snow stations, including snow water equivalent (swe), snow depth, precipitation and air temperature. Hourly data is available until 2003, and daily data available before that for stations that were established before this point up to (and including) the current water year.
The user can define multiple options within the function, including:
1. station_id: This function will retrieve data for one station (by specified station ID), or multiple stations specified within a string (i.e., c("2F05P", "1C18P")). The user can also specify to return all ASWE stations within the Data BC Catalogue.
2. get_year: Specifies the year you want to return. Can be one water year, multiple, or all.
3. parameter_id: Specifies what type of data you want to retrieve. The choices include SWE, Temperature, SD (snow depth), and Precipitation.
4. timestep: Specifies what type of data to retrieve (hourly or daily average).
The function in this example will retrieve data for station ID 2F05P for all years on record without updating the cache of historic data (data prior to this water year).
```{r, get_aswe_databc, echo = T, include = TRUE, results = 'hide'}
# Get hourly swe data for one station across all years available (no data available before 2003 for all stations)
id <- c("2F05P")
SWE_test <- get_aswe_databc(station_id = id,
get_year = "All",
parameter = "swe",
timestep = "hourly")
```
#### Manual Snow Survey Data Function
The manual snow station data function - get_manual_swe() - is similar to the function that gets data from the ASWE sites.
Specifically, the user can define multiple options within the function, including:
1. station_id: This function will retrieve data for one station (by specified station ID), or multiple stations specified within a string (i.e., c("2F05P", "1C18P")). The user can also specify to return all manual snow survey locations within the Data BC catalogue. This is significantly faster than the ASWE station function.
2. survey_period: Specifies what survey period the user wants to return. Can be "All" (the default within the function), or else a specific survey period (or number of them). The format can either be numeric month year (i.e., "03-01" is March 1), or annotated in the format day-month, such as "01-Mar".
```{r, get_manual_swe, echo = T, include = TRUE, results = 'hide'}
# Retrieve manual snow survey data for one site over all survey periods and years
id <- c("1C21")
manual_test <- get_manual_swe(station_id = id,
survey_period = "All",
get_year = "All")
```
##### Automated Snow Weather Station Locations
The snow_auto_location() returns a dataframe containing location metadata for all of the automated snow weather stations. The returned dataframe includes both active as well as inactive stations, in addition to their latitude, longitude and elevation.
Data obtained from the [BC Data Catalogue](https://catalogue.data.gov.bc.ca/dataset/automated-snow-weather-station-locations).
``` {r, snow_auto_location, echo = T, include = TRUE, results = 'hide'}
ASWE_locations <- snow_auto_location()
head(ASWE_locations)
```
##### Manual Snow Survey Locations
The snow_auto_location() function returns a dataframe containing location metadata for all of the manual snow survey locations. The returned dataframe includes both active as well as inactive stations, in addition to their latitude, longitude and elevation.
Data obtained from the [BC Data Catalogue](https://catalogue.data.gov.bc.ca/dataset/manual-snow-survey-locations).
``` {r, snow_manual_location, echo = T, include = TRUE, results = 'hide'}
manual_locations <- snow_manual_location()
head(manual_locations)
```
##### Snow Survey Administrative Basin Areas
The snow_auto_location() returns a dataframe containing location metadata for the administrative basin areas. Returned data includes the polygon geometries necessary to map snow basin areas (for example, upon integration with the bcmaps() package).
Data obtained from the [BC Data Catalogue](https://catalogue.data.gov.bc.ca/dataset/snow-survey-administrative-basin-areas).
`````` {r, snow_basin_areas, echo = T, include = TRUE, results = 'hide'}
basin_locations <- snow_basin_areas()
head(basin_locations)
```
##### Assign water year
This package also contains the function wtr_yr() for assigning water year to a column of dates. It is meant as an internal function that can also be called externally. The main input is a vector or column of dates that are used to calculate the corresponding water year. The default start to the calendar year is October (start_month = 10).
`````` {r, wtr_yr, echo = T, include = TRUE, results = 'hide'}
wtr_yr(as.Date("2018-12-01"))
```
### Project Status
This project is in active development and subject to change.
### Getting Help or Reporting an Issue
To report bugs/issues/feature requests, please file an [issue](https://github.com/bcgov/bcsnowdata/issues/).
### How to Contribute
If you would like to contribute to the package, please see our
[CONTRIBUTING](CONTRIBUTING.md) guidelines.
Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.
### License
```
Copyright 2022 Province of British Columbia
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and limitations under the License.
```
---
*This project was created using the [bcgovr](https://github.com/bcgov/bcgovr) package.*