The goal of angstroms was to provide easy access to Regional Ocean Modeling System (ROMS) but now it provides easy access and control over any complex gridded output available to the raster package in R.
The key features are:
- treat gridded data as existing index space
- handle coordinate arrays independently
- avoid remodelling data whenever possible
- re-map data into the grid space for extractions
- treat the grid as a mesh (which it always is).
This approach aligns with the plotting and interpretation tools in the quadmesh package, particularly the mesh_plot() and quadmesh() functions.
What angstroms is now
angstroms first reached CRAN in 2017. The five ideas above have since been taken up, more generally, by other packages and writing:
- index space first, with coordinates handled separately, is the stance of the book Regular in what?: a grid is regular, rectilinear or curvilinear only in a frame, and “no frame” (index space) is a frame;
- re-mapping external data into grid space is what controlledburn does for polygons, lines and points: sparse runs of whole cells plus exact coverage fractions, indexed by the grid’s own row and column;
- the grid as a mesh is quadmesh.
So angstroms is not being rewritten in place. It is the ROMS front end: it keeps what is specific to ROMS, and over time hands the general jobs to packages that each do one thing.
What stays in angstroms:
- the staggered C-grid locations (rho, u, v, psi) and their coordinate arrays (
romscoords()); - terrain-following S-coordinate depths (
romshcoords()); - the grid angle, to turn grid-relative u and v into east and north (
romsangle(),romsrotate()); - coupling to Atlantis box models through rbgm (
create_transport()).
What moves out, one small release at a time:
| Job | Now | Later |
|---|---|---|
| read slices | raster and ncdf4 | tidync or vapour |
| index arithmetic | raster extents in index space | vaster |
| coordinate transformation | reproj | reproj (already) |
| geometry into grid space | nearest grid node (romsmap()) |
controlledburn, with edges cut into short pieces before mapping |
| grid as mesh, plotting | quadmesh | quadmesh |
romsmap() moves only the vertices of a geometry, each to its nearest grid node. That is fine for a quick look, as its help page says, but a long edge on a curvilinear grid can then cross cells it never touches. Cutting edges into short pieces first, and mapping to fractional column and row rather than the nearest node, is the fix that the controlledburn route will bring.
The scope is ROMS for now. Other model grids with the same structure may follow.
Installation
Install the released version from CRAN with:
install.packages("angstroms")You can install the development version of angstroms from github with:
# install.packages("remotes")
remotes::install_github("AustralianAntarcticDivision/angstroms")angstroms - R for gridded model data (including ROMS)
Angstroms aims to make working with gridded output as easy as possible in R. Rather than re-map explicitly the complex curvilinear grid in ROMS or ACCESS (or many others), the approach simplifies this by:
- maintaining the internal index of a grid as the default georeferencing
- converting external data (maps, transects, points, etc.) into the native internal index space of ROMS
- providing tools to read arbitrary slices from the grids (either 2D or 3D) as Raster objects
- providing tools to recover the original full coordinates as needed
In combination these allow extraction and query from the complex grids output very easily.
The ability to deal with time series across multiple files is still in development, though can be used simply now with standard loops.
Contributing
Here are some notes on lessons learned, all is work in progress.
- calls to raster/brick/stack should be wrapped by an appropriate
romsdata(), to ensure thatncdf = TRUEis consistent, and to reduce the amount of extent-setting and orienting code - romsdata() should have a convention to accept a raw matrix/array, see first point
- use
set_indextenton a brick/raster to ensure it is in index-extent, again to reduce code duplications -
ncdf=TRUEis required, because on some systems we might fall back to rgdal which won’t support NetCDF properly (can be done with SDS strings or VRT but that’s a hassle) - use of raster (and so ncdf4) package could be better done more directly with RNetCDF / tidync
- RNetCDF loses speed on ncdf4 for some metadata harvesting, but is otherwise a better choice right now (Nov 2017) especially with Thredds support for Win64 now on CRAN
- orientation is an open question, but at the moment it looks like X-increasing, Y-decreasing, Z-decreasing, T-increasing - though it’s not that simple - and for no good reason other than train-wreck-convention
- romsdata() generally needs a bit more thought, should it take a raw array or only a source string, do 2d/3d variants make sense, how to orient specific slice conventions (roms_xt etc.)
Conduct
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
