fvcom.tbx
is an R
toolbox for the exploration of unstructured,
prism-based hydrodynamic model outputs (i.e. from the Finite Coastal
Ocean Volume Model, FVCOM) in R
. The package has been designed
specifically for the West Coast of Scotland Coastal Modelling System
(WeStCOMS), which implements FVCOM. Package development has been
motivated by the requirements of ecological research, and the need to
link hydrodynamic model outputs with ecological analyses implemented in
R
. To this end, the package includes functions which facilitate the
following operations:
R
;This README file outlines the steps that are required to set up FVCOM
outputs for integration with R
via fvcom.tbx
and some of the main
functionality of the package. For further details, please consult the
vignette and the reference manual.
You can install the development version of fvcom.tbx
from
GitHub with:
devtools::install_github("edwardlavender/fvcom.tbx", build_vignette = TRUE)
If you build the vignette, you can view this with
vignette("fvcom.tbx", package = "fvcom.tbx")
.
Hydrodynamic model outputs are typically stored as MATLAB® or Network
Common Data Form (NetCDF) files. Each file contains information on the
model structure (e.g., the model mesh) and all of the model predictions
for a specific day. Within each file, model predictions are stored as 2-
or 3-dimensional arrays. To integrate these files with R
, via
fvcom.tbx
, follow the workflow detailed below:
The first step is to acquire FVCOM files. FVCOM files can be obtained
from source or from a remote server. For file acquisition from a remote
server, fvcom.tbx
includes the thredds_download()
function which is
designed to download WeStCOMS files from the SAMS thredds server.
(Alternatively, thredds_extract()
can be used to extract specific
predictions from model files on the thredds server.)
From any FVCOM file, it is necessary to obtain the following:
dat_trinodes
, is available in this
package.dat_nodexy
, is
available in this package.dat_h
is available in this package.For each FVCOM file, we also need to extract and save the environmental arrays of interest (see below).
fvcom.tbx
is step up to work with environmental arrays rather than the
full FVCOM files. Hence, it is necessary to define a set of directories
into which, for each FVCOM file, environmental arrays can be extracted
and saved. The following directory names are recommended:
fvcom.tbx
);To create a directory system in which to store outputs, fvcom.tbx
provides the create_wcdirs()
function.
With an appropriate directory system in place, the next step is to
extract environmental arrays from FVCOM files into this directory
system. If you have already obtained the full FVCOM files* (e.g., via
thredds_download()
), this is a possible workflow:
define_dates2load()
can be used to do this.*An alternative workflow, rather than obtaining the full FVCOM files
and then extracting environmental arrays, is to directly extract and
only download specific environmental arrays of interest, which may be
faster. fvcom.tbx
may include functionality via thredds_url()
and
thredds_extract()
functions to implement this approach in future.
For environmental arrays, fvcom.tbx
assumes the following conventions:
R
. The
vignette provides a sample MATLAB® script in which full FVCOM files
are loaded into MATLAB®, environmental arrays extracted and then saved
into a pre-defined directory system as .mat files. Accordingly, in
fvcom.tbx
, the default function to load files into R
is
function(con) R.matlab::readMat(con)$data
, but this can be changed
by the user as necessary. In any given directory (e.g., ‘/temp’), all
of the environmental arrays should be of the same file type.date_name()
is used to flick between dates and WeStCOMS
file names.Armed with the necessary standard FVCOM objects and environmental
arrays, we can now proceed to implement functions in fvcom.tbx
to
build model mesh(es), compute new fields, extract model predictions,
explore environmental conditions and validate model predictions with
observations.
Several functions are designed to facilitate building and working with unstructured meshes. These include:
build_mesh()
- build an unstructured mesh (around nodes or elements)
from node coordinates and connections as a SpatialPolygonsDataFrame
;find_cells()
- find the mesh cells (for nodes or elements) which
enclose inputted coordinates;find_xy()
- find the coordinates of mesh cells (for nodes or
elements);The compute_field_from_fvcom()
is designed for the flexible
computation of new fields using existing hydrodynamic model outputs.
This is supported by helper functions for commonly desirable fields such
as:
calc_thermocline()
- calculate thermocline strength from temperature
predictions;calc_direction()
- calculate wind/current direction from $u$ and $v$
component vectors;calc_speed()
- calculate wind/current speed from $u$ and $v$
component vectors;There are also some functions for the computation of specific new fields from scratch (such as sun angle) in cases where it is helpful to express variables which are not resolved by the hydrodynamic model across the same mesh (for instance, to investigate the extent of spatiotemporal variation over the same spatial domain). These include the following:
compute_sun_angle()
- compute sun angle as a new field;compute_field_photoperiod()
- compute photoperiod as a new field;Some functions are designed to facilitate the extraction of model predictions from source files. These include the following:
exclude_corrupt()
and exclude_unavailable()
- exclude corrupt and
unavailable files from file names vector;expand_by_hour()
- expand a dataframe with times at non-integer
hours to include surrounding integer hours for extraction;extract()
- extract model predictions for multiple
dates/hours/layers/mesh cells;depth_from_known()
- calculate the depth of Sigma layers using known
parameters;depth_from_unknown()
- compute the depth of Sigma layers using
unknown (i.e., extracted) parameters and/or assign the depths of Sigma
layers to a dataframe using nearest neighbour or bilinear
interpolation;shrink_by_hour
, interp_btw_hours()
, interp_btw_depths()
and
interp_layer()
- interpolate predictions between hours or layers and
fractional layer numbers;Some functions are designed to facilitate exploration of environmental conditions through space and/or time. These include the following:
summarise_field_2d()
- compute statistical summaries of
environmental conditions across a Sigma layer (through time for a
given file, if applicable);plot_field_2d()
- visualise environmental conditions across a Sigma
layer through space at a specified point in time;explore_field_2d()
- implement summarise_field_2d()
and
plot_field_2d()
across multiple timepoints and/or model files;prettyGraphics
package, including pretty_scape_3d()
and vis_scape_3d()
which
produce interactive, 3-dimensional visualisations of
landscapes/seascapes and/or environmental conditions; for large
rasters, crop_aggr_utm()
helps reduce raster dimensions for these
functions;validate()
facilitates the comparison of observed conditions
(including those from animal movement datasets) with predicted
conditions to evaluate model skill.
Future developments to fvcom.tbx
may include developing the following
functionality:
fvcom.tbx
is a new package at an early stage of evolution. Please
report issues, comments or suggestions!
WeStCOMS was developed at the Scottish Association for Marine Sciences by Dmitry Aleynik.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.