From f30472e0421019afbe994cee33b815e731b07e4a Mon Sep 17 00:00:00 2001 From: andrew-edwards Date: Fri, 8 Nov 2024 17:28:41 -0800 Subject: [PATCH] Write bccm_full vignette; update README and .gitignore. --- .gitignore | 11 +++ README.Rmd | 21 +++-- README.md | 30 +++--- vignettes/bccm_full.Rmd | 203 ++++++++++++++++++++++++++++++++++++++++ vignettes/hotssea.Rmd | 4 +- 5 files changed, 242 insertions(+), 27 deletions(-) create mode 100644 vignettes/bccm_full.Rmd diff --git a/.gitignore b/.gitignore index fcdfa473..224d3ecf 100644 --- a/.gitignore +++ b/.gitignore @@ -96,6 +96,11 @@ data-raw/zooplankton/kelly-emails.txt data-raw/depth/S102_S111sample/ data-raw/depth/S102andS111.zip +data-raw/hotssea/hotssea-original/ +data-raw/hotssea/hotssea-version-1.02.3/ +data-raw/hotssea/hotssea-version-1.02.4/ +data-raw/hotssea/testing-importing.R + data/older-data/test_grid_10.rda data/older-data/test_grid_2.rda data/older-data/test_grid_20.rda @@ -106,3 +111,9 @@ data/older-data/test_grid_20.rda /data-raw/depth/GEBCO_Grid_documentation.pdf /data-raw/depth/GEBCO_Grid_terms_of_use.pdf /data-raw/depth/gebco_2023_n58.0_s42.0_w-146.0_e-117.0.nc + +vignettes/bccm-full-figs-cache/ +vignettes/bccm_full_cache/ +vignettes/hotssea-figs-cache/ +vignettes/hotssea-cache/ +vignettes/oisst_month_grid26.rds diff --git a/README.Rmd b/README.Rmd index 4aad846d..da28980e 100644 --- a/README.Rmd +++ b/README.Rmd @@ -108,26 +108,27 @@ https://www.sciencedirect.com/science/article/pii/S0967064519300220 The values highlighed above with **Updated monthly** have been updated each month since the release of pacea, as documented in the [NEWS](NEWS.md), which it is advisable to check when you update your pacea installation (see below). Since the initial release we have -also (in order): +also (latest first): -- updated the estimates of Pacific Hake abundance and recruitment with values - from the 2024 assessment (retaining the original estimates from the 2023 - assessments for reproducibility); see the +- added Pacific Herring stock assessment results, for spawning stock biomass and + age-2 recruitment for each of the five major stock assessment regions; see the [populations.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/populations.html) vignette. -- added zooplankton biomass anomalies for the Strait of Georgia, with a new - vignette: [zooplankton.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/zooplankton.html). +- added helper function `a()`, shorthand for `as.data.frame()`, see examples in + `?a`. - extended calculations of the Aleutian Low Pressure Index (ALPI) up to 2022; they were originally only available to 2015. The Aleutian Low was mentioned in several talks at the 2024 State of the Pacific Ocean meeting, motivating us to update the values here. -- added helper function `a()`, shorthand for `as.data.frame()`, see examples in `?a`. +- added zooplankton biomass anomalies for the Strait of Georgia, with a new + vignette: [zooplankton.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/zooplankton.html). -- added Pacific Herring stock assessment results, for spawning stock biomass and - age-2 recruitment for each of the five major stock assessment regions; see the +- updated the estimates of Pacific Hake abundance and recruitment with values + from the 2024 assessment (retaining the original estimates from the 2023 + assessments for reproducibility); see the [populations.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/populations.html) vignette. @@ -353,7 +354,7 @@ If you use `pacea` in your work then please cite it as (NOTE this has been updated since the original release): Edwards A.M., Tai T.C., Watson J., Peña M.A., Hilborn A., Hannah C.G., Rooper - C.N., and Flynn K.L. (2024). pacea: An R package of Pacific ecosystem information to + C.N., Flynn K.L., and Oldford, G.L. (2024). pacea: An R package of Pacific ecosystem information to help facilitate an ecosystem approach to fisheries management. , diff --git a/README.md b/README.md index f0673ba7..dd389e8c 100644 --- a/README.md +++ b/README.md @@ -99,29 +99,29 @@ The values highlighed above with **Updated monthly** have been updated each month since the release of pacea, as documented in the [NEWS](NEWS.md), which it is advisable to check when you update your pacea installation (see below). Since the initial release we have also -(in order): +(latest first): -- updated the estimates of Pacific Hake abundance and recruitment with - values from the 2024 assessment (retaining the original estimates - from the 2023 assessments for reproducibility); see the +- added Pacific Herring stock assessment results, for spawning stock + biomass and age-2 recruitment for each of the five major stock + assessment regions; see the [populations.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/populations.html) vignette. -- added zooplankton biomass anomalies for the Strait of Georgia, with - a new vignette: - [zooplankton.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/zooplankton.html). +- added helper function `a()`, shorthand for `as.data.frame()`, see + examples in `?a`. - extended calculations of the Aleutian Low Pressure Index (ALPI) up to 2022; they were originally only available to 2015. The Aleutian Low was mentioned in several talks at the 2024 State of the Pacific Ocean meeting, motivating us to update the values here. -- added helper function `a()`, shorthand for `as.data.frame()`, see - examples in `?a`. +- added zooplankton biomass anomalies for the Strait of Georgia, with + a new vignette: + [zooplankton.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/zooplankton.html). -- added Pacific Herring stock assessment results, for spawning stock - biomass and age-2 recruitment for each of the five major stock - assessment regions; see the +- updated the estimates of Pacific Hake abundance and recruitment with + values from the 2024 assessment (retaining the original estimates + from the 2023 assessments for reproducibility); see the [populations.html](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/populations.html) vignette. @@ -342,9 +342,9 @@ If you use `pacea` in your work then please cite it as (NOTE this has been updated since the original release): Edwards A.M., Tai T.C., Watson J., Peña M.A., Hilborn A., Hannah C.G., -Rooper C.N., and Flynn K.L. (2024). pacea: An R package of Pacific -ecosystem information to help facilitate an ecosystem approach to -fisheries management. , +Rooper C.N., Flynn K.L., and Oldford, G.L. (2024). pacea: An R package +of Pacific ecosystem information to help facilitate an ecosystem +approach to fisheries management. , You may wish to add the date you installed it (using diff --git a/vignettes/bccm_full.Rmd b/vignettes/bccm_full.Rmd new file mode 100644 index 00000000..5622ef26 --- /dev/null +++ b/vignettes/bccm_full.Rmd @@ -0,0 +1,203 @@ +--- +title: "BCCM Results Over Full Domain" +author: "Andrew Edwards and Travis Tai" +output: rmarkdown::html_vignette +vignette: > + %\VignetteIndexEntry{BCCM Results Over Full Domain} + %\VignetteEngine{knitr::rmarkdown} + %\VignetteEncoding{UTF-8} +date: "Last rendered on `r format(Sys.time(), '%d %B, %Y')`" +--- + +```{r run, echo = FALSE, eval = FALSE} +rmarkdown::render("bccm_full.Rmd") +# to build, or click the knit button in RStudio +``` + +```{r setup, include = FALSE} +knitr::opts_chunk$set( + collapse = TRUE, + comment = "#", + cache = TRUE, + cache_path = "bccm-full-cache/", + fig.path = "bccm-full-figs-cache/", + fig.width = 7.7, + fig.height = 7 +) +``` + +# Introduction + +The British Columbia Continental Margin (BCCM) model is a +physical biogeochemical oceanographic model, implemented using the Regional Ocean Modeling +System (ROMS; Peña et al., 2019). Results restricted to Canada's Exclusive Economic Zone and mapped +to a 2 km x 2 km grid onshore and 6 x 6 km grid offshore are +discussed in the [BCCM Results vignette](bccm.html), which should be looked at +to understand more about the model. The restrictions and +varying of the gridsize were done to reduce file sizes. + +Due to several requests from users we have now also mapped the BCCM results for its full domain (extending +north and south into US waters) onto a 2 km x 2km grid. These requests included: + +- [Issue #49](https://github.com/pbs-assess/pacea/issues/49): extend the BCCM + results into US waters +- [Issue #58](https://github.com/pbs-assess/pacea/issues/58): add the results from the +HOTSSea physical oceanographic model for the Salish Sea (a region not covered by +the BCCM results, ideally on a grid that overlaps as that used for the BCCM +- [Issue #48](https://github.com/pbs-assess/pacea/issues/48) and [Issue + #62](https://github.com/pbs-assess/pacea/issues/62): have an easily exported grid that covers a larger domain +- [Issue #60](https://github.com/pbs-assess/pacea/issues/60): projecting the Optimally Interpolated Sea Surface Temperature values onto the same grid as the +BCCM results. + +These requests are now mostly fulfilled, and include the BCCM results on the +full domain. The results are in the same format as those for the restricted +domain described in the [BCCM Results vignette](bccm.html) vignette. The +file sizes are much larger (each variable is about 120 Mb rather than about 30 +Mb), but only need to be downloaded once. + +We have kept consistent terminology and functionality as for the restricted BCCM +results. Basically: +- variable names are appended with `_full` +- plotting and analysis functions should still work on the `_full` variables. + +## Available variables + +```{r packages} +library(pacea) +library(dplyr) +library(sf) +library(ggplot2) +``` + +For the restricted domain, the available variables are given in the data object +`bccm_data`. For the full domain, the variables are therefore given in +`bccm_data_full`: +```{r bccm_data-Full} +bccm_data_full +``` +The `bccm_data` object gives the same `r nrow(bccm_data_full)` names, but without +the `_full`. + +## Downloading bccm full results + +The 22 BCCM full model results are stored on Zenodo at https://zenodo.org/records/14031460. Each can be downloaded +individually (if you only want certain variables) as described below. It is +easiest to just +just simply download them all to your computer in one go, using +```{r download, eval = FALSE} +bccm_all_variables_full() +``` +This places them into a cache directory on your local machine, given by +by `paste0(pacea_cache(), "/bccm_full")`. It only took about 10 minutes to +download them all (the code uses parallel cores on Windows) on a home network, +but could be longer on a work network. You can check progress in your local +cache directory, where files should gradually appear. +Any files that are already +present in your cache directory are not re-downloaded. See +`?bccm_all_variables_full` if you have problems. + +### Using the bccm full results + +As an example, let's look at the estimates of primary production, calling the +object `pp` locally: +```{r pp} +pp <- bccm_primaryproduction_full() +``` +Note the `()`. The `bccm_primaryproduction_full()` function assigns the +output to our designated variable simply named `pp`. + +If you have not already previously downloaded the relevant results it +will first download them into your cache folder (i.e. it will get just the +specified model results, rather than all of them as in the +`bccm_all_variables_full()` described above). If you have previously downloaded +the results the function will simply load them in from your cached folder. + +View the data help for more information +(e.g. `?bccm_primaryproduction_full`); similar help functions all point to a +common help file for all `bccm_full` objects. + +So, what does the object look like? +```{r pp1} +pp +head(pp[, 1:5]) # note that the geometry column is included when selecting columns from + # an `sf` object. +``` + +The object is in wide format, with each column representing a unique year-month +combination, and is a 'simple features' (`sf`) R object, and so contains a +`geometry` column. The data also have various attributes, such as the units for the +data values, and some extra ones to automate some plotting. (This is useful but +not essential for users to know). +```{r} +names(attributes(pp)) +attributes(pp)$units +class(pp) +``` +## Visualising the bccm full results + +We give some examples here, and then refer users to the [BCCM Results +vignette](bccm.html) since the examples shown there should work for the `_full` +results. (Note we have not tested every potential idea you might have, but by +keeping the structure of the outputs the same, our custom plotting and analysis +functions should work). + + +### Plotting with `plot()` + +Results can be plotted using the `plot()` function (that we have +customised). The default settings are to plot results for April, 2018. However, +users can specify any time period(s) available in the results. Examples are: +```{r plot1} +plot(pp) +``` + +To see the estimated primary production for each month of 2018 +```{r, ppplot, fig.width = 16, fig.height = 12} +plot(pp, months = 1:12) +``` + +This shows the production ramping up through the spring. + +### Climatologies and anomalies + +Let's have a quick look at anomalies, say for oxygen at the bottom of the water +column, adapting the examples from the [BCCM +vignette](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/bccm.html). Again, +see that vignette for extra details. + +So let's ask: how do the anomalies of bottom oxygen for +April and September in 2010 and 2018, look compared to a climatology (for each +month) from 1993 to 2010 (the full range of years currently available). + +We can easily load the model results and calculate the anomalies for a +climatology (see `?calc_clim` to obtain the climatology also): +```{r, anomalies} +bottom_oxygen <- bccm_bottom_oxygen_full() +anom <- calc_anom(bottom_oxygen, + clim_years = 1993:2010, + time_period_return = c("Apr", "Sep"), + years_return = c(2010, 2018)) +anom +``` +```{r, anomaliesplot, fig.width = 8, fig.height = 8} +plot(anom, + months.plot = c("Apr", "Sep"), + years.plot = c(2010, 2018), + eez = FALSE) +``` + +So some areas are relatively oxygen rich (green) in these months compared to the +same areas from 1993 to 2010, whereas others are lower in oxygen (red). This +varies spatially and by month. Along the coast there looks to be more oxygen +than normal in April 2010, generally a bit less in September 2010, and even less +in April and September 2018. + +See the [BCCM +vignette](http://htmlpreview.github.io/?https://github.com/pbs-assess/pacea/blob/main/vignettes/bccm.html) +for further example calculations, which hopefully stimulate your own ideas. + +## Reference + +Peña, M.A., Fine, I. and Callendar, W. 2019. Interannual variability in primary +production and shelf-offshore transport of nutrients along the northeast Pacific +Ocean margin. Deep-Sea Research II, doi:10.1016/j.dsr2.2019.104637. diff --git a/vignettes/hotssea.Rmd b/vignettes/hotssea.Rmd index a2f240de..df2cf05e 100644 --- a/vignettes/hotssea.Rmd +++ b/vignettes/hotssea.Rmd @@ -118,7 +118,7 @@ Similar calculations are done for the `_mean` (the mean daily mean), `_max` (the daily means), and `_std` (the standard deviation of the daily means), replacing the word 'minimum' in the fourth bullet point. And the same calculations are done for salinity. -So, `hotssea_avg0to30m_temperature_min` is the depth-integrated mean(over the +So, `hotssea_avg0to30m_temperature_min` is the depth-integrated mean (over the top 30 m) of each modelled depths' minimum (over the month) daily mean temperature. And `hotssea_bottom_salinity_sd` is the the bottom cell's standard deviation (over the month) of daily mean @@ -168,7 +168,7 @@ daily mean temperature: hot <- hotssea_avg0to30m_temperature_max() ``` Note the `()`. The `hotssea_avg0to30m_temperature_max()` function assigns the -output to our designated variable simply names `hot`. +output to our designated variable simply named `hot`. If you have not already previously downloaded the results it will first download them into your cache folder (i.e. it will get just the