vignette done

R/tsibble.R

@@ -36,8 +36,9 @@ fill_gaps.temporal_cubble_df <- function(.data, ..., .full = FALSE,
  index <- index_var(.data)
  coords <- coords(.data)
  spatial <- spatial(.data)
- .data <- as_tsibble(.data, key = key , index = index)
- res <- fill_gaps(.data, ...)
+ data <- as_tsibble(.data, key = key , index = index)
+ res <- fill_gaps(data, ...)
+ if (!inherits(.data, "tbl_ts")) class(res) <- setdiff(class(res), "tbl_ts")
 
  new_temporal_cubble(
  res, key = key, index = index, coords = coords(.data), spatial = spatial)

README.Rmd

@@ -1,5 +1,6 @@
 ---
 output: github_document
+bibliography: '`r system.file("reference.bib", package = "cubble")`'
 ---
 
 <!-- README.md is generated from README.Rmd. Please edit that file -->
@@ -12,6 +13,7 @@ knitr::opts_chunk$set(
  out.width = "100%",
  message = FALSE
 )
+library(cubble)
 ```
 
 # cubble <a href='https://huizezhang-sherry.github.io/cubble/'><img src='man/figures/logo.svg' align="right" height="138.5" /></a>
@@ -20,7 +22,42 @@ knitr::opts_chunk$set(
 [![R-CMD-check](https://github.com/huizezhang-sherry/cubble/workflows/R-CMD-check/badge.svg)](https://github.com/huizezhang-sherry/cubble/actions)
 <!-- badges: end -->
 
-Cubble provides a data structure to manipulate spatio-temporal vector data in two forms: nested form (spatial cubble) and long form (temporal cubble). The nested cubble shows spatial variables as columns and nests temporal variables in a `ts` column. The long cubble presents temporal variables as columns and stores spatial variables as an attribute. The two forms can be switched back and forth for manipulation on the spatial and temporal dimension of the data. 
+The term spatio-temporal data can incorporate various spatial and temporal characteristics and different data may require different data structures for wrangling and analysis. The spatio-temporal data that cubble addresses are those collected at unique fixed locations, allowing for irregularity in the temporal dimension, such as the weather station data. This corresponds to the full space-time and sparse space-time layouts in the spacetime paper [@spacetime]: 
+
+```{r layout, echo = FALSE, fig.height=3, fig.retina=3}
+library(tidyverse)
+library(patchwork)
+p1 <- tibble(
+ id = 1:12,
+ x = rep(1:4, each = 3),
+ y = rep(1:3, 4)
+) %>% 
+ ggplot(aes(x = as.factor(x) ,y = as.factor(y))) + 
+ geom_point() + 
+ geom_text(aes(y = y - 0.2, label = id)) + 
+ theme_bw() + 
+ theme(aspect.ratio = 1) + 
+ scale_x_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
+ scale_y_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
+ labs(x = "Time points", y = "Spatial features", title = "STF: full grid layout") 
+
+p2 <- tibble(
+ id = 1:7,
+ x = c(1, 1, 1, 2, 2, 3, 4),
+ y = c(1, 2, 3, 2, 3, 1, 2),
+ label = c("1[1,1]", "2[1,2]", "3[1,3]", "4[2,2]", "5[3,2]", "6[1,3]", "7[2,4]")
+) %>% 
+ ggplot(aes(x = as.factor(x) ,y = as.factor(y))) + 
+ geom_point() + 
+ geom_text(aes(y = y - 0.2, label = label)) + 
+ theme_bw() + 
+ theme(aspect.ratio = 1) + 
+ scale_x_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
+ scale_y_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
+ labs(x = "Time points", y = "Spatial features", title = "STS: sparse grid layout") 
+
+p1 | p2
+```
 
 ## Installation
 
@@ -36,36 +73,33 @@ And the development version from [GitHub](https://github.com/) with:
 # install.packages("remotes")
 remotes::install_github("huizezhang-sherry/cubble")
 ```
-## Create a cubble 
 
-`as_cubble()` creates a cubble in the nested form by supplying the spatial identifier, `key`, temporal identifier, `index`, and the spatial coordinates that defines the site, `coords`.
+## How cubble organises spatio-temporal data
 
-```{r}
-library(cubble)
-library(dplyr)
-nested <- climate_flat %>% as_cubble(key = id, index = date, coords = c(long, lat))
-nested
-```
+Cubble organises spatio-temporal data in two structures: In a nested cubble (spatial cubble), spatial variables are organised as columns and temporal variables are nested within a specialised `ts` column: 
 
-Check the vignette [1. The cubble class](articles/cb1class.html) for more details on the class design. 
+```{r echo = FALSE}
+climate_mel
+```
 
-You can also create a cubble object by supplying the spatial and temporal component separately in `make_cubble()`. This allows you to use an `sf` object for the spatial component and a `tsibble` object for the temporal component. The `sf` and `tsibble` class will be carried over to the cubble object: 
+In a long cubble (temporal cubble), the temporal variables are expanded into the long form, while the spatial variables are stored as a data attribute: 
 
-```{r}
-cb_nested <- make_cubble(spatial = stations_sf, temporal = meteo_ts)
-class(cb_nested)
-class(cb_nested$ts[[1]])
+```{r echo = FALSE}
+climate_mel %>% face_temporal()
 ```
 
-Check the vignette [2. Creation and coercion](articles/cb2create.html) for more on `make_cubble()` and coerce from other objects: netcdf, [stars objects](https://r-spatial.github.io/stars/), and [sftime objects](https://r-spatial.github.io/sftime/).
-
-## Pivot between the spatial and temporal cubble
+The two forms can be pivoted back and forth with the pair of verb: `face_spatial()` and `face_temporal()`.
 
-The pair of verbs, `face_temporal()` and `face_spatial()`, pivot the cubble object between the spatial and temporal sides. 
+```{r echo = FALSE, out.width="80%", fig.align='center'}
+knitr::include_graphics("man/figures/cubble-operations.png")
+```
 
-Check [Getting started](articles/cubble.html) and the vignette [3. Making a glyph map](articles/cb3glyph.html) for operating on the spatial and temporal cubble to make spatio-temporal visualisation.
 
+## Roadmap
 
-## Misc
+ * To learn more about the cubble class: [1. The cubble class](articles/cb1class.html)
+ * To create a cubble or coerce an existing R object into a cubble: [2. Creation and coercion](articles/cb2create.html)
+ * To incoporate sf or tsibble in a cubble: [3. Compatibility with tsibble and sf](articles/cb3tsibblesf.html)
+ * To create glyph map, match multiple data sources, and create interactive graphics with cubble: [4. Making a glyph map](articles/cb4glyph.html), [5. Matching different data sources](articles/cb5match.html), and [6. Interactive graphics](articles/cb6interactive.html)
 
-Cubble stands for "cubical tibble" as in a *tibble* object for multivariate spatio-temporal data *cube*.
+## Reference

README.md

@@ -8,13 +8,15 @@
 [![R-CMD-check](https://github.com/huizezhang-sherry/cubble/workflows/R-CMD-check/badge.svg)](https://github.com/huizezhang-sherry/cubble/actions)
 <!-- badges: end -->
 
-Cubble provides a data structure to manipulate spatio-temporal vector
-data in two forms: nested form (spatial cubble) and long form (temporal
-cubble). The nested cubble shows spatial variables as columns and nests
-temporal variables in a `ts` column. The long cubble presents temporal
-variables as columns and stores spatial variables as an attribute. The
-two forms can be switched back and forth for manipulation on the spatial
-and temporal dimension of the data.
+The term spatio-temporal data can incorporate various spatial and
+temporal characteristics and different data may require different data
+structures for wrangling and analysis. The spatio-temporal data that
+cubble addresses are those collected at unique fixed locations, allowing
+for irregularity in the temporal dimension, such as the weather station
+data. This corresponds to the full space-time and sparse space-time
+layouts in the spacetime paper (Pebesma 2012):
+
+<img src="man/figures/README-layout-1.png" width="100%" />
 
 ## Installation
 
@@ -32,60 +34,70 @@ And the development version from [GitHub](https://github.com/) with:
 remotes::install_github("huizezhang-sherry/cubble")
 ```
 
-## Create a cubble
-
-`as_cubble()` creates a cubble in the nested form by supplying the
-spatial identifier, `key`, temporal identifier, `index`, and the spatial
-coordinates that defines the site, `coords`.
-
-``` r
-library(cubble)
-library(dplyr)
-nested <- climate_flat %>% as_cubble(key = id, index = date, coords = c(long, lat))
-nested
-#> # cubble: key: id [3], index: date, nested form
-#> # spatial: [144.8321, -37.98, 145.0964, -37.6655], Missing CRS!
-#> # temporal: date [date], prcp [dbl], tmax [dbl], tmin [dbl]
-#> id long lat elev name wmo_id ts 
-#> <chr> <dbl> <dbl> <dbl> <chr> <dbl> <list> 
-#> 1 ASN00086038 145. -37.7 78.4 essendon airport 95866 <tibble [10 × 4]>
-#> 2 ASN00086077 145. -38.0 12.1 moorabbin airport 94870 <tibble [10 × 4]>
-#> 3 ASN00086282 145. -37.7 113. melbourne airport 94866 <tibble [10 × 4]>
-```
-
-Check the vignette [1. The cubble class](articles/cb1class.html) for
-more details on the class design.
-
-You can also create a cubble object by supplying the spatial and
-temporal component separately in `make_cubble()`. This allows you to use
-an `sf` object for the spatial component and a `tsibble` object for the
-temporal component. The `sf` and `tsibble` class will be carried over to
-the cubble object:
-
-``` r
-cb_nested <- make_cubble(spatial = stations_sf, temporal = meteo_ts)
-class(cb_nested)
-#> [1] "spatial_cubble_df" "cubble_df" "sf" 
-#> [4] "tbl_df" "tbl" "data.frame"
-class(cb_nested$ts[[1]])
-#> [1] "tbl_ts" "tbl_df" "tbl" "data.frame"
-```
-
-Check the vignette [2. Creation and coercion](articles/cb2create.html)
-for more on `make_cubble()` and coerce from other objects: netcdf,
-[stars objects](https://r-spatial.github.io/stars/), and [sftime
-objects](https://r-spatial.github.io/sftime/).
-
-## Pivot between the spatial and temporal cubble
-
-The pair of verbs, `face_temporal()` and `face_spatial()`, pivot the
-cubble object between the spatial and temporal sides.
-
-Check [Getting started](articles/cubble.html) and the vignette [3.
-Making a glyph map](articles/cb3glyph.html) for operating on the spatial
-and temporal cubble to make spatio-temporal visualisation.
-
-## Misc
-
-Cubble stands for “cubical tibble” as in a *tibble* object for
-multivariate spatio-temporal data *cube*.
+## How cubble organises spatio-temporal data
+
+Cubble organises spatio-temporal data in two structures: In a nested
+cubble, spatial variables are organised as columns and temporal
+variables are nested within a specialised `ts` column:
+
+ #> # cubble: key: id [3], index: date, nested form
+ #> # spatial: [144.8321, -37.98, 145.0964, -37.6655], Missing CRS!
+ #> # temporal: date [date], prcp [dbl], tmax [dbl], tmin [dbl]
+ #> id long lat elev name wmo_id ts 
+ #> <chr> <dbl> <dbl> <dbl> <chr> <dbl> <list> 
+ #> 1 ASN00086038 145. -37.7 78.4 essendon airport 95866 <tibble [10 × 4]>
+ #> 2 ASN00086077 145. -38.0 12.1 moorabbin airport 94870 <tibble [10 × 4]>
+ #> 3 ASN00086282 145. -37.7 113. melbourne airport 94866 <tibble [10 × 4]>
+
+In a long cubble, the temporal variables are expanded into the long
+form, while the spatial variables are stored as a data attribute:
+
+ #> # cubble: key: id [3], index: date, long form
+ #> # temporal: 2020-01-01 -- 2020-01-10 [1D], no gaps
+ #> # spatial: long [dbl], lat [dbl], elev [dbl], name [chr], wmo_id [dbl]
+ #> id date prcp tmax tmin
+ #> <chr> <date> <dbl> <dbl> <dbl>
+ #> 1 ASN00086038 2020-01-01 0 26.8 11 
+ #> 2 ASN00086038 2020-01-02 0 26.3 12.2
+ #> 3 ASN00086038 2020-01-03 0 34.5 12.7
+ #> 4 ASN00086038 2020-01-04 0 29.3 18.8
+ #> 5 ASN00086038 2020-01-05 18 16.1 12.5
+ #> 6 ASN00086038 2020-01-06 104 17.5 11.1
+ #> 7 ASN00086038 2020-01-07 14 20.7 12.1
+ #> 8 ASN00086038 2020-01-08 0 26.4 16.4
+ #> 9 ASN00086038 2020-01-09 0 33.1 17.4
+ #> 10 ASN00086038 2020-01-10 0 34 19.6
+ #> # ℹ 20 more rows
+
+The two forms can be pivoted back and forth with the pair of verb:
+`face_spatial()` and `face_temporal()`.
+
+<img src="man/figures/cubble-operations.png" width="80%" style="display: block; margin: auto;" />
+
+## Roadmap
+
+- To learn more about the cubble class: [1. The cubble
+ class](articles/cb1class.html)
+- To create a cubble or coerce an existing R object into a cubble: [2.
+ Creation and coercion](articles/cb2create.html)
+- To incoporate sf or tsibble in a cubble: [3. Compatibility with
+ tsibble and sf](articles/cb3tsibblesf.html)
+- To create glyph map, match multiple data sources, and create
+ interactive graphics with cubble: [4. Making a glyph
+ map](articles/cb4glyph.html), [5. Matching different data
+ sources](articles/cb5match.html), and [6. Interactive
+ graphics](articles/cb6interactive.html)
+
+## Reference
+
+<div id="refs" class="references csl-bib-body hanging-indent">
+
+<div id="ref-spacetime" class="csl-entry">
+
+Pebesma, Edzer. 2012. “<span class="nocase">spacetime</span>:
+Spatio-Temporal Data in R.” *Journal of Statistical Software* 51 (7):
+1–30. <https://www.jstatsoft.org/v51/i07/>.
+
+</div>
+
+</div>

vignettes/cb1class.Rmd

@@ -1,7 +1,6 @@
 ---
 title: "1. The cubble class"
 output: rmarkdown::html_vignette
-bibliography: '`r system.file("reference.bib", package = "cubble")`'
 vignette: >
  %\VignetteIndexEntry{class}
  %\VignetteEngine{knitr::rmarkdown}
@@ -27,41 +26,6 @@ library(tsibble)
 library(patchwork)
 ```
 
-The term spatio-temporal data can incorporate various spatial and temporal characteristics and different data may require different data structures for wrangling and analysis: climate weather stations records data at fixed point location but may suffer from potential temporal data quality issue such as missing data for certain days. GPS data tracks unique point locations at different timestamps and can be organised as trajectories; satellite imagery captures snapshots of landscapes at selected times and is commonly structured as rasters. The spatio-temporal data that cubble addresses are those collected at unique fixed locations, allowing for irregularity in the temporal dimension, such as the weather station data. This corresponds to the full space-time and sparse space-time layouts in the spacetime paper [@spacetime]: 
-
-```{r echo = FALSE}
-p1 <- tibble(
- id = 1:12,
- x = rep(1:4, each = 3),
- y = rep(1:3, 4)
-) %>% 
- ggplot(aes(x = as.factor(x) ,y = as.factor(y))) + 
- geom_point() + 
- geom_text(aes(y = y - 0.2, label = id)) + 
- theme_bw() + 
- theme(aspect.ratio = 1) + 
- scale_x_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
- scale_y_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
- labs(x = "Time points", y = "Spatial features", title = "STF: full grid layout") 
-
-p2 <- tibble(
- id = 1:7,
- x = c(1, 1, 1, 2, 2, 3, 4),
- y = c(1, 2, 3, 2, 3, 1, 2),
- label = c("1[1,1]", "2[1,2]", "3[1,3]", "4[2,2]", "5[3,2]", "6[1,3]", "7[2,4]")
-) %>% 
- ggplot(aes(x = as.factor(x) ,y = as.factor(y))) + 
- geom_point() + 
- geom_text(aes(y = y - 0.2, label = label)) + 
- theme_bw() + 
- theme(aspect.ratio = 1) + 
- scale_x_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
- scale_y_discrete(labels = c("1st", "2nd", "3rd", "4th")) + 
- labs(x = "Time points", y = "Spatial features", title = "STS: sparse grid layout") 
-
-p1 | p2
-```
-
 # The cubble object
 
 The cubble class is an S3 class built on tibble that allows the spatio-temporal data to be wrnagled in two forms: a nested/spatial form and a long/temporal form. It consists of two subclasses: 
@@ -123,5 +87,3 @@ The following shortcut functions are available to extract components from the at
  - `index_var()`: the index attribute as a string, i.e. `"date"`,
  - `coords()`: a character vector of length two representing the coordinate pairs, i.e. `"long" "lat"`, and
  - `spatial()`: the tibble object for the spatial variables.
-
-# Reference

vignettes/cb2create.Rmd

@@ -18,7 +18,7 @@ knitr::opts_chunk$set(
 library(cubble)
 ```
 
-This article demonstrates how to create a cubble from various types of data. From the README page, you have already seen examples of constructing a cubble from a tibble. Here we provide additional examples of creating a cubble from: 
+This article demonstrates how to create a cubble from various types of data. We will create a cubble from: 
 
  - separate spatial and temporal tables
  - a `tibble` object

vignettes/cb3tsibblesf.Rmd

@@ -72,11 +72,11 @@ sf_nested %>% sf::st_transform(crs = "EPSG:3857")
 The counterpart to promote the spatial component in an existing cubble to be an sf object is `make_spatial_sf()`:
 
 ```{r echo = TRUE}
-sf_nested <- make_cubble(
+sf_nested2 <- make_cubble(
  stations, meteo, 
  key = id, index = date, coords = c(long, lat)) %>% 
  make_spatial_sf() 
-all.equal(sf_nested, sf_nested)
+all.equal(sf_nested2, sf_nested)
 ```
 
 # Reference