Package 'FjordLight'

Title: Available Light Within the Water Column and on the Seafloor of Arctic Fjords
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.
Authors: Bernard Gentili [aut], Jean-Pierre Gattuso [aut] , Robert W. Schlegel [aut, cre]
Maintainer: Robert W. Schlegel <[email protected]>
License: MIT + file LICENSE
Version: 1.0.1
Built: 2024-11-17 05:10:53 UTC
Source: https://github.com/face-it-project/fjordlight

Help Index

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)

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)

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 fl_ListFjords for the list of possible choices.
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 fl_ListFjords for the list of possible choices.
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, FALSE, will prevent this function from loading the monthly bottom PAR values. Instead it will load all global, annual, and monthly climatology data. Set TS = TRUE to load all data, but note that these may be extremely large.
verbose

TRUE or FALSE (default) to provide a more verbose output of the data loading process.

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 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 fl_LoadFjord.
mode

Determines the format to be loaded into the R environment. The default "raster" will load the data as a raster format. "3col" will load the data as a data.frame with three columns.

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 fl_LoadFjord.
what

The default value "o" will load all "ocean" data, meaning it will filter out any land pixels. The other options are: "c" filters out only coastal bathymetry data (depth of 200 m to 0 m), "s" filters out only shallow bathymetry data (depth of 50 m to 0 m), and "l" loads only the land data. One may combine "o", "c", or "s", with "l" (e.g. "ol") to load both sea and land data.
mode

Determines the format of the bathymetry data loaded into the R environment. The default "raster" will load the data as a raster format. The other option "df" will load the data as a data.frame with three columns.
PLOT

Boolean argument (default = FALSE) that tells the function if the user would like the loaded bathymetry and/or elevation data to be plotted or not. NB: this argument will only run if the user chooses mode = "raster".

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 fl_LoadFjord.
optics

The PAR variable that the user would like to load. The option are: "PARbottom" (default) to load the bottom PAR values, "PAR0m" surface PAR, or "Kpar" for the extinction coefficient.
period

Here the user determines which time period of data should be loaded. To load the total average values (default) use "Global". One may chose instead to load the "Yearly" or "Monthly" values. Note that monthly values here represent the climatological average for the month, not one month in a given year. If the user would like one specific month of data (only available for bottom PAR), they should use flget_PARbottomMonthlyTS.
month

The monthly climatology to extract. Accepts an integer value from 3 to 10. This argument is ignored if period = "Yearly".
year

The yearly average to extract. Currently accepts an integer value from 2003 to 2022. This argument is ignored if period = "Monthly".
mode

Determines the format of the data loaded into the R environment. The default "raster" will load the data as a raster format. The other option "df" will load the data as a data.frame with three columns.
PLOT

Boolean argument (default = FALSE) that tells the function if the user would like the loaded data to be plotted or not.

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 optics and either month or year, depending on the users choice.

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 fl_LoadFjord.

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))

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 fl_LoadFjord. NB: when loading the data one must set the argument fl_LoadFjord(..., TS = TRUE). See examples below.
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 NULL will be passed to the function, telling it to load all available months of data (i.e. 3:10). This is used in combination with year to determine which monthly data to extract.
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 NULL will be passed to the function, telling it to load all available years of data (i.e. currently 2003:2022). This is used in combination with month to determine which monthly data to extract.
mode

Determines the format of the data loaded into the R environment. The default "raster" will load the data as a raster format. The other option "df" will load the data as a data.frame with three columns.
PLOT

Boolean argument (default = FALSE) that tells the function if the user would like the loaded data to be plotted or not.

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 fl_LoadFjord. NB: when loading the data one must set the argument fl_LoadFjord(..., TS = TRUE). See examples below.
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 NULL will be passed to the function, telling it to load all available months of data (i.e. 3:10). This is used in combination with year to determine which monthly data to extract.
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 NULL will be passed to the function, telling it to load all available years of data (i.e. currently 2003:2022). This is used in combination with month to determine which monthly data to extract.
mode

Determines the format of the data loaded into the R environment. The default "raster" will load the data as a raster format. The other option "df" will load the data as a data.frame with three columns.
PLOT

Boolean argument (default = FALSE) that tells the function if the user would like the loaded data to be plotted or not.

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 fl_LoadFjord.
type

Whether the p function should show values for the coastal zone (< 200 m deep), or the shallow zone (< 50 m deep).
period

Here the user determines which time period of data should be loaded. To load the total average values (default) use "Global". One may chose instead to load the "Yearly" or "Monthly" values. Note that monthly values here represent the climatological average for the month, not one month in a given year. If the user would like one specific month of data (only available for bottom PAR), they should use flget_PARbottomMonthlyTS.
month

The monthly climatology to extract. Accepts an integer value from 3 to 10. This argument is ignored if period = "Yearly".
year

The yearly average to extract. Currently accepts an integer value from 2003 to 2022. This argument is ignored if period = "Monthly".
mode

Determines the basic process that this function performs. The default mode = "function" will allow the user to create a function that they can then use themselves to determine p curves using their own input (see examples). Or to access the underlying p function data directly set mode = "df".
PLOT

Boolean argument (default = FALSE) that tells the function if the user would like the loaded data to be plotted or not.
add

Boolean (i.e. TRUE/FALSE) to tell the function to add the p function plot to an existing plot. See examples below.
...

Additional arguments that may be passed to flplot_Pfunction, which will implement them using base R plotting functionality.

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 optics and either global, year, or month, depending on which period was indicated. These values show the percent of the fjord (filtered for pixels with a depth of 200 m or shallower) that received at least the amount of irradiance indicated in the irradianceLevel column.

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))