7.5 Setting the time dimension manually

For this section, we will use PRISM precipitation data for U.S. for January, 2009.

(
ppt_m1_y09_stars <- read_stars("Data/PRISM/PRISM_ppt_y2009_m1.tif") 
)

stars object with 3 dimensions and 1 attribute
attribute(s), summary of first 1e+05 cells:
                        Min. 1st Qu. Median     Mean 3rd Qu.   Max.  NA's
PRISM_ppt_y2009_m1.tif     0       0  0.436 3.543222  3.4925 56.208 60401
dimension(s):
     from   to   offset      delta refsys point
x       1 1405 -125.021  0.0416667  NAD83 FALSE
y       1  621  49.9375 -0.0416667  NAD83 FALSE
band    1   31       NA         NA     NA    NA
                                                                          values
x                                                                           NULL
y                                                                           NULL
band PRISM_ppt_stable_4kmD2_20090101_bil,...,PRISM_ppt_stable_4kmD2_20090131_bil
     x/y
x    [x]
y    [y]
band

As you can see, when you read a GeoTIFF file, the third dimension will always be called band because GeoTIFF format does not support dimension values for the third dimension.⁸⁴

You can use st_set_dimension() to set the third dimension (called band) as the time dimension using Date object. This can be convenient when you would like to filter the data by date using filter() as we will see later.

For ppt_m1_y09_stars, precipitation is observed on a daily basis from January 1, 2009 to January 31, 2009, where the band value of x corresponds to January x, 2009. So, we can first create a vector of dates as follows (If you are not familiar with Dates and the lubridate pacakge, this is a good resource to learn them.):

#--- starting date ---#
start_date <- ymd("2009-01-01")

#--- ending date ---#
end_date <- ymd("2009-01-31")

#--- sequence of dates  ---#
dates_ls_m1 <- seq(start_date, end_date, "days")

We can then use st_set_dimensions() to change the third dimension to the dimension of date.

#--- syntax (NOT RUN) ---#  
st_set_dimensions(stars object, dimension, values = dimension values, names = name of the dimension)

(
ppt_m1_y09_stars <- st_set_dimensions(ppt_m1_y09_stars, 3, values = dates_ls_m1, names = "date")
)

stars object with 3 dimensions and 1 attribute
attribute(s), summary of first 1e+05 cells:
                        Min. 1st Qu. Median     Mean 3rd Qu.   Max.  NA's
PRISM_ppt_y2009_m1.tif     0       0  0.436 3.543222  3.4925 56.208 60401
dimension(s):
     from   to     offset      delta refsys point values x/y
x       1 1405   -125.021  0.0416667  NAD83 FALSE   NULL [x]
y       1  621    49.9375 -0.0416667  NAD83 FALSE   NULL [y]
date    1   31 2009-01-01     1 days   Date    NA   NULL

As you can see, the third dimension has become date. The value of offset for the date dimension has become 2009-01-01 meaning the starting date value is now 2009-01-01. Further, the value of delta is now 1 days, so date dimension of x corresponds to 2009-01-01 + x - 1 = 2009-01-x.

Note that the date dimension does not have to be regularly spaced. For example, you may have satellite images available for your area with a 5-day interval sometimes and a 6-day interval other times. This is perfectly fine. As an illustration, I will create a wrong sequence of dates for this data with a 2-day gap in the middle and assign them to the date dimension to see what happens.

#--- 2009-01-23 removed and 2009-02-01 added ---#
(
dates_ls_wrong <- c(seq(start_date, end_date, "days")[-23], ymd("2009-02-01")) 
)

 [1] "2009-01-01" "2009-01-02" "2009-01-03" "2009-01-04" "2009-01-05"
 [6] "2009-01-06" "2009-01-07" "2009-01-08" "2009-01-09" "2009-01-10"
[11] "2009-01-11" "2009-01-12" "2009-01-13" "2009-01-14" "2009-01-15"
[16] "2009-01-16" "2009-01-17" "2009-01-18" "2009-01-19" "2009-01-20"
[21] "2009-01-21" "2009-01-22" "2009-01-24" "2009-01-25" "2009-01-26"
[26] "2009-01-27" "2009-01-28" "2009-01-29" "2009-01-30" "2009-01-31"
[31] "2009-02-01"

Now assign these date values to ppt_m1_y09_stars:

#--- set date values ---#
(
ppt_m1_y09_stars_wrong <- st_set_dimensions(ppt_m1_y09_stars, 3, values = dates_ls_wrong, names = "date")
)

stars object with 3 dimensions and 1 attribute
attribute(s), summary of first 1e+05 cells:
                        Min. 1st Qu. Median     Mean 3rd Qu.   Max.  NA's
PRISM_ppt_y2009_m1.tif     0       0  0.436 3.543222  3.4925 56.208 60401
dimension(s):
     from   to   offset      delta refsys point                    values x/y
x       1 1405 -125.021  0.0416667  NAD83 FALSE                      NULL [x]
y       1  621  49.9375 -0.0416667  NAD83 FALSE                      NULL [y]
date    1   31       NA         NA   Date    NA 2009-01-01,...,2009-02-01

Since the step between the date values is no longer \(1\) day for the entire sequence, the value of delta is now NA. However, notice that the value of date is no longer NULL. Since the date is not regular, you can not represent date using three values (from, to, and delta) any more, and date values for each observation have to be stored now.

Finally, note that just applying st_set_dimensions() to a stars object does not change the dimension of the stars object (just like setNames() as we discussed above).

ppt_m1_y09_stars

stars object with 3 dimensions and 1 attribute
attribute(s), summary of first 1e+05 cells:
                        Min. 1st Qu. Median     Mean 3rd Qu.   Max.  NA's
PRISM_ppt_y2009_m1.tif     0       0  0.436 3.543222  3.4925 56.208 60401
dimension(s):
     from   to     offset      delta refsys point values x/y
x       1 1405   -125.021  0.0416667  NAD83 FALSE   NULL [x]
y       1  621    49.9375 -0.0416667  NAD83 FALSE   NULL [y]
date    1   31 2009-01-01     1 days   Date    NA   NULL

As you can see, the date dimension has not been altered. You need to assign the results of st_set_dimensions() to a stars object to see the changes in the dimension reflected just like we did above with the right date values.

In Chapter 7.1, we read an rds, which is a stars object with dimension name set manually by me.↩︎