diff --git a/DESCRIPTION b/DESCRIPTION index cd3ec3b..c4a2cdf 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: rwlts Type: Package Title: Web Land Trajectory Service R Client -Version: 0.6.0 +Version: 0.8.0 Authors@R: c(person("Brazil Data Cube Team", email = "brazildatacube@inpe.br", @@ -15,14 +15,14 @@ Imports: httr, tibble, magrittr, - dplyr, + dplyr +Suggests: ggplot2, - ggalluvial + ggalluvial, + covr, + vcr, + testthat License: MIT + file LICENSE Encoding: UTF-8 LazyData: true -RoxygenNote: 7.1.1 -Suggests: - covr, - vcr, - testthat +RoxygenNote: 7.1.2 diff --git a/NAMESPACE b/NAMESPACE index 73b150c..d5682a1 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,21 +1,13 @@ # Generated by roxygen2: do not edit by hand +S3method(plot,alluvial) +S3method(plot,wlts) export("%>%") export(describe_collection) export(get_trajectory) export(list_collections) -export(plot_sankey) importFrom(dplyr,arrange) importFrom(dplyr,group_by) importFrom(dplyr,mutate) importFrom(dplyr,ungroup) -importFrom(ggalluvial,geom_flow) -importFrom(ggalluvial,geom_stratum) -importFrom(ggplot2,aes_string) -importFrom(ggplot2,facet_wrap) -importFrom(ggplot2,geom_text) -importFrom(ggplot2,ggplot) -importFrom(ggplot2,scale_y_continuous) -importFrom(ggplot2,stat) -importFrom(ggplot2,theme) importFrom(magrittr,"%>%") diff --git a/NEWS.md b/NEWS.md index c9c72d6..5b7502e 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,10 @@ +# Version 0.8.0 (2021-10-04) + +- Change `sankey` to `alluvial` +- Collection can be provide as character vector +- Implement plot using s3 class +- Change version + # Version 0.6.0 (2021-09-03) - Add Sankey Plot diff --git a/R/plot.R b/R/plot.R index dd05720..0171f3c 100644 --- a/R/plot.R +++ b/R/plot.R @@ -1,43 +1,62 @@ -#' @title Sankey Plot +#' @title Plots for rwlts package #' -#' @description Visualization method based on the sankey graph. In which the -#' changes between each class are presented on the time axis. +#' @name plot.wlts #' -#' @param wtls_tibble a \code{tibble} object from class \code{wlts}. -#' @param show_count_transition a \code{logical} parameter, if true, is added -#' the number of points on each bar. The default value is FALSE. +#' @description A set of visualization methods for trajectories extracted in +#' rwlts package. +#' +#' @param x a \code{tibble} object from class \code{wlts}. +#' @param type a \code{character} with the type of plot. +#' Nowadays, only the "alluvial" plot is supported. By default is "alluvial". +#' @param ... additional functions #' #' @examples -#' \donttest{ +#' \dontrun{ #' wlts_bdc <- "https://brazildatacube.dpi.inpe.br/wlts/" #' #' wlts_tibble <- get_trajectory( #' URL = wlts_bdc, #' latitude = c(-12, -11), #' longitude = c(-54, -55), -#' collections = "mapbiomas5_amazonia", +#' collections = "mapbiomas_amazonia-v5", #' start_date = "2015-07-01", #' end_date = "2017-07-01", #' config = httr::add_headers("x-api-key" = "BDC-KEY")) #' -#' -#' plot_sankey(wlts_tibble) +#' plot(wlts_tibble) #' } #' #' @return a \code{gg} object from ggplot2 package. #' #' @export -plot_sankey <- function(wtls_tibble, show_count_transition = FALSE) { +plot.wlts <- function(x, ..., type = "alluvial") { - if (!inherits(wtls_tibble, "wlts")) - stop(paste("The given object does not correspond to a time trajectory.", - "Please use the `get_trajectory` function."), .call = FALSE) - - if (is.null(wtls_tibble$result)) + if (is.null(x$result)) stop(paste("The result provided is empty, please check your query."), .call = FALSE) - traj_data_sankey <- wtls_tibble$result %>% + if (!requireNamespace("ggplot2", quietly = TRUE)) { + stop(paste("ggplot2 required for this function to work.", + "Please install it."), call. = FALSE) + } + + # dispatch for S3 methods + class(x) <- c(type, class(x)) + plot(x, ...) +} + +#' @rdname plot.wlts +#' @param show_count a \code{logical} parameter, if true, is added +#' the number of points on each bar. The default value is FALSE. +#' @export +plot.alluvial <- function(x, ..., show_count = FALSE) { + + if (!requireNamespace("ggalluvial", quietly = TRUE)) { + stop(paste("ggalluvial required for this function to work.", + "Please install it."), call. = FALSE) + } + + traj_data_sankey <- x$result %>% dplyr::mutate(date = as.factor(as.numeric(date)), class = as.factor(class)) %>% dplyr::arrange(date) %>% @@ -58,11 +77,11 @@ plot_sankey <- function(wtls_tibble, show_count_transition = FALSE) { ggplot2::scale_y_continuous(expand = c(0, 0)) + ggplot2::theme(legend.position = "bottom") - if (show_count_transition) + if (show_count) g <- g + ggplot2::geom_text(stat = "stratum", ggplot2::aes_string(label = "n_points")) - if (length(unique(wtls_tibble$result$collection)) > 1) + if (length(unique(x$result$collection)) > 1) g <- g + ggplot2::facet_wrap(~ traj_data_sankey$collection) return(g) diff --git a/R/rwlts-package.R b/R/rwlts-package.R index 7b1df66..23a405b 100644 --- a/R/rwlts-package.R +++ b/R/rwlts-package.R @@ -30,7 +30,4 @@ NULL #' @importFrom dplyr mutate arrange ungroup group_by -#' @importFrom ggplot2 ggplot aes_string scale_y_continuous theme facet_wrap -#' geom_text stat -#' @importFrom ggalluvial geom_flow geom_stratum NULL diff --git a/R/wlts.R b/R/wlts.R index d0ea44f..ed873c1 100644 --- a/R/wlts.R +++ b/R/wlts.R @@ -122,6 +122,9 @@ get_trajectory <- function(URL, if (any(!is.null(start_date) | !is.null(end_date))) .check_datetime(start_date, end_date) + if (length(collections) > 1) + collections <- paste(collections, collapse = ",") + # build final url url_obj <- .build_url(URL, path = "/trajectory", query = list(start_date, end_date, collections), diff --git a/README.Rmd b/README.Rmd index cffbcc6..b0565c8 100644 --- a/README.Rmd +++ b/README.Rmd @@ -1,11 +1,12 @@ - --- output: github_document +editor_options: + markdown: + wrap: 72 --- - ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, @@ -24,35 +25,58 @@ R Client Library for Web Land Trajectory Service (WLTS) [![Software License](https://img.shields.io/badge/license-MIT-green)](https://github.com/brazil-data-cube/rstac/blob/master/LICENSE) -[![Build Status](https://drone.dpi.inpe.br/api/badges/brazil-data-cube/rwlts/status.svg)](https://drone.dpi.inpe.br/brazil-data-cube/rwlts) + [![codecov](https://codecov.io/gh/brazil-data-cube/rwlts/branch/main/graph/badge.svg?token=6WTJI6K93Y)](https://codecov.io/gh/brazil-data-cube/rwlts) -[![Software Life Cycle](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html) -[![Join us at Discord](https://img.shields.io/discord/689541907621085198?logo=discord&logoColor=ffffff&color=7389D8)](https://discord.com/channels/689541907621085198#) - - -About -===== - -Information on Land Use and Land Cover (LULC) is essential to support governments in making decisions about the impact of human activities on the environment, planning the use of natural resources, conserving biodiversity and monitoring climate change. - -Currently, several projects systematically provide information on the dynamics of land use and cover. Well known projects include PRODES, DETER and TerraClass. -These projects are developed by INPE and they produce information on land use and coverage used by the Brazilian Government to make public policy decisions. -Besides these projects there are other initiatives from universities and space agencies devoted to the creation of national and global maps. +[![Software Life +Cycle](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html) +[![Join us at +Discord](https://img.shields.io/discord/689541907621085198?logo=discord&logoColor=ffffff&color=7389D8)](https://discord.com/channels/689541907621085198#) -Although these projects follow open data policies and provide a rich collection of data, there is still a gap in tools that facilitate the integrated use of these collections. Each project adopts its own land use and land cover classification system, providing different class names and meanings for the elements of these collections. The forms of distribution of project data can be carried out in different ways, through files or web services. In addition, the data has different spatial and temporal resolutions and storage systems (raster or vector). - -In this context, the **W**eb **L**and **T**rajectory **S**ervice (WLTS) is a service that aims to facilitate the access to these vaapproach consists of using a data model that defines a minimum set of temporal and spatial information to represent different sources and types of data, but with a focus on land use and land cover. - -WLTS can be used in a variety of applications, such as validating land cover data sets, selecting training samples to support Machine Learning algorithms used in the generation of new classification maps. - -If you want to know more about WLTS service, please, take a look at its [specification](https://github.com/brazil-data-cube/wlts-spec). + +# About + +Information on Land Use and Land Cover (LULC) is essential to support +governments in making decisions about the impact of human activities on +the environment, planning the use of natural resources, conserving +biodiversity and monitoring climate change. + +Currently, several projects systematically provide information on the +dynamics of land use and cover. Well known projects include PRODES, +DETER and TerraClass. These projects are developed by INPE and they +produce information on land use and coverage used by the Brazilian +Government to make public policy decisions. Besides these projects there +are other initiatives from universities and space agencies devoted to +the creation of national and global maps. + +Although these projects follow open data policies and provide a rich +collection of data, there is still a gap in tools that facilitate the +integrated use of these collections. Each project adopts its own land +use and land cover classification system, providing different class +names and meanings for the elements of these collections. The forms of +distribution of project data can be carried out in different ways, +through files or web services. In addition, the data has different +spatial and temporal resolutions and storage systems (raster or vector). + +In this context, the **W**eb **L**and **T**rajectory **S**ervice (WLTS) +is a service that aims to facilitate the access to these approach +consists of using a data model that defines a minimum set of temporal +and spatial information to represent different sources and types of +data, but with a focus on land use and land cover. + +WLTS can be used in a variety of applications, such as validating land +cover data sets, selecting training samples to support Machine Learning +algorithms used in the generation of new classification maps. + +If you want to know more about WLTS service, please, take a look at its +[specification](https://github.com/brazil-data-cube/wlts-spec). ## Installation -To install the development version of `rwlts`, run the following commands: +To install the development version of `rwlts`, run the following +commands: -``` {R, eval=FALSE} +```{R, eval=FALSE} # load necessary libraries library(devtools) devtools::install_github("brazil-data-cube/rwlts") @@ -60,7 +84,7 @@ devtools::install_github("brazil-data-cube/rwlts") Importing `rwlts` package: -``` {R, echo=TRUE, warning=FALSE, message=FALSE} +```{R, echo=TRUE, warning=FALSE, message=FALSE} library(rwlts) ``` @@ -77,80 +101,118 @@ tribble( ) %>% as.data.frame() %>% knitr::kable(format = "markdown") ``` -These functions can be used to retrieve information from a WLTS API service. The code bellow creates a `wlts` object and list the available collections of the WLTS API of the Brazil Data Cube project of the Brazilian National Institute for Space Research INPE. +These functions can be used to retrieve information from a WLTS API +service. The code bellow creates a `wlts` object and list the available +collections of the WLTS API of the Brazil Data Cube project of the +Brazilian National Institute for Space Research INPE. ### List Collections -The first operation, `list_collections`, retrieves all available collections in WLTS service. - +The first operation, `list_collections`, retrieves all available +collections in WLTS service. -``` {R, echo=TRUE} +```{R, echo=TRUE} wlts_bdc <- "https://brazildatacube.dpi.inpe.br/wlts/" list_collections(wlts_bdc) ``` -### Describle Collection - -Each collection returned by the WLTS service can be used for retrieving LULC trajectories. To get information about the collections, we use the `describe_collection` function. This function returns the metadata of a given collection, which includes the description and specific details. The metadata also describes the spatio-temporal extent of the collection. +### Describe Collection -In the code below, we retrieve the metadata from the `deter_amazonia_legal` collection using the `describe_collection` function. +Each collection returned by the WLTS service can be used for retrieving +LULC trajectories. To get information about the collections, we use the +`describe_collection` function. This function returns the metadata of a +given collection, which includes the description and specific details. +The metadata also describes the spatio-temporal extent of the +collection. +In the code below, we retrieve the metadata from the +`deter_amazonia_legal` collection using the `describe_collection` +function. -``` {R, echo=TRUE} +```{R, echo=TRUE} describe_collection(wlts_bdc, "deter_amazonia_legal") ``` ### Trajectory -LULC trajectories can be extracted from collections. These LULC trajectories in WLTS services are associated with a point (lat, long) in geographic space. In `rwlts`, we can use the `get_trajectory` function to retrieve trajectories. For example, in the code below, the point `(-54, -12)` trajectory is retrieved from the `mapbiomas5_amazonia` collection. +LULC trajectories can be extracted from collections. These LULC +trajectories in WLTS services are associated with a point (lat, long) in +geographic space. In `rwlts`, we can use the `get_trajectory` function +to retrieve trajectories. For example, in the code below, the point +`(-54, -12)` trajectory is retrieved from the `mapbiomas_amazonia-v5` +collection. -``` {r} +```{r} get_trajectory(wlts_bdc, latitude = -12, longitude = -54, - collections = "mapbiomas5_amazonia") + collections = "mapbiomas_amazonia-v5", + config = httr::add_headers("x-api-key" = "change-me")) ``` - -The `get_trajectory` function returns a `list` of class `wlts`. This object contains the `query` and `result` attributes. The `query` attribute stores the query performed to retrieve the data. By default, it will be `NULL`. For this information to be stored, the `query_info = TRUE` parameter is required. For example: +The `get_trajectory` function returns a `list` of class `wlts`. This +object contains the `query` and `result` attributes. The `query` +attribute stores the query performed to retrieve the data. By default, +it will be `NULL`. For this information to be stored, the +`query_info = TRUE` parameter is required. For example: ```{r, eval=FALSE} get_trajectory(wlts_bdc, latitude = -12, longitude = -54, - collections = "mapbiomas5_amazonia", - query_info = TRUE) + collections = "mapbiomas_amazonia-v5", + query_info = TRUE, + config = httr::add_headers("x-api-key" = "change-me")) ``` -The `result` attribute stores the retrieved trajectories. The data is stored in a `tibble` for easy manipulation, which has the columns: +The `result` attribute stores the retrieved trajectories. The data is +stored in a `tibble` for easy manipulation, which has the columns: -- `class`: LULC class; -- `collection`: Data Collection; -- `date`: Time instants of the trajectory; -- `point_id`: ID of the point that was queried. +- `class`: LULC class; +- `collection`: Data Collection; +- `date`: Time instants of the trajectory; +- `point_id`: ID of the point that was queried. -The `point_id` column of the result `tibble` is used in `rwlts` to identify the entry point. This ID is necessary since the `get_trajectory` function can be used with vectors as input. For example, the code below retrieves the trajectory of data from the `mapbiomas5_amazonia` collection for two points `(-54, -12)` and `(-54, -11.01)`. +The `point_id` column of the result `tibble` is used in `rwlts` to +identify the entry point. This ID is necessary since the +`get_trajectory` function can be used with vectors as input. For +example, the code below retrieves the trajectory of data from the +`mapbiomas_amazonia-v5` collection for two points `(-54, -12)` and +`(-54, -11.01)`. ```{r} get_trajectory(wlts_bdc, latitude = c(-12, -11.01), longitude = c(-54, -54), - collections = "mapbiomas5_amazonia") + collections = "mapbiomas_amazonia-v5", + config = httr::add_headers("x-api-key" = "change-me")) ``` -In this case, the point `(-54, -12)` will have `point_id` equal to 1, while `(-54, -11.01)` will have `point_id` equal to 2. +In this case, the point `(-54, -12)` will have `point_id` equal to 1, +while `(-54, -11.01)` will have `point_id` equal to 2. -In addition to multiple point retrieval, the `get_trajectory` function allows multiple collections to be queried for the composition of the trajectory. To do this, in the `collections` parameter, the collections must be assigned. For example, data from the collections `mapbiomas5_amazonia` and `terraclass_amazonia` are retrieved in the code below. +In addition to multiple point retrieval, the `get_trajectory` function +allows multiple collections to be queried for the composition of the +trajectory. To do this, in the `collections` parameter, the collections +must be assigned. For example, data from the collections +`mapbiomas_amazonia-v5` and `terraclass_amazonia-v2` are retrieved in +the code below. ```{r} get_trajectory(wlts_bdc, latitude = c(-12, -11.01), longitude = c(-54, -54), - collections = "mapbiomas5_amazonia,terraclass_amazonia") + collections = c("mapbiomas_amazonia-v5", "terraclass_amazonia-v2"), + config = httr::add_headers("x-api-key" = "change-me")) ``` -Finally, the `get_trajectory` function, through the `start_date` and `end_date` parameters, allows you to specify the time intervals used in the trajectory. To exemplify its use, in the code below, trajectories are retrieved for the points `(-54, -12)` and `(-54, -11.01)`, from the `mapbiomas5_amazonia` and `terraclass_amazonia` collections in the time interval `[2003-01-01, 2004-01-01]`. +Finally, the `get_trajectory` function, through the `start_date` and +`end_date` parameters, allows you to specify the time intervals used in +the trajectory. To exemplify its use, in the code below, trajectories +are retrieved for the points `(-54, -12)` and `(-54, -11.01)`, from the +`mapbiomas_amazonia-v5` and `terraclass_amazonia-v2` collections in the +time interval `[2003-01-01, 2004-01-01]`. ```{r} get_trajectory(wlts_bdc, @@ -158,41 +220,33 @@ get_trajectory(wlts_bdc, longitude = c(-54, -54), start_date = "2003-01-01", end_date = "2004-01-01", - collections = "mapbiomas5_amazonia,terraclass_amazonia") + collections = c("mapbiomas_amazonia-v5","terraclass_amazonia-v2"), + config = httr::add_headers("x-api-key" = "change-me")) ``` -The `rwlts` uses the **httr** package to manage HTTP requests, allowing the use of tokens from the authorization protocols OAuth 1.0 or 2.0 as well as other configuration options. In the code below, we present an example of how to provide a parameter token on a HTTP request. +### Alluvial plot -```{r, eval=FALSE} -my_token <- "..." +To visualize the trajectories and fully understand their time dynamics, +the `rwlts` package implements the Alluvial-based visualization method. +To create this plot, use the `plot` function, as shown in the example +below: -get_trajectory(wlts_bdc, - latitude = c(-12, -11.01), - longitude = c(-54, -54), - collections = "mapbiomas5_amazonia,terraclass_amazonia", - config = httr::add_headers("x-api-key" = my_token)) -``` - -### Sankey plot - -To visualize the trajectories and fully understand their time dynamics, the `rwlts` package implements the Sankey-based visualization method. To create this plot, use the `plot_sankey` function, as shown in the example below: - -``` {r, fig.width = 9, fig.height = 4} +```{r, fig.width = 9, fig.height = 4} # import data from package data("mt_500_mapbiomas_cerrado") -plot_sankey(mt_500_mapbiomas_cerrado) +plot(mt_500_mapbiomas_cerrado) ``` -Besides, you can fully customize the returned plot. This customization is possible since the `plot_sankey` function returns a ggplot2 object. - +Besides, you can fully customize the returned plot. This customization +is possible since the `plot` function returns a ggplot2 object. ```{r, fig.width = 10} library(ggplot2) library(ggalluvial) # use to create plot library(cowplot) # use different theme -plot_sankey(mt_500_mapbiomas_cerrado, show_count_transition = TRUE) + +plot(mt_500_mapbiomas_cerrado, show_count = TRUE) + cowplot::theme_minimal_hgrid() + labs(title = "Changes in Primavera do Leste (2004-2014)", x = "Timeline", @@ -212,12 +266,14 @@ plot_sankey(mt_500_mapbiomas_cerrado, show_count_transition = TRUE) + "Soja")) ``` -> The numbers inside each bar correspond to the quantity of points extracted in each year. You can see that according to the change of LULC classes, the quantity of points in each class also changes. +> The numbers inside each bar correspond to the quantity of points +> extracted in each year. You can see that according to the change of +> LULC classes, the quantity of points in each class also changes. -License -======= +# License Copyright (C) 2021 INPE. -R client for WLTS is free software; you can redistribute it and/or modify it -under the terms of the MIT License; see LICENSE file for more details. +R client for WLTS is free software; you can redistribute it and/or +modify it under the terms of the MIT License; see LICENSE file for more +details. diff --git a/README.md b/README.md index 87dad53..341b8cb 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,13 @@ R Client Library for Web Land Trajectory Service (WLTS) [![Software License](https://img.shields.io/badge/license-MIT-green)](https://github.com/brazil-data-cube/rstac/blob/master/LICENSE) -[![Build -Status](https://drone.dpi.inpe.br/api/badges/brazil-data-cube/rwlts/status.svg)](https://drone.dpi.inpe.br/brazil-data-cube/rwlts) +[![Build Status](https://drone.dpi.inpe.br/api/badges/brazil-data-cube/rwlts/status.svg)](https://drone.dpi.inpe.br/brazil-data-cube/rwlts) [![codecov](https://codecov.io/gh/brazil-data-cube/rwlts/branch/main/graph/badge.svg?token=6WTJI6K93Y)](https://codecov.io/gh/brazil-data-cube/rwlts) [![Software Life Cycle](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html) [![Join us at Discord](https://img.shields.io/discord/689541907621085198?logo=discord&logoColor=ffffff&color=7389D8)](https://discord.com/channels/689541907621085198#) + # About @@ -43,7 +43,7 @@ through files or web services. In addition, the data has different spatial and temporal resolutions and storage systems (raster or vector). In this context, the **W**eb **L**and **T**rajectory **S**ervice (WLTS) -is a service that aims to facilitate the access to these vaapproach +is a service that aims to facilitate the access to these approach consists of using a data model that defines a minimum set of temporal and spatial information to represent different sources and types of data, but with a focus on land use and land cover. @@ -96,16 +96,17 @@ collections in WLTS service. wlts_bdc <- "https://brazildatacube.dpi.inpe.br/wlts/" list_collections(wlts_bdc) -#> [1] "terraclass_amazonia" "deter_amazonia_legal" -#> [3] "deter_cerrado" "prodes_cerrado" -#> [5] "prodes_amazonia_legal" "ibge_cobertura_uso_terra" -#> [7] "lapig_areas_pastagem" "mapbiomas5_amazonia" -#> [9] "mapbiomas5_cerrado" "mapbiomas5_caatinga" -#> [11] "mapbiomas5_mata_atlantica" "mapbiomas5_pampa" -#> [13] "mapbiomas5_pantanal" +#> [1] "lapig_areas_pastagem" "terraclass_amazonia" +#> [3] "deter_amazonia_legal" "deter_cerrado" +#> [5] "ibge_cobertura_uso_terra" "prodes_amazonia_legal" +#> [7] "prodes_cerrado" "mapbiomas_caatinga-v5" +#> [9] "mapbiomas_cerrado-v5" "mapbiomas_amazonia-v5" +#> [11] "terraclass_amazonia-v2" "mapbiomas_pantanal-v5" +#> [13] "mapbiomas_pampa-v5" "terraclass_cerrado" +#> [15] "mapbiomas_mata_atlantica-v5" ``` -### Describle Collection +### Describe Collection Each collection returned by the WLTS service can be used for retrieving LULC trajectories. To get information about the collections, we use the @@ -182,41 +183,33 @@ LULC trajectories can be extracted from collections. These LULC trajectories in WLTS services are associated with a point (lat, long) in geographic space. In `rwlts`, we can use the `get_trajectory` function to retrieve trajectories. For example, in the code below, the point -`(-54, -12)` trajectory is retrieved from the `mapbiomas5_amazonia` +`(-54, -12)` trajectory is retrieved from the `mapbiomas_amazonia-v5` collection. ``` r get_trajectory(wlts_bdc, latitude = -12, longitude = -54, - collections = "mapbiomas5_amazonia") + collections = "mapbiomas_amazonia-v5", + config = httr::add_headers("x-api-key" = "change-me")) #> $query #> NULL #> #> $result -#> # A tibble: 20 x 4 -#> class collection date point_id -#> -#> 1 Formação Florestal mapbiomas5_amazonia 2000 1 -#> 2 Formação Florestal mapbiomas5_amazonia 2001 1 -#> 3 Formação Florestal mapbiomas5_amazonia 2002 1 -#> 4 Formação Florestal mapbiomas5_amazonia 2003 1 -#> 5 Formação Florestal mapbiomas5_amazonia 2004 1 -#> 6 Formação Florestal mapbiomas5_amazonia 2005 1 -#> 7 Formação Florestal mapbiomas5_amazonia 2006 1 -#> 8 Formação Florestal mapbiomas5_amazonia 2007 1 -#> 9 Formação Florestal mapbiomas5_amazonia 2008 1 -#> 10 Formação Florestal mapbiomas5_amazonia 2009 1 -#> 11 Formação Florestal mapbiomas5_amazonia 2010 1 -#> 12 Formação Florestal mapbiomas5_amazonia 2011 1 -#> 13 Formação Florestal mapbiomas5_amazonia 2012 1 -#> 14 Formação Florestal mapbiomas5_amazonia 2013 1 -#> 15 Formação Florestal mapbiomas5_amazonia 2014 1 -#> 16 Formação Florestal mapbiomas5_amazonia 2015 1 -#> 17 Formação Florestal mapbiomas5_amazonia 2016 1 -#> 18 Formação Florestal mapbiomas5_amazonia 2017 1 -#> 19 Formação Florestal mapbiomas5_amazonia 2018 1 -#> 20 Formação Florestal mapbiomas5_amazonia 2019 1 +#> # A tibble: 35 × 4 +#> class collection date point_id +#> +#> 1 Formação Florestal mapbiomas_amazonia-v5 1985 1 +#> 2 Formação Florestal mapbiomas_amazonia-v5 1986 1 +#> 3 Formação Florestal mapbiomas_amazonia-v5 1987 1 +#> 4 Formação Florestal mapbiomas_amazonia-v5 1988 1 +#> 5 Formação Florestal mapbiomas_amazonia-v5 1989 1 +#> 6 Formação Florestal mapbiomas_amazonia-v5 1990 1 +#> 7 Formação Florestal mapbiomas_amazonia-v5 1991 1 +#> 8 Formação Florestal mapbiomas_amazonia-v5 1992 1 +#> 9 Formação Florestal mapbiomas_amazonia-v5 1993 1 +#> 10 Formação Florestal mapbiomas_amazonia-v5 1994 1 +#> # … with 25 more rows #> #> attr(,"class") #> [1] "wlts" @@ -232,8 +225,9 @@ it will be `NULL`. For this information to be stored, the get_trajectory(wlts_bdc, latitude = -12, longitude = -54, - collections = "mapbiomas5_amazonia", - query_info = TRUE) + collections = "mapbiomas_amazonia-v5", + query_info = TRUE, + config = httr::add_headers("x-api-key" = "change-me")) ``` The `result` attribute stores the retrieved trajectories. The data is @@ -248,32 +242,33 @@ The `point_id` column of the result `tibble` is used in `rwlts` to identify the entry point. This ID is necessary since the `get_trajectory` function can be used with vectors as input. For example, the code below retrieves the trajectory of data from the -`mapbiomas5_amazonia` collection for two points `(-54, -12)` and +`mapbiomas_amazonia-v5` collection for two points `(-54, -12)` and `(-54, -11.01)`. ``` r get_trajectory(wlts_bdc, latitude = c(-12, -11.01), longitude = c(-54, -54), - collections = "mapbiomas5_amazonia") + collections = "mapbiomas_amazonia-v5", + config = httr::add_headers("x-api-key" = "change-me")) #> $query #> NULL #> #> $result -#> # A tibble: 40 x 4 -#> class collection date point_id -#> -#> 1 Formação Florestal mapbiomas5_amazonia 2000 1 -#> 2 Formação Florestal mapbiomas5_amazonia 2001 1 -#> 3 Formação Florestal mapbiomas5_amazonia 2002 1 -#> 4 Formação Florestal mapbiomas5_amazonia 2003 1 -#> 5 Formação Florestal mapbiomas5_amazonia 2004 1 -#> 6 Formação Florestal mapbiomas5_amazonia 2005 1 -#> 7 Formação Florestal mapbiomas5_amazonia 2006 1 -#> 8 Formação Florestal mapbiomas5_amazonia 2007 1 -#> 9 Formação Florestal mapbiomas5_amazonia 2008 1 -#> 10 Formação Florestal mapbiomas5_amazonia 2009 1 -#> # … with 30 more rows +#> # A tibble: 70 × 4 +#> class collection date point_id +#> +#> 1 Formação Florestal mapbiomas_amazonia-v5 1985 1 +#> 2 Formação Florestal mapbiomas_amazonia-v5 1986 1 +#> 3 Formação Florestal mapbiomas_amazonia-v5 1987 1 +#> 4 Formação Florestal mapbiomas_amazonia-v5 1988 1 +#> 5 Formação Florestal mapbiomas_amazonia-v5 1989 1 +#> 6 Formação Florestal mapbiomas_amazonia-v5 1990 1 +#> 7 Formação Florestal mapbiomas_amazonia-v5 1991 1 +#> 8 Formação Florestal mapbiomas_amazonia-v5 1992 1 +#> 9 Formação Florestal mapbiomas_amazonia-v5 1993 1 +#> 10 Formação Florestal mapbiomas_amazonia-v5 1994 1 +#> # … with 60 more rows #> #> attr(,"class") #> [1] "wlts" @@ -286,32 +281,33 @@ In addition to multiple point retrieval, the `get_trajectory` function allows multiple collections to be queried for the composition of the trajectory. To do this, in the `collections` parameter, the collections must be assigned. For example, data from the collections -`mapbiomas5_amazonia` and `terraclass_amazonia` are retrieved in the -code below. +`mapbiomas_amazonia-v5` and `terraclass_amazonia-v2` are retrieved in +the code below. ``` r get_trajectory(wlts_bdc, latitude = c(-12, -11.01), longitude = c(-54, -54), - collections = "mapbiomas5_amazonia,terraclass_amazonia") + collections = c("mapbiomas_amazonia-v5", "terraclass_amazonia-v2"), + config = httr::add_headers("x-api-key" = "change-me")) #> $query #> NULL #> #> $result -#> # A tibble: 50 x 4 -#> class collection date point_id -#> -#> 1 Formação Florestal mapbiomas5_amazonia 2000 1 -#> 2 Formação Florestal mapbiomas5_amazonia 2001 1 -#> 3 Formação Florestal mapbiomas5_amazonia 2002 1 -#> 4 Formação Florestal mapbiomas5_amazonia 2003 1 -#> 5 Formação Florestal mapbiomas5_amazonia 2004 1 -#> 6 Floresta terraclass_amazonia 2004 1 -#> 7 Formação Florestal mapbiomas5_amazonia 2005 1 -#> 8 Formação Florestal mapbiomas5_amazonia 2006 1 -#> 9 Formação Florestal mapbiomas5_amazonia 2007 1 -#> 10 Formação Florestal mapbiomas5_amazonia 2008 1 -#> # … with 40 more rows +#> # A tibble: 80 × 4 +#> class collection date point_id +#> +#> 1 Formação Florestal mapbiomas_amazonia-v5 1985 1 +#> 2 Formação Florestal mapbiomas_amazonia-v5 1986 1 +#> 3 Formação Florestal mapbiomas_amazonia-v5 1987 1 +#> 4 Formação Florestal mapbiomas_amazonia-v5 1988 1 +#> 5 Formação Florestal mapbiomas_amazonia-v5 1989 1 +#> 6 Formação Florestal mapbiomas_amazonia-v5 1990 1 +#> 7 Formação Florestal mapbiomas_amazonia-v5 1991 1 +#> 8 Formação Florestal mapbiomas_amazonia-v5 1992 1 +#> 9 Formação Florestal mapbiomas_amazonia-v5 1993 1 +#> 10 Formação Florestal mapbiomas_amazonia-v5 1994 1 +#> # … with 70 more rows #> #> attr(,"class") #> [1] "wlts" @@ -321,8 +317,8 @@ Finally, the `get_trajectory` function, through the `start_date` and `end_date` parameters, allows you to specify the time intervals used in the trajectory. To exemplify its use, in the code below, trajectories are retrieved for the points `(-54, -12)` and `(-54, -11.01)`, from the -`mapbiomas5_amazonia` and `terraclass_amazonia` collections in the time -interval `[2003-01-01, 2004-01-01]`. +`mapbiomas_amazonia-v5` and `terraclass_amazonia-v2` collections in the +time interval `[2003-01-01, 2004-01-01]`. ``` r get_trajectory(wlts_bdc, @@ -330,65 +326,51 @@ get_trajectory(wlts_bdc, longitude = c(-54, -54), start_date = "2003-01-01", end_date = "2004-01-01", - collections = "mapbiomas5_amazonia,terraclass_amazonia") + collections = c("mapbiomas_amazonia-v5","terraclass_amazonia-v2"), + config = httr::add_headers("x-api-key" = "change-me")) #> $query #> NULL #> #> $result -#> # A tibble: 6 x 4 -#> class collection date point_id -#> -#> 1 Formação Florestal mapbiomas5_amazonia 2003 1 -#> 2 Formação Florestal mapbiomas5_amazonia 2004 1 -#> 3 Floresta terraclass_amazonia 2004 1 -#> 4 Formação Florestal mapbiomas5_amazonia 2003 2 -#> 5 Formação Florestal mapbiomas5_amazonia 2004 2 -#> 6 Floresta terraclass_amazonia 2004 2 +#> # A tibble: 6 × 4 +#> class collection date point_id +#> +#> 1 Formação Florestal mapbiomas_amazonia-v5 2003 1 +#> 2 Formação Florestal mapbiomas_amazonia-v5 2004 1 +#> 3 Vegetação Natural Florestal Primária terraclass_amazonia-v2 2004 1 +#> 4 Formação Florestal mapbiomas_amazonia-v5 2003 2 +#> 5 Formação Florestal mapbiomas_amazonia-v5 2004 2 +#> 6 Vegetação Natural Florestal Primária terraclass_amazonia-v2 2004 2 #> #> attr(,"class") #> [1] "wlts" ``` -The `rwlts` uses the **httr** package to manage HTTP requests, allowing -the use of tokens from the authorization protocols OAuth 1.0 or 2.0 as -well as other configuration options. In the code below, we present an -example of how to provide a parameter token on a HTTP request. - -``` r -my_token <- "..." - -get_trajectory(wlts_bdc, - latitude = c(-12, -11.01), - longitude = c(-54, -54), - collections = "mapbiomas5_amazonia,terraclass_amazonia", - config = httr::add_headers("x-api-key" = my_token)) -``` - -### Sankey plot +### Alluvial plot To visualize the trajectories and fully understand their time dynamics, -the `rwlts` package implements the Sankey-based visualization method. To -create this plot, use the `plot_sankey` function, as shown in the -example below: +the `rwlts` package implements the Alluvial-based visualization method. +To create this plot, use the `plot` function, as shown in the example +below: ``` r # import data from package data("mt_500_mapbiomas_cerrado") -plot_sankey(mt_500_mapbiomas_cerrado) +plot(mt_500_mapbiomas_cerrado) ``` - + Besides, you can fully customize the returned plot. This customization -is possible since the `plot_sankey` function returns a ggplot2 object. +is possible since the `plot` function returns a ggplot2 object. ``` r library(ggplot2) library(ggalluvial) # use to create plot library(cowplot) # use different theme -plot_sankey(mt_500_mapbiomas_cerrado, show_count_transition = TRUE) + +plot(mt_500_mapbiomas_cerrado, show_count = TRUE) + cowplot::theme_minimal_hgrid() + labs(title = "Changes in Primavera do Leste (2004-2014)", x = "Timeline", @@ -408,7 +390,7 @@ plot_sankey(mt_500_mapbiomas_cerrado, show_count_transition = TRUE) + "Soja")) ``` - + > The numbers inside each bar correspond to the quantity of points > extracted in each year. You can see that according to the change of diff --git a/inst/extdata/img/README-unnamed-chunk-12-1.png b/inst/extdata/img/README-unnamed-chunk-12-1.png new file mode 100644 index 0000000..6d7df45 Binary files /dev/null and b/inst/extdata/img/README-unnamed-chunk-12-1.png differ diff --git a/inst/extdata/img/README-unnamed-chunk-13-1.png b/inst/extdata/img/README-unnamed-chunk-13-1.png index 6d7df45..149835f 100644 Binary files a/inst/extdata/img/README-unnamed-chunk-13-1.png and b/inst/extdata/img/README-unnamed-chunk-13-1.png differ diff --git a/man/plot_sankey.Rd b/man/plot.wlts.Rd similarity index 50% rename from man/plot_sankey.Rd rename to man/plot.wlts.Rd index 79470bb..a934572 100644 --- a/man/plot_sankey.Rd +++ b/man/plot.wlts.Rd @@ -1,39 +1,46 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/plot.R -\name{plot_sankey} -\alias{plot_sankey} -\title{Sankey Plot} +\name{plot.wlts} +\alias{plot.wlts} +\alias{plot.alluvial} +\title{Plots for rwlts package} \usage{ -plot_sankey(wtls_tibble, show_count_transition = FALSE) +\method{plot}{wlts}(x, ..., type = "alluvial") + +\method{plot}{alluvial}(x, ..., show_count = FALSE) } \arguments{ -\item{wtls_tibble}{a \code{tibble} object from class \code{wlts}.} +\item{x}{a \code{tibble} object from class \code{wlts}.} + +\item{...}{additional functions} -\item{show_count_transition}{a \code{logical} parameter, if true, is added +\item{type}{a \code{character} with the type of plot. +Nowadays, only the "alluvial" plot is supported. By default is "alluvial".} + +\item{show_count}{a \code{logical} parameter, if true, is added the number of points on each bar. The default value is FALSE.} } \value{ a \code{gg} object from ggplot2 package. } \description{ -Visualization method based on the sankey graph. In which the -changes between each class are presented on the time axis. +A set of visualization methods for trajectories extracted in + rwlts package. } \examples{ -\donttest{ +\dontrun{ wlts_bdc <- "https://brazildatacube.dpi.inpe.br/wlts/" wlts_tibble <- get_trajectory( URL = wlts_bdc, latitude = c(-12, -11), longitude = c(-54, -55), - collections = "mapbiomas5_amazonia", + collections = "mapbiomas_amazonia-v5", start_date = "2015-07-01", end_date = "2017-07-01", config = httr::add_headers("x-api-key" = "BDC-KEY")) - - plot_sankey(wlts_tibble) + plot(wlts_tibble) } }