From ed10270c0f72a563ec5a15975796c0f1af72ee5d Mon Sep 17 00:00:00 2001 From: Scott Chamberlain Date: Wed, 10 Aug 2016 13:47:29 -0700 Subject: [PATCH] fix #17 fixed cache delete fxn and other caching fxns fix #16 clear up usage of lsast_list, lsat_scenes and lsast_scene_files fix #15 more details on what pkg is for bump dev version --- DESCRIPTION | 8 +++++--- R/cache.R | 1 + R/getlandsat-package.R | 25 +++++++++++++++++++++++++ R/lsat_list.R | 11 ++++++----- R/lsat_scenes.R | 6 ++++++ R/lsat_scenes_files.R | 7 ++++++- inst/vign/getlandsat_vignette.Rmd | 5 +++-- man/getlandsat-package.Rd | 26 +++++++++++++++++++++++++- man/lsat_cache.Rd | 2 ++ man/lsat_list.Rd | 7 +++++-- man/lsat_scene_files.Rd | 9 ++++++++- man/lsat_scenes.Rd | 7 +++++++ 12 files changed, 99 insertions(+), 15 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index f0ed40f..b261cb5 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,8 +5,8 @@ Description: Get Landsat 8 Data from AWS public data sets (). Includes functions for listing images and fetching them, and handles caching to prevent unnecessary additional requests. -Version: 0.0.6.9000 -Date: 2016-07-13 +Version: 0.0.9.9000 +Date: 2016-08-10 Authors@R: c(person("Scott", "Chamberlain", role = c("aut", "cre"), email = "myrmecocystus@gmail.com")) License: MIT + file LICENSE @@ -21,8 +21,10 @@ Imports: tibble, rappdirs Suggests: + roxygen2 (>= 5.0.1), testthat, knitr, - covr + covr, + raster VignetteBuilder: knitr RoxygenNote: 5.0.1 diff --git a/R/cache.R b/R/cache.R index 9d0d348..702c6d4 100644 --- a/R/cache.R +++ b/R/cache.R @@ -12,6 +12,7 @@ #' @details We cache using \code{\link[rappdirs]{user_cache_dir}}, find your cache #' folder by executing \code{rappdirs::user_cache_dir("landsat-pds")} #' +#' @section Functions: #' \itemize{ #' \item \code{lsat_cache_list()} returns a character vector of full path file names #' \item \code{lsat_cache_delete()} deletes one or more files, returns nothing diff --git a/R/getlandsat-package.R b/R/getlandsat-package.R index 739b577..24c0111 100644 --- a/R/getlandsat-package.R +++ b/R/getlandsat-package.R @@ -1,5 +1,10 @@ #' getlandsat - get Landsat 8 data from AWS public data sets #' +#' \pkg{getlandsat} provides access to Landsat \url{https://landsat.usgs.gov} 8 +#' metadata and images hosted on AWS S3 at +#' \url{https://aws.amazon.com/public-data-sets/landsat}. The package only +#' fetches data. It does not attempt to aid users in downstream usage. +#' #' @importFrom readr read_csv #' @importFrom xml2 read_html read_xml xml_find_all as_list xml_children xml_name #' @importFrom httr content write_disk GET stop_for_status @@ -7,4 +12,24 @@ #' @aliases getlandsat #' @docType package #' @keywords package +#' +#' @examples \dontrun{ +#' ## List scenes +#' (res <- lsat_scenes(n_max = 10)) +#' +#' ## List scene files +#' lsat_scene_files(x = res$download_url[1]) +#' +#' ## Get an image +#' ### Returns path to the image +#' lsat_image(x = "LC80101172015002LGN00_B5.TIF") +#' +#' ## Visualize +#' if (requireNamespace("raster")) { +#' library("raster") +#' x <- lsat_cache_details()[[1]] +#' img <- raster(x$file) +#' plot(img) +#' } +#' } NULL diff --git a/R/lsat_list.R b/R/lsat_list.R index cb0407f..c5f52ea 100644 --- a/R/lsat_list.R +++ b/R/lsat_list.R @@ -1,8 +1,4 @@ -#' @title List Landsat images -#' -#' @description This is an alternative to using lsat_scenes(). This -#' function uses the AWS S3 API, while the other fxn simply downloads -#' the up to date compressed csv file. +#' List Landsat images #' #' @export #' @param max (integer) number indicating the maximum number of keys to return (max 1000, @@ -15,6 +11,11 @@ #' @param delimiter (character) string used to group keys. Read the AWS doc for #' more detail. #' @param ... curl args passed on to \code{\link[httr]{GET}} +#' +#' @details This is an alternative to using \code{\link{lsat_scenes}}. This +#' function uses the AWS S3 API, while \code{\link{lsat_scenes}} downloads +#' the up to date compressed csv file. +#' #' @examples \dontrun{ #' lsat_list(max = 10) #' diff --git a/R/lsat_scenes.R b/R/lsat_scenes.R index 710d7a9..4e453f1 100644 --- a/R/lsat_scenes.R +++ b/R/lsat_scenes.R @@ -8,6 +8,12 @@ #' file for \code{read_csv} for what parameter you can pass to modify it's #' behavior. #' +#' This is an alternative to using \code{\link{lsat_list}}. This function +#' downloads the up to date compressed csv file, while \code{\link{lsat_list}} +#' uses the AWS S3 API. +#' +#' @seealso \code{\link{lsat_scene_files}} +#' #' @examples \dontrun{ #' res <- lsat_scenes() #' head(res) diff --git a/R/lsat_scenes_files.R b/R/lsat_scenes_files.R index f85b375..cd563f7 100644 --- a/R/lsat_scenes_files.R +++ b/R/lsat_scenes_files.R @@ -2,7 +2,12 @@ #' #' @export #' @param x (character) A URL to a scene html file -#' @param ... Further args passed on to \code{\link[httr]{GET}} +#' @param ... Curl options passed on to \code{\link[httr]{GET}} +#' +#' @details This function fetches files available in a scene, while +#' \code{\link{lsat_scenes}} lists the scenes, but not their files +#' +#' @seealso \code{\link{lsat_scenes}} #' #' @return A data.frame with two columns: #' \itemize{ diff --git a/inst/vign/getlandsat_vignette.Rmd b/inst/vign/getlandsat_vignette.Rmd index 255d374..89a13a4 100644 --- a/inst/vign/getlandsat_vignette.Rmd +++ b/inst/vign/getlandsat_vignette.Rmd @@ -17,8 +17,9 @@ knitr::opts_chunk$set( getlandsat introduction ======================= -Get Landsat 8 Data from AWS public data sets. Includes functions for -listing images and fetching them. +`getlandsat` provides access to Landsat 8 metadata and images hosted on AWS S3 at . The package only fetches data. It does not attempt to aid users in downstream usage, but some additional functionality may be added. + +Potential users are probably anyone from scientists asking questions about biodiversity or land use change, to software developers creating tools for users to vizualize their data. ## Install diff --git a/man/getlandsat-package.Rd b/man/getlandsat-package.Rd index 6dac65f..fde1aac 100644 --- a/man/getlandsat-package.Rd +++ b/man/getlandsat-package.Rd @@ -6,7 +6,31 @@ \alias{getlandsat-package} \title{getlandsat - get Landsat 8 data from AWS public data sets} \description{ -getlandsat - get Landsat 8 data from AWS public data sets +\pkg{getlandsat} provides access to Landsat \url{https://landsat.usgs.gov} 8 +metadata and images hosted on AWS S3 at +\url{https://aws.amazon.com/public-data-sets/landsat}. The package only +fetches data. It does not attempt to aid users in downstream usage. +} +\examples{ +\dontrun{ +## List scenes +(res <- lsat_scenes(n_max = 10)) + +## List scene files +lsat_scene_files(x = res$download_url[1]) + +## Get an image +### Returns path to the image +lsat_image(x = "LC80101172015002LGN00_B5.TIF") + +## Visualize +if (requireNamespace("raster")) { + library("raster") + x <- lsat_cache_details()[[1]] + img <- raster(x$file) + plot(img) +} +} } \keyword{package} diff --git a/man/lsat_cache.Rd b/man/lsat_cache.Rd index 0f6fcd7..f080ab5 100644 --- a/man/lsat_cache.Rd +++ b/man/lsat_cache.Rd @@ -31,6 +31,8 @@ use \code{cache_delete} in a \code{\link{lapply}} type call We cache using \code{\link[rappdirs]{user_cache_dir}}, find your cache folder by executing \code{rappdirs::user_cache_dir("landsat-pds")} +} +\section{Functions}{ \itemize{ \item \code{lsat_cache_list()} returns a character vector of full path file names diff --git a/man/lsat_list.Rd b/man/lsat_list.Rd index 0fb97cd..c17acce 100644 --- a/man/lsat_list.Rd +++ b/man/lsat_list.Rd @@ -24,8 +24,11 @@ more detail.} \item{...}{curl args passed on to \code{\link[httr]{GET}}} } \description{ -This is an alternative to using lsat_scenes(). This -function uses the AWS S3 API, while the other fxn simply downloads +List Landsat images +} +\details{ +This is an alternative to using \code{\link{lsat_scenes}}. This +function uses the AWS S3 API, while \code{\link{lsat_scenes}} downloads the up to date compressed csv file. } \examples{ diff --git a/man/lsat_scene_files.Rd b/man/lsat_scene_files.Rd index 7bc89f3..cff2a63 100644 --- a/man/lsat_scene_files.Rd +++ b/man/lsat_scene_files.Rd @@ -9,7 +9,7 @@ lsat_scene_files(x, ...) \arguments{ \item{x}{(character) A URL to a scene html file} -\item{...}{Further args passed on to \code{\link[httr]{GET}}} +\item{...}{Curl options passed on to \code{\link[httr]{GET}}} } \value{ A data.frame with two columns: @@ -21,6 +21,10 @@ A data.frame with two columns: \description{ List files for a Landsat scene } +\details{ +This function fetches files available in a scene, while +\code{\link{lsat_scenes}} lists the scenes, but not their files +} \examples{ \dontrun{ res <- lsat_scenes(n_max = 10) @@ -28,4 +32,7 @@ lsat_scene_files(x = res$download_url[1]) lsat_scene_files(x = res$download_url[2]) } } +\seealso{ +\code{\link{lsat_scenes}} +} diff --git a/man/lsat_scenes.Rd b/man/lsat_scenes.Rd index 3ba6a40..d34ad1e 100644 --- a/man/lsat_scenes.Rd +++ b/man/lsat_scenes.Rd @@ -17,6 +17,10 @@ We use \code{\link[readr]{read_csv}} to read the scene list file from \url{http://landsat-pds.s3.amazonaws.com/scene_list.gz}. See the help file for \code{read_csv} for what parameter you can pass to modify it's behavior. + +This is an alternative to using \code{\link{lsat_list}}. This function +downloads the up to date compressed csv file, while \code{\link{lsat_list}} +uses the AWS S3 API. } \examples{ \dontrun{ @@ -27,4 +31,7 @@ head(res) lsat_scenes(n_max = 10) } } +\seealso{ +\code{\link{lsat_scene_files}} +}