Version: | 1.0.1 |
Date: | 2024-08-19 |
Title: | Available Light Within the Water Column and on the Seafloor of Arctic Fjords |
Type: | Package |
Description: | Satellite data collected between 2003 and 2022, in conjunction with gridded bathymetric data (50-150 m resolution), are used to estimate the irradiance reaching the bottom of a series of representative EU Arctic fjords. An Earth System Science Data (ESSD) manuscript, Schlegel et al. (2024), provides a detailed explanation of the methodology. |
Maintainer: | Robert W. Schlegel <robwschlegel@gmail.com> |
Depends: | R (≥ 3.3.0) |
Imports: | ncdf4, raster, curl |
License: | MIT + file LICENSE |
Encoding: | UTF-8 |
URL: | https://face-it-project.github.io/FjordLight/index.html, https://doi.pangaea.de/10.1594/PANGAEA.910898, https://doi.pangaea.de/10.1594/PANGAEA.965460 |
RoxygenNote: | 7.3.2 |
NeedsCompilation: | no |
Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
Config/testthat/edition: | 3 |
VignetteBuilder: | knitr |
Packaged: | 2024-08-19 06:06:58 UTC; robert |
Author: | Bernard Gentili [aut],
Jean-Pierre Gattuso
|
Repository: | CRAN |
Date/Publication: | 2024-08-19 07:30:13 UTC |
Create a colour palette from blues to reds.
Description
This function will create a lovely, evenly spaced colour palette.
Usage
cs_BuYlRd(n)
Arguments
n |
The number of colours of blue to red to return. |
Value
A character vector of hexadecimal values.
Author(s)
Bernard Gentili
Examples
cs_BuYlRd(10)
Create a colour palette of blues.
Description
This function will create a lovely, evenly spaced colour palette.
Usage
cs_blue(n)
Arguments
n |
The number of colours of blue to return. |
Value
A character vector of hexadecimal values.
Author(s)
Bernard Gentili
Examples
cs_blue(10)
Create a colour palette from blues to yellows.
Description
This function will create a lovely, evenly spaced colour palette.
Usage
cs_blye(n)
Arguments
n |
The number of colours of blue to yellow to return. |
Value
A character vector of hexadecimal values.
Author(s)
Bernard Gentili
Examples
cs_blye(10)
Download fjord PAR data as NetCDF files.
Description
This functions queries the FTP server where the NetCDF files are stored. It will
retrieve the one file that matches the name provided to it via the fjord
argument. Note that these files can be multiple gigabytes in size.
Usage
fl_DownloadFjord(fjord, layer = "PAR_B", dirdata = NULL)
Arguments
fjord |
Expects a character vector for one of the 8 available fjords.
See |
layer |
The layer of data the user wants to download. The default "PAR_B" will download monthly bottom PAR data, "K_PAR" will download monthly values for the light extinction coefficient (i.e. K_PAR) in the water column, "ClimSD" will download the standard deviations for the monthly climatologies, and "YearlySD" will download the standard deviations for the yearly climatologies. Note that if monthly K_PAR data are chosen, the file will be saved as e.g. "kong_MonthlyKpar.nc". "ClimSD" and "YearlySD" data will also have this character string appended to the file name. Whereas PAR_B data will be saved simply as e.g. "kong.nc". NB: Only the "PAR_B" data contain the full list of metadata variables. |
dirdata |
The directory where the user would like to download the data. |
Value
The downloaded NetCDF file contains the following variables:
bathymetry |
depth [m] |
land |
elevation [m] |
area |
PixelArea_km2 [m] |
AreaOfCoastalZone |
Surface of Sea floor with a depth of between 0 and 200 meters [km2] |
etc...
Author(s)
Bernard Gentili and Robert Schlegel
Examples
# Choose a fjord
fjord_code <- "kong"
# Download it
# NB: One should provide a permanent directory when downloading a file.
fl_DownloadFjord(fjord_code, dirdata = tempdir())
Simply lists the names of fjords with available data.
Description
Run this to determine which character vectors to use when downloading data
via fl_DownloadFjord
, or a range of other uses within FjordLight
.
Usage
fl_ListFjords()
Value
A list of currently 7 different character vectors representing a range of fjords in the EU Arctic.
Author(s)
Bernard Gentili
Examples
fl_ListFjords()
Load fjord PAR data from a NetCDF file downloaded by FjordLight
.
Description
This functions will load into the R environment the data within one NetCDF
file that has been downloaded via fl_DownloadFjord
.
Usage
fl_LoadFjord(
fjord,
layer = "PAR_B",
dirdata = NULL,
TS = FALSE,
verbose = FALSE
)
Arguments
fjord |
Expects a character vector for one of the 8 available fjords.
See |
layer |
The layer of data the user wants to load. The default "PAR_B" will load monthly bottom PAR data. The other options, "K_PAR" will load monthly values for the light extinction coefficient (i.e. K_PAR) in the water column, "ClimSD" will load the standard deviation values for the monthly climatologies, and "YearlySD" will load the standard deviation values for the yearly climatologies. Note that only the PAR_B files and do not contain all global values and metadata. The other files are in supplement to the PAR_B files. |
dirdata |
The directory where the user would like to load the data from. |
TS |
The default, |
verbose |
|
Value
Data are loaded in as a complex list format. Containing most of the data fields
described in the documentation for fl_DownloadFjord
.
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Choose fjord
fjord_code <- "test"
# Load global, annual, and monthly climatologies
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# Load ALL data
fjorddata_full <- fl_LoadFjord(fjord_code,
dirdata = system.file("extdata", package = "FjordLight"), TS = TRUE)
Create a colour palette for bathymetry plots.
Description
This function will create a lovely, evenly spaced colour palette designed for use with bathymetry plots.
Usage
fl_topocolorscale(v)
Arguments
v |
Expects a single negative numeric value. This should be the maximum depth of the bathymetry. |
Value
A list containing two vectors. First the numeric breaks (brks
) that will
be shown as different isobath colours. Second the colours (colors
) that will be shown. The
colours are given as hexadecimal values.
Author(s)
Bernard Gentili
Examples
fl_topocolorscale(-200)
Extract monthly K_PAR data from a NetCDF file downloaded by FjordLight
.
Description
This functions will extract the monthly K_PAR data stored within a K_PAR
NetCDF file downloaded via fl_DownloadFjord
. Note that these data are
very large. If one would prefer to work with the smaller annual or monthly climatology
values, instead use flget_climatology
. There are options for how the user
would like to subset the data, which data format the data should be extracted to,
and if the user would like to plot the data in the process.
Usage
flget_KPARMonthlyTS(
fjord,
month = NULL,
year = NULL,
mode = "raster",
PLOT = FALSE
)
Arguments
fjord |
Expects the object loaded via |
month |
The monthly values to extract. Accepts one or many integer values from 3 to 10.
If no values are provided, the default value of |
year |
The years of data to extract. Currently accepts one or many integer values from 2003 to 2022.
If no values are provided, the default value of |
mode |
Determines the format of the data loaded into the R environment.
The default |
PLOT |
Boolean argument (default = |
Value
Depending on which arguments the user chooses, this function will return the
chosen monthly K_PAR data as a RasterStack
(mode = "raster"
)
or data.frame (mode = "df"
). The data.frame will contain the following columns:
longitude |
degree decimals |
latitude |
degree decimals |
PARbottom |
mol photons m-2 d-1 |
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Load ALL data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code,
dirdata = system.file("extdata", package = "FjordLight"),
TS = TRUE, layer = "K_PAR")
# Load a small subset as a data.frame
mts_single <- flget_KPARMonthlyTS(fjorddata, month = 6, year = 2016, mode = "df", PLOT = FALSE)
# Years 2003 to 2004 - months July to August
# NB: This may be too large for smaller laptops
mts_many <- flget_KPARMonthlyTS(fjorddata, month = 7:8, year = 2003:2004, PLOT = FALSE)
# May also plot the data
mts_plot <- flget_KPARMonthlyTS(fjorddata, month = 6:9, year = 2010, PLOT = TRUE)
# For more examples: https://face-it-project.github.io/FjordLight/articles/fl_example.html
Extract monthly bottom PAR data from a NetCDF file downloaded by FjordLight
.
Description
This functions will extract the monthly bottom PAR data stored within a
NetCDF file downloaded via fl_DownloadFjord
. Note that these data are
very large. If one would prefer to work with the smaller annual or monthly climatology
values, instead use flget_climatology
. There are options for how the user
would like to subset the data, which data format the data should be extracted to,
and if the user would like to plot the data in the process.
Usage
flget_PARbottomMonthlyTS(
fjord,
month = NULL,
year = NULL,
mode = "raster",
PLOT = FALSE
)
Arguments
fjord |
Expects the object loaded via |
month |
The monthly values to extract. Accepts one or many integer values from 3 to 10.
If no values are provided, the default value of |
year |
The years of data to extract. Currently accepts one or many integer values from 2003 to 2022.
If no values are provided, the default value of |
mode |
Determines the format of the data loaded into the R environment.
The default |
PLOT |
Boolean argument (default = |
Value
Depending on which arguments the user chooses, this function will return the
chosen monthly bottom PAR data as a RasterStack
(mode = "raster"
)
or data.frame (mode = "df"
). The data.frame will contain the following columns:
longitude |
degree decimals |
latitude |
degree decimals |
PARbottom |
mol photons m-2 d-1 |
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Load ALL data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code,
dirdata = system.file("extdata", package = "FjordLight"), TS = TRUE)
# Load a small subset as a data.frame
mts_single <- flget_PARbottomMonthlyTS(fjorddata, month = 6, year = 2016, mode = "df", PLOT = FALSE)
# Years 2003 to 2004 - months July to August
# NB: This may be too large for smaller laptops
mts_many <- flget_PARbottomMonthlyTS(fjorddata, month = 7:8, year = 2003:2004, PLOT = FALSE)
# May also plot the data
mts_plot <- flget_PARbottomMonthlyTS(fjorddata, month = 6:9, year = 2010, PLOT = TRUE)
# For more examples: https://face-it-project.github.io/FjordLight/articles/fl_example.html
Extract p function data from a NetCDF file downloaded by FjordLight
.
Description
This functions will conveniently extract the p function data stored within a
NetCDF file downloaded via fl_DownloadFjord
.
There are options for how the user would like to subset the data, which data format the
data should be extracted to, and if the user would like to plot the data in the process.
Usage
flget_Pfunction(
fjord,
type = "coastal",
period = "Global",
month = NULL,
year = NULL,
mode = "function",
PLOT = FALSE,
add = FALSE,
...
)
Arguments
fjord |
Expects the object loaded via |
type |
Whether the p function should show values for the |
period |
Here the user determines which time period of data should be loaded. To load
the total average values (default) use |
month |
The monthly climatology to extract. Accepts an integer value from 3 to 10.
This argument is ignored if |
year |
The yearly average to extract. Currently accepts an integer value from 2003 to 2022.
This argument is ignored if |
mode |
Determines the basic process that this function performs. The default
|
PLOT |
Boolean argument (default = |
add |
Boolean (i.e. |
... |
Additional arguments that may be passed to |
Value
Depending on which arguments the user chooses for mode
, a function will
be returned (see examples). Or a two column data.frame:
irradianceLevel |
A threshold value [mol photons m-2 d-1] |
optics_global|year|month |
The column name is determined by the arguments passed to |
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Load data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# Create a function
fG <- flget_Pfunction(fjorddata, "shallow", "Global")
# Then use it with specific PAR thresholds
irradiance_levels <- c(0.1, 1, 10)
fG(irradiance_levels)
# As a 2 column data.frame
f2012 <- flget_Pfunction(fjorddata, "shallow", "Yearly", year = 2012, mode = "df", PLOT = TRUE)
str(f2012)
# Plot a P-function
fGlob <- flget_Pfunction(fjorddata, "coastal", "Global", PLOT = TRUE, lty = 1, col = 1, lwd = 2,
Main = paste(fjord_code, "P-functions"), ylim = c(0, 50))
Extract pixel surface area data from a NetCDF file downloaded by FjordLight
.
Description
This functions will conveniently extract the pixel surface area data stored within a
NetCDF file downloaded via fl_DownloadFjord
. The user may choose to
load the data in either raster or data.frame formats. It is useful to combine these
data with others, e.g. bathymetry data loaded via fl_DownloadFjord
Usage
flget_area(fjord, mode = "raster")
Arguments
fjord |
Expects the object loaded via |
mode |
Determines the format to be loaded into the R environment.
The default |
Value
Depending on which arguments the user chooses, this function will return the
surface area data as a RasterLayer
(mode = "raster"
) or
data.frame (mode = "df"
). The data.frame will contain the following columns:
longitude |
degree decimals |
latitude |
degree decimals |
PixelArea_km2 |
the surface area of the grid cell [km^2] |
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Load data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# Load area data
area <- flget_area(fjorddata, mode = "df")
Extract and/or plot bathymetry data from a NetCDF file downloaded by FjordLight
.
Description
This functions will conveniently extract the bathymetry data stored within a
NetCDF file downloaded via fl_DownloadFjord
. There are options
for how the user would like to subset the data, which data format the data
should be extracted to, and if the user would like to plot the data in the process.
Usage
flget_bathymetry(fjord, what = "o", mode = "raster", PLOT = FALSE)
Arguments
fjord |
Expects the object loaded via |
what |
The default value |
mode |
Determines the format of the bathymetry data loaded into the R environment.
The default |
PLOT |
Boolean argument (default = |
Value
Depending on which arguments the user chooses, this function will return the
filtered bathymetry data as a RasterLayer
(mode = "raster"
) or
data.frame (mode = "df"
). The data.frame will contain the following columns:
longitude |
degree decimals |
latitude |
degree decimals |
depth |
metres |
Note that the depth column will contain both elevation (positive) and depth (negative) values.
Author(s)
Bernard Gentili & Robert Schlegel
Examples
# Load data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# Shallow data (what = "s"; s for shallow) as a data.frame
shallow_df <- flget_bathymetry(fjorddata, what = "s", mode = "df")
# Plot all ocean and land data
full_bathy <- flget_bathymetry(fjorddata, what = "ol", mode = "raster", PLOT = TRUE)
# Plot only land data
land_only <- flget_bathymetry(fjorddata, what = "l", mode = "raster", PLOT =TRUE)
# For more examples see: https://face-it-project.github.io/FjordLight/articles/fl_example.html
Extract climatology data from a NetCDF file downloaded by FjordLight
.
Description
This functions will conveniently extract the climatology data stored within a
NetCDF file downloaded via fl_DownloadFjord
. To extract the monthly
bottom PAR data instead one must use flget_PARbottomMonthlyTS
.
There are options for how the user would like to subset the data, which data format the
data should be extracted to, and if the user would like to plot the data in the process.
Usage
flget_climatology(
fjord,
optics = "PARbottom",
period = "Global",
month = NULL,
year = NULL,
mode = "raster",
PLOT = FALSE
)
Arguments
fjord |
Expects the object loaded via |
optics |
The PAR variable that the user would like to load. The option are:
|
period |
Here the user determines which time period of data should be loaded. To load
the total average values (default) use |
month |
The monthly climatology to extract. Accepts an integer value from 3 to 10.
This argument is ignored if |
year |
The yearly average to extract. Currently accepts an integer value from 2003 to 2022.
This argument is ignored if |
mode |
Determines the format of the data loaded into the R environment.
The default |
PLOT |
Boolean argument (default = |
Value
Depending on which arguments the user chooses, this function will return the
chosen, global, annual, or monthly climatology data as a RasterLayer
(mode = "raster"
) or data.frame (mode = "df"
).
The data.frame will contain the following columns:
longitude |
degree decimals |
latitude |
degree decimals |
optics_month|year |
The column name is determined by the arguments for
|
Author(s)
Bernard Gentili
Examples
# Load data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# PAR0m and PARbottom for July
P07 <- flget_climatology(fjorddata, "PAR0m", "Clim", month = 7, PLOT = TRUE)
Pb7 <- flget_climatology(fjorddata, "PARbottom", "Clim", month = 7, PLOT = TRUE)
# PARbottom Global
PbG <- flget_climatology(fjorddata, "PARbottom", "Global", PLOT = TRUE)
# PAR0m and kdpar for year 2012 as 3 columns data frame
P02012 <- flget_climatology(fjorddata, "PAR0m", "Yearly", year = 2012, mode = "df")
k2012 <- flget_climatology(fjorddata, "Kpar", "Yearly", year = 2012, mode = "df")
# For more examples see: https://face-it-project.github.io/FjordLight/articles/fl_example.html
Extract geo-parameters from a NetCDF file downloaded by FjordLight
.
Description
Given a NetCDF file downloaded via fl_DownloadFjord
,
this function extracts the central longitude and latitude for that site,
as well as the surface are in km^2 for the shallow zone (< 50 m deep) and coastal
zone (< 200 m deep).
Usage
flget_geoparameters(fjord)
Arguments
fjord |
Expects the object loaded via |
Value
A named vector containing the following items:
site_average_longitude |
The central longitude of the fjord [degree decimals] |
site_average_latitude |
The central latitude of the fjord [degree decimals] |
AreaOfCoastalZone |
The surface area of the grid cells with a depth of < 200 m [km^2] |
AreaOfShallowZone |
The surface area of the grid cells with a depth of < 50 m [km^2] |
Author(s)
Bernard Gentili
Examples
# Load data
fjord_code <- "test"
fjorddata <- fl_LoadFjord(fjord_code, dirdata = system.file("extdata", package = "FjordLight"))
# Load geo-parameters
geo_params <- flget_geoparameters(fjorddata)
# Convert to a data.frame if desired
geo_params_df <- t(as.data.frame(geo_params))
Plot monthly K_PAR data extracted from NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_KPARMonthlyTS
that plots data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_KPARMonthlyTS(r)
Arguments
r |
The monthly K_PAR data in a raster stack format. |
Value
A base R plot of the monthly K_PAR data will be provided.
Author(s)
Bernard Gentili
Plot monthly bottom PAR data extracted from NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_PARbottomMonthlyTS
that plots data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_PARbottomMonthlyTS(r)
Arguments
r |
The monthly bottom PAR data in a raster stack format. |
Value
A base R plot of the monthly bottom PAR data will be provided.
Author(s)
Bernard Gentili
Plot p function data extracted from NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_Pfunction
that plots data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_Pfunction(irrLev, g, period, month, year, Main = NULL, add = add, ...)
Arguments
irrLev |
The chosen irradiance thresholds (x-axis). |
g |
The percent of the fjord (y-axis) with a depth of 200 m or shallower receiving an irradiance values (e.g. surface PAR) at or above the corresponding threshold (x-axis). |
period |
The period being displayed. I.e. yearly or monthly. |
month |
If monthly climatology data, which month(s) is being displayed. |
year |
If yearly data, which year(s) is being displayed |
Main |
The title of the plot. The default |
add |
Boolean value of |
... |
Any other desired base R plotting functionality. |
Value
A base R plot of the yearly or monthly p function data will be provided.
Author(s)
Bernard Gentili
Plot bathymetry data found within NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_bathymetry
that plots the bathymetry data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_bathymetry(r, l = NULL, name)
Arguments
r |
The bathymetry data in a raster format. |
l |
The land data in the same format. |
name |
The name of the chosen fjord. |
Value
A base R plot of the bathymetric data will be provided.
Author(s)
Bernard Gentili
Plot annual/monthly climatology data extracted from NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_climatology
that plots data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_climatology(r, l, name, optics, period, month, year)
Arguments
r |
The yearly/monthly climatology data in a raster format. |
l |
The land data in the same format. |
name |
The name of the chosen fjord. |
optics |
The name of the PAR variable being displayed. |
period |
The period being displayed. I.e. yearly or monthly. |
month |
If monthly climatology data, which month(s) is being displayed. |
year |
If yearly data, which year(s) is being displayed |
Value
A base R plot of the yearly or monthly climatology data will be provided.
Author(s)
Bernard Gentili
Plot land data found within NetCDF files downloaded by FjordLight
.
Description
Internal function used by flget_bathymetry
that plots the land data
contained within the NetCDF files downloaded via fl_DownloadFjord
.
Usage
flplot_land(r, name)
Arguments
r |
The land data in a raster format. |
name |
The name of the chosen fjord. |
Value
A base R plot of the land data will be provided.
Author(s)
Bernard Gentili