Skip to content

Commit

Permalink
Document the first use of get_key()
Browse files Browse the repository at this point in the history
  • Loading branch information
@adamhsparks
adamhsparks committed Jul 7, 2024
1 parent b36c335 commit 0da2030
Show file tree
Hide file tree
Showing 6 changed files with 151 additions and 114 deletions.
16 changes: 16 additions & 0 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,22 @@ The examples in this README assume that you have stored your API key in your .Re
{weatherOz} will prompt you to set up your API keys automatically if you haven't.
For more information on the preferred method for setting up your API keys, see [Chapter 8](https://rstats.wtf/r-startup.html#renviron) in "What They Forgot to Teach You About R" by Bryan *et al.* for more on storing details in your .Renviron if you are unfamiliar.

To get a DPIRD API key, you can use `get_key()` and it will direct you to the form to request a key and provides instructions for using `usethis::edit_r_environ()` to add your key to your .Renviron so that {weatherOz} will automatically find it.
If you have already set up an API key, this will return that value for you.

```{r get-dpird-key, eval=FALSE}
get_key(source = "DPIRD")
```

You only need to provide an e-mail address for the SILO API.
Using `get_key()` will provide you with instructions on what format to use in your .Renviron so that {weatherOz} will auto-recognise it and if you have already set up an API key, this will return that value for you.

```{r get-silo-key, eval=FALSE}
get_key(source = "SILO")
```

Note that you do not need to do this separately, any function requiring an API key will prompt you if you don't have one set.

## Example 1

Source wind and erosion conditions for daily time interval from the DPIRD Weather 2.0 API.
Expand Down
22 changes: 22 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,6 +82,28 @@ method for setting up your API keys, see [Chapter
Teach You About R” by Bryan *et al.* for more on storing details in your
.Renviron if you are unfamiliar.

To get a DPIRD API key, you can use `get_key()` and it will direct you
to the form to request a key and provides instructions for using
`usethis::edit_r_environ()` to add your key to your .Renviron so that
{weatherOz} will automatically find it. If you have already set up an
API key, this will return that value for you.

``` r
get_key(source = "DPIRD")
```

You only need to provide an e-mail address for the SILO API. Using
`get_key()` will provide you with instructions on what format to use in
your .Renviron so that {weatherOz} will auto-recognise it and if you
have already set up an API key, this will return that value for you.

``` r
get_key(source = "SILO")
```

Note that you do not need to do this separately, any function requiring
an API key will prompt you if you don’t have one set.

## Example 1

Source wind and erosion conditions for daily time interval from the
Expand Down
2 changes: 1 addition & 1 deletion codemeta.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -554,7 +554,7 @@
"applicationCategory": "Tools",
"isPartOf": "https://ropensci.org",
"keywords": ["dpird", "bom", "meteorological-data", "weather-forecast", "australia", "weather", "weather-data", "meteorology", "western-australia", "australia-bureau-of-meteorology", "western-australia-agriculture", "australia-agriculture", "australia-climate", "australia-weather", "rstats", "climate", "api-client", "data", "weather-api", "rainfall", "r"],
"fileSize": "5566.198KB",
"fileSize": "5568.386KB",
"citation": [
{
"@type": "ScholarlyArticle",
Expand Down
Binary file modified vignettes/dpird-station-locations-map-1.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
208 changes: 95 additions & 113 deletions vignettes/weatherOz.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,25 @@ The examples in this README assume that you have stored your API key in your .Re
{weatherOz} will prompt you to set up your API keys automatically if you haven't.
For more information on the preferred method for setting up your API keys, see [Chapter 8](https://rstats.wtf/r-startup.html#renviron) in "What They Forgot to Teach You About R" by Bryan *et al.* for more on storing details in your .Renviron if you are unfamiliar.

To get a DPIRD API key, you can use `get_key()` and it will direct you to the form to request a key and provides instructions for using `usethis::edit_r_environ()` to add your key to your .Renviron so that {weatherOz} will automatically find it.
If you have already set up an API key, this will return that value for you.


``` r
get_key(source = "DPIRD")
```

You only need to provide an e-mail address for the SILO API.
Using `get_key()` will provide you with instructions on what format to use in your .Renviron so that {weatherOz} will auto-recognise it and if you have already set up an API key, this will return that value for you.



``` r
get_key(source = "SILO")
```

Note that you do not need to do this separately, any function requiring an API key will prompt you if you don't have one set.

## Using {weatherOz} to Fetch Daily Summary DPIRD Data

Daily summary weather data is frequently used.
Expand All @@ -65,14 +84,10 @@ Northam
#> <fctr> <char> <num> <num> <char> <int>
#> 1: NO Northam 116.6942 -31.65161 WA 163
#> 2: MK Muresk 116.6913 -31.72772 WA 251
#> owner
#> <char>
#> 1: WA Department of Primary Industries and Regional Development (DPIRD)
#> 2: WA Department of Primary Industries and Regional Development (DPIRD)
#> distance_km
#> <num>
#> 1: 3.23
#> 2: 7.93
#> owner distance_km
#> <char> <num>
#> 1: WA Department of Primary Industries and Regional Development (DPIRD) 3.23
#> 2: WA Department of Primary Industries and Regional Development (DPIRD) 7.93
```

There are two stations within 20km of the coordinates for Northam, WA that we provided.
Expand All @@ -89,45 +104,45 @@ dpird_daily <- get_dpird_summaries(

dpird_daily
#> Key: <station_code>
#> station_code station_name longitude latitude year month day date
#> <fctr> <char> <num> <num> <int> <int> <int> <Date>
#> 1: NO Northam 116.6942 -31.65161 2022 1 1 2022-01-01
#> 2: NO Northam 116.6942 -31.65161 2022 1 2 2022-01-02
#> 3: NO Northam 116.6942 -31.65161 2022 1 3 2022-01-03
#> 4: NO Northam 116.6942 -31.65161 2022 1 4 2022-01-04
#> 5: NO Northam 116.6942 -31.65161 2022 1 5 2022-01-05
#> ---
#> 361: NO Northam 116.6942 -31.65161 2022 12 27 2022-12-27
#> 362: NO Northam 116.6942 -31.65161 2022 12 28 2022-12-28
#> 363: NO Northam 116.6942 -31.65161 2022 12 29 2022-12-29
#> 364: NO Northam 116.6942 -31.65161 2022 12 30 2022-12-30
#> 365: NO Northam 116.6942 -31.65161 2022 12 31 2022-12-31
#> air_tavg air_tmax air_tmax_time air_tmin air_tmin_time
#> <num> <num> <POSc> <num> <POSc>
#> 1: 23.8 32.5 2022-01-01 17:02:00 16.7 2022-01-01 05:17:00
#> 2: 25.4 36.1 2022-01-02 16:58:00 14.4 2022-01-02 05:19:00
#> 3: 28.0 39.9 2022-01-03 14:42:00 16.6 2022-01-03 05:18:00
#> 4: 26.1 36.3 2022-01-04 15:15:00 17.3 2022-01-04 04:22:00
#> 5: 27.3 39.1 2022-01-05 16:19:00 16.1 2022-01-05 05:14:00
#> ---
#> 361: 23.0 40.2 2022-12-27 14:48:20 13.7 2022-12-27 05:13:20
#> 362: 22.2 40.5 2022-12-28 19:58:20 11.9 2022-12-28 05:33:20
#> 363: 26.0 40.2 2022-12-30 03:03:20 13.8 2022-12-29 05:01:40
#> 364: 26.6 39.2 2022-12-30 13:50:50 14.5 2022-12-30 04:52:30
#> 365: 22.7 31.1 2022-12-31 15:45:50 16.2 2022-12-31 05:23:20
#> rainfall rh_avg rh_tmax rh_tmax_time rh_tmin rh_tmin_time
#> <num> <num> <num> <POSc> <num> <POSc>
#> 1: 0 39.9 71.5 2022-01-01 04:10:00 14.5 2022-01-01 18:03:00
#> 2: 0 35.2 63.8 2022-01-02 05:39:00 16.4 2022-01-02 16:58:00
#> 3: 0 38.0 68.5 2022-01-03 05:22:00 14.4 2022-01-03 16:15:00
#> 4: 0 45.9 74.2 2022-01-04 04:33:00 20.1 2022-01-04 16:35:00
#> 5: 0 42.1 77.2 2022-01-05 05:22:00 14.4 2022-01-05 17:21:00
#> ---
#> 361: 0 41.8 81.1 2022-12-26 16:03:20 14.6 2022-12-27 16:47:30
#> 362: 0 32.8 65.4 2022-12-28 05:35:00 9.2 2022-12-28 16:11:40
#> 363: 0 29.2 62.5 2022-12-29 05:08:20 9.5 2022-12-29 17:31:40
#> 364: 0 34.4 61.2 2022-12-30 05:06:40 7.9 2022-12-30 14:00:00
#> 365: 0 59.0 98.9 2022-12-31 05:30:00 24.7 2022-12-31 16:01:40
#> station_code station_name longitude latitude year month day date air_tavg air_tmax
#> <fctr> <char> <num> <num> <int> <int> <int> <Date> <num> <num>
#> 1: NO Northam 116.6942 -31.65161 2022 1 1 2022-01-01 23.8 32.5
#> 2: NO Northam 116.6942 -31.65161 2022 1 2 2022-01-02 25.4 36.1
#> 3: NO Northam 116.6942 -31.65161 2022 1 3 2022-01-03 28.0 39.9
#> 4: NO Northam 116.6942 -31.65161 2022 1 4 2022-01-04 26.1 36.3
#> 5: NO Northam 116.6942 -31.65161 2022 1 5 2022-01-05 27.3 39.1
#> ---
#> 361: NO Northam 116.6942 -31.65161 2022 12 27 2022-12-27 23.0 40.2
#> 362: NO Northam 116.6942 -31.65161 2022 12 28 2022-12-28 22.2 40.5
#> 363: NO Northam 116.6942 -31.65161 2022 12 29 2022-12-29 26.0 40.2
#> 364: NO Northam 116.6942 -31.65161 2022 12 30 2022-12-30 26.6 39.2
#> 365: NO Northam 116.6942 -31.65161 2022 12 31 2022-12-31 22.7 31.1
#> air_tmax_time air_tmin air_tmin_time rainfall rh_avg rh_tmax rh_tmax_time rh_tmin
#> <POSc> <num> <POSc> <num> <num> <num> <POSc> <num>
#> 1: 2022-01-01 17:02:00 16.7 2022-01-01 05:17:00 0 39.9 71.5 2022-01-01 04:10:00 14.5
#> 2: 2022-01-02 16:58:00 14.4 2022-01-02 05:19:00 0 35.2 63.8 2022-01-02 05:39:00 16.4
#> 3: 2022-01-03 14:42:00 16.6 2022-01-03 05:18:00 0 38.0 68.5 2022-01-03 05:22:00 14.4
#> 4: 2022-01-04 15:15:00 17.3 2022-01-04 04:22:00 0 45.9 74.2 2022-01-04 04:33:00 20.1
#> 5: 2022-01-05 16:19:00 16.1 2022-01-05 05:14:00 0 42.1 77.2 2022-01-05 05:22:00 14.4
#> ---
#> 361: 2022-12-27 14:48:20 13.7 2022-12-27 05:13:20 0 41.8 81.1 2022-12-26 16:03:20 14.6
#> 362: 2022-12-28 19:58:20 11.9 2022-12-28 05:33:20 0 32.8 65.4 2022-12-28 05:35:00 9.2
#> 363: 2022-12-30 03:03:20 13.8 2022-12-29 05:01:40 0 29.2 62.5 2022-12-29 05:08:20 9.5
#> 364: 2022-12-30 13:50:50 14.5 2022-12-30 04:52:30 0 34.4 61.2 2022-12-30 05:06:40 7.9
#> 365: 2022-12-31 15:45:50 16.2 2022-12-31 05:23:20 0 59.0 98.9 2022-12-31 05:30:00 24.7
#> rh_tmin_time
#> <POSc>
#> 1: 2022-01-01 18:03:00
#> 2: 2022-01-02 16:58:00
#> 3: 2022-01-03 16:15:00
#> 4: 2022-01-04 16:35:00
#> 5: 2022-01-05 17:21:00
#> ---
#> 361: 2022-12-27 16:47:30
#> 362: 2022-12-28 16:11:40
#> 363: 2022-12-29 17:31:40
#> 364: 2022-12-30 14:00:00
#> 365: 2022-12-31 16:01:40
```

## Using {weatherOz} to Fetch Patched Point SILO Data
Expand All @@ -149,20 +164,13 @@ Tbar <-
)

Tbar
#> station_code station_name longitude latitude state elev_m owner
#> <fctr> <char> <num> <num> <char> <num> <char>
#> 1: 041529 Toowoomba Airport 151.9134 -27.5425 QLD 640.9 BOM
#> 2: 041369 Moyola 151.8819 -27.5233 QLD 559.0 BOM
#> 3: 040096 Helidon Post Office 152.1246 -27.5504 QLD 155.0 BOM
#> 4: 041011 Cambooya Post Office 151.8650 -27.7072 QLD 476.0 BOM
#> 5: 041512 Cooby Creek Dam 151.9244 -27.3825 QLD 497.0 BOM
#> distance_km
#> <num>
#> 1: 4.149375
#> 2: 7.903524
#> 3: 17.172757
#> 4: 18.433372
#> 5: 19.881135
#> station_code station_name longitude latitude state elev_m owner distance_km
#> <fctr> <char> <num> <num> <char> <num> <char> <num>
#> 1: 041529 Toowoomba Airport 151.9134 -27.5425 QLD 640.9 BOM 4.149375
#> 2: 041369 Moyola 151.8819 -27.5233 QLD 559.0 BOM 7.903524
#> 3: 040096 Helidon Post Office 152.1246 -27.5504 QLD 155.0 BOM 17.172757
#> 4: 041011 Cambooya Post Office 151.8650 -27.7072 QLD 476.0 BOM 18.433372
#> 5: 041512 Cooby Creek Dam 151.9244 -27.3825 QLD 497.0 BOM 19.881135
```

There are 11 stations within 20km of the coordinates for Toowoomba, Qld that we provided in the SILO database.
Expand All @@ -178,58 +186,32 @@ ppd <- get_patched_point(
)

ppd
#> station_code station_name year month day date air_tmax
#> <fctr> <char> <num> <num> <int> <Date> <num>
#> 1: 041103 Toowoomba 2022 1 1 2022-01-01 22.8
#> 2: 041103 Toowoomba 2022 1 2 2022-01-02 27.7
#> 3: 041103 Toowoomba 2022 1 3 2022-01-03 29.4
#> 4: 041103 Toowoomba 2022 1 4 2022-01-04 30.0
#> 5: 041103 Toowoomba 2022 1 5 2022-01-05 29.5
#> ---
#> 361: 041103 Toowoomba 2022 12 27 2022-12-27 26.2
#> 362: 041103 Toowoomba 2022 12 28 2022-12-28 26.7
#> 363: 041103 Toowoomba 2022 12 29 2022-12-29 27.6
#> 364: 041103 Toowoomba 2022 12 30 2022-12-30 27.0
#> 365: 041103 Toowoomba 2022 12 31 2022-12-31 27.7
#> air_tmax_source air_tmin air_tmin_source elev_m extracted latitude
#> <int> <num> <int> <char> <Date> <num>
#> 1: 25 16.6 25 691.0 m 2024-07-07 -27.5836
#> 2: 25 14.2 25 691.0 m 2024-07-07 -27.5836
#> 3: 25 13.8 25 691.0 m 2024-07-07 -27.5836
#> 4: 25 16.8 25 691.0 m 2024-07-07 -27.5836
#> 5: 25 17.5 25 691.0 m 2024-07-07 -27.5836
#> ---
#> 361: 25 15.1 25 691.0 m 2024-07-07 -27.5836
#> 362: 25 13.0 25 691.0 m 2024-07-07 -27.5836
#> 363: 25 14.1 25 691.0 m 2024-07-07 -27.5836
#> 364: 25 17.0 25 691.0 m 2024-07-07 -27.5836
#> 365: 25 16.4 25 691.0 m 2024-07-07 -27.5836
#> longitude rainfall rainfall_source rh_tmax rh_tmax_source rh_tmin
#> <num> <num> <int> <num> <int> <num>
#> 1: 151.9317 7.6 25 72.1 26 100.0
#> 2: 151.9317 0.1 25 47.1 26 100.0
#> 3: 151.9317 0.0 25 38.8 26 100.0
#> 4: 151.9317 0.0 25 43.1 26 95.7
#> 5: 151.9317 0.0 25 49.2 26 100.0
#> ---
#> 361: 151.9317 0.0 25 47.9 26 95.0
#> 362: 151.9317 0.2 25 43.7 26 100.0
#> 363: 151.9317 0.0 25 44.1 26 100.0
#> 364: 151.9317 0.7 25 60.3 26 100.0
#> 365: 151.9317 0.4 25 50.9 26 100.0
#> rh_tmin_source
#> <int>
#> 1: 26
#> 2: 26
#> 3: 26
#> 4: 26
#> 5: 26
#> ---
#> 361: 26
#> 362: 26
#> 363: 26
#> 364: 26
#> 365: 26
#> station_code station_name year month day date air_tmax air_tmax_source air_tmin air_tmin_source
#> <fctr> <char> <num> <num> <int> <Date> <num> <int> <num> <int>
#> 1: 041103 Toowoomba 2022 1 1 2022-01-01 22.8 25 16.6 25
#> 2: 041103 Toowoomba 2022 1 2 2022-01-02 27.7 25 14.2 25
#> 3: 041103 Toowoomba 2022 1 3 2022-01-03 29.4 25 13.8 25
#> 4: 041103 Toowoomba 2022 1 4 2022-01-04 30.0 25 16.8 25
#> 5: 041103 Toowoomba 2022 1 5 2022-01-05 29.5 25 17.5 25
#> ---
#> 361: 041103 Toowoomba 2022 12 27 2022-12-27 26.2 25 15.1 25
#> 362: 041103 Toowoomba 2022 12 28 2022-12-28 26.7 25 13.0 25
#> 363: 041103 Toowoomba 2022 12 29 2022-12-29 27.6 25 14.1 25
#> 364: 041103 Toowoomba 2022 12 30 2022-12-30 27.0 25 17.0 25
#> 365: 041103 Toowoomba 2022 12 31 2022-12-31 27.7 25 16.4 25
#> elev_m extracted latitude longitude rainfall rainfall_source rh_tmax rh_tmax_source rh_tmin rh_tmin_source
#> <char> <Date> <num> <num> <num> <int> <num> <int> <num> <int>
#> 1: 691.0 m 2024-07-07 -27.5836 151.9317 7.6 25 72.1 26 100.0 26
#> 2: 691.0 m 2024-07-07 -27.5836 151.9317 0.1 25 47.1 26 100.0 26
#> 3: 691.0 m 2024-07-07 -27.5836 151.9317 0.0 25 38.8 26 100.0 26
#> 4: 691.0 m 2024-07-07 -27.5836 151.9317 0.0 25 43.1 26 95.7 26
#> 5: 691.0 m 2024-07-07 -27.5836 151.9317 0.0 25 49.2 26 100.0 26
#> ---
#> 361: 691.0 m 2024-07-07 -27.5836 151.9317 0.0 25 47.9 26 95.0 26
#> 362: 691.0 m 2024-07-07 -27.5836 151.9317 0.2 25 43.7 26 100.0 26
#> 363: 691.0 m 2024-07-07 -27.5836 151.9317 0.0 25 44.1 26 100.0 26
#> 364: 691.0 m 2024-07-07 -27.5836 151.9317 0.7 25 60.3 26 100.0 26
#> 365: 691.0 m 2024-07-07 -27.5836 151.9317 0.4 25 50.9 26 100.0 26
```

{weatherOz} offers much more functionality that is detailed in other vignettes that document how to use it to get station metadata for any station in the DPIRD or SILO databases, get extreme weather events for the DPIRD station network, get minute data for DPIRD stations, get APSIM formatted data from SILO, get ag bulletins, précis forecasts and various imagery files from BOM in the respective vignettes for DPIRD, SILO and BOM data available through {weatherOz}.
Expand Down
Loading

0 comments on commit 0da2030

Please sign in to comment.