4. stars data model

Edzer Pebesma

For a better version of the stars vignettes see https://r-spatial.github.io/stars/articles/

This vignette explains the data model of stars objects, illustrated using artificial and real datasets.

Stars objects

stars objects consist of

A dimensions object is a named list of dimension elements, each describing the semantics a dimension of the data arrays (space, time, type etc). In addition to that, a dimensions object has an attribute called raster of class stars_raster, which is a named list with three elements:

The affine and curvilinear values are only relevant in case of raster data, indicated by dimensions to have non-NA values.

A dimension object describes a single dimension; it is a list with named elements

Clearly, offset and delta only apply to regularly discretized dimensions, and are NA if this is not the case. from and to will usually be 1 and the dimension size, but from may be larger than 1 in case a regular sub-grid got cut out or was cropped. Rectilinear and curvilinear grids need grid values in values; this can be irregularly spaced coordinate values, or coordinate intervals of irregular width, or spatial geometries encoded in an sfc vector (“list-column”), or a matrix with grid cell centre values (longitude or latitude) for curvilinear grids.

Grid type

Regular grids

With a very simple file created from a \(4 \times 5\) matrix

we see that

When we plot this object, using the image method for stars objects,

we see that \((0,0)\) is the origin of the grid (grid corner), and \(1\) the coordinate value increase from one index (row, col) to the next. It means that consecutive matrix columns represent grid lines, going from south to north. Grids defined this way are regular: grid cell size is constant everywhere.

Many actual grid datasets have y coordinates (grid rows) going from North to South (top to bottom); this is realised with a negative value for delta. We see that the grid origing \((0,0)\) did not change:

An example is the GeoTIFF carried in the package, which, as probably all data sources read through GDAL, has a negative delta for the y-coordinate:

Raster attributes, rotated and sheared grids

Dimension tables of stars objects carry a raster attribute:

which is a list that holds

These fields are needed at this level, because they describe properties of the array at a higher level than individual dimensions do: a pair of dimensions forms a raster, both affine and curvilinear describe how x and y as a pair are derived from grid indexes (see below) when this cannot be done on a per-dimension basis.

With two affine parameters \(a_1\) and \(a_2\), \(x\) and \(y\) coordinates are derived from (1-based) grid indexes \(i\) and \(j\), grid offset values \(o_x\) and \(o_y\), and grid cell sizes \(d_x\) and \(d_y\) by

\[x = o_x + (i-1) d_x + (j-1) a_1\]

\[y = o_y + (i-1) a_2 + (j-1) d_y\] Clearly, when \(a_1=a_2=0\), \(x\) and \(y\) are entirely derived from their respective index, offset and cellsize.

Note that for integer indexes, the coordinates are that of the starting edge of a grid cell; to get the grid cell center of the top left grid cell (in case of a negative \(d_y\)), use \(i=1.5\) and \(j=1.5\).

We can rotate grids by setting \(a_1\) and \(a_2\) to a non-zero value:

The rotation angle, in degrees, is

Sheared grids are obtained when the two rotation coefficients, \(a_1\) and \(a_2\), are unequal:

Now, the y-axis and x-axis have different rotation in degrees of respectively

Rectilinear grids

Rectilinear grids have orthogonal axes, but do not have congruent (equally sized and shaped) cells: each axis has its own irregular subdivision.

We can define a rectilinear grid by specifying the cell boundaries, meaning for every dimension we specify one more value than the dimension size:

x = c(0, 0.5, 1, 2, 4, 5)  # 6 numbers: boundaries!
y = c(0.3, 0.5, 1, 2, 2.2) # 5 numbers: boundaries!
(r = st_as_stars(list(m = m), dimensions = st_dimensions(x = x, y = y)))
## stars object with 2 dimensions and 1 attribute
## attribute(s):
##    Min. 1st Qu. Median Mean 3rd Qu. Max.