{"id":21539442,"url":"https://github.com/bluegreen-labs/appeears","last_synced_at":"2025-08-23T23:14:18.147Z","repository":{"id":164338811,"uuid":"636680657","full_name":"bluegreen-labs/appeears","owner":"bluegreen-labs","description":"Interface to the NASA AppEEARS API","archived":false,"fork":false,"pushed_at":"2025-02-25T09:54:17.000Z","size":1430,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-03-24T04:43:37.820Z","etag":null,"topics":["api","data-science","r-package","remote-sensing","rstats"],"latest_commit_sha":null,"homepage":"https://bluegreen-labs.github.io/appeears/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluegreen-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-05-05T11:57:22.000Z","updated_at":"2025-02-25T09:49:42.000Z","dependencies_parsed_at":"2024-01-22T14:03:15.659Z","dependency_job_id":null,"html_url":"https://github.com/bluegreen-labs/appeears","commit_stats":{"total_commits":151,"total_committers":1,"mean_commits":151.0,"dds":0.0,"last_synced_commit":"cf97971c624d294ebef476be1bf361768b37c9ea"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluegreen-labs%2Fappeears","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluegreen-labs%2Fappeears/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluegreen-labs%2Fappeears/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluegreen-labs%2Fappeears/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluegreen-labs","download_url":"https://codeload.github.com/bluegreen-labs/appeears/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248149998,"owners_count":21055844,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","data-science","r-package","remote-sensing","rstats"],"created_at":"2024-11-24T04:15:21.826Z","updated_at":"2025-04-10T03:26:14.342Z","avatar_url":"https://github.com/bluegreen-labs.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# appeears \u003cimg src=\"man/figures/logo.png\" align=\"right\" height=\"139\" alt=\"\" /\u003e\n\n[![R-CMD-check](https://github.com/bluegreen-labs/appeears/workflows/R-CMD-check/badge.svg)](https://github.com/bluegreen-labs/appeears/actions)\n[![codecov](https://codecov.io/gh/bluegreen-labs/appeears/branch/main/graph/badge.svg)](https://app.codecov.io/gh/bluegreen-labs/appeears)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7938190.svg)](https://doi.org/10.5281/zenodo.7938190)\n![](https://cranlogs.r-pkg.org/badges/grand-total/appeears) \n![](https://www.r-pkg.org/badges/version/appeears)\n\nProgrammatic interface to the [NASA AppEEARS API](https://appeears.earthdatacloud.nasa.gov/) services where, and I quote, \"The Application for Extracting and Exploring Analysis Ready Samples (AρρEEARS) offers a simple and efficient way to access and transform geospatial data from a variety of federal data archives. AρρEEARS enables users to subset geospatial datasets using spatial, temporal, and band/layer parameters.\"\n\n## How to cite this package\n\nYou can cite this package like this \"we obtained data through the NASA AppEEARS\nAPI using the {appeears} R package (Hufkens 2023)\". Here is the full\nbibliographic reference to include in your reference list (don't forget\nto update the 'last accessed' date):\n\n\u003e Hufkens, K. (2023). appeears: Programmatic interface to the NASA AppEEARS API. Zenodo. \u003chttps://doi.org/10.5281/zenodo.7938190\u003e.\n\n## Installation\n\n### stable release\n\nTo install the current stable release use a CRAN repository:\n\n``` r\ninstall.packages(\"appeears\")\nlibrary(\"appeears\")\n```\n\n### development release\n\nTo install the development releases of the package run the following\ncommands:\n\n``` r\nif(!require(remotes)){install.packages(\"remotes\")}\nremotes::install_github(\"bluegreen-labs/appeears\")\nlibrary(\"appeears\")\n```\n\nVignettes are not rendered by default, if you want to include additional\ndocumentation please use:\n\n``` r\nif(!require(remotes)){install.packages(\"remotes\")}\nremotes::install_github(\"bluegreen-labs/appeears\", build_vignettes = TRUE)\nlibrary(\"appeears\")\n```\n\n## Use\n\n### Setup\n\nBefore starting save the provided NASA Earth Data password to your local keychain. The\npackage does not allow you to use your password inline in scripts to limit\nsecurity issues when sharing scripts on github or otherwise. In the `appeears` package and API\nthe login user is your chosen user name, **not your email address**.\n\nIn the `R` console (command line) use the following workflow to enter your `appeears`\ncredentials in your keychain management. If this fails, please fall back to file\nbased keychain management (see below). Avoid putting the `rs_set_key()`\ncode in your script as you might leak login credentials through code sharing!\n\n``` r\n# set a key to the keychain\nrs_set_key(\n  user = \"earth_data_user\",\n  password = \"XXXXXXXXXXXXXXXXXXXXXX\"\n  )\n\n# you can retrieve the password using\nrs_get_key(user = \"earth_data_user\")\n\n# the output should be the key you provided\n# \"XXXXXXXXXXXXXXXXXXXXXX\"\n```\n\nDownloads are managed using a Bearer/session token. This token is valid for 48 hours,\nafter which it will expire and you will need to request a new one. Although downloads\nare managed using the user (keychain) details only, you can request the current token\nusing `rs_login()`, while `rs_logout()` will explicitly invalidate the current\nsession token.\n\n```r\n# request the current token\ntoken \u003c- rs_login(user = \"earth_data_user\")\n\n# invalidate the current session\nrs_logout(token)\n```\n\n#### File based keychains\n\nOn linux, or systems with key management issues, you can opt to use\na file based keyring instead of a graphical user interface (GUI) based keyring manager. \nFor example, this is helpful for headless setups such as servers without a GUI.\nFor this option to work users must set an `R` environmental option\nat the beginning of each session or script (before executing any login routines).\n\nOn the `R` console (command line) set the environmental option as shown below and set\nyour key using your username and password.\n\n``` r\n# set the environmental variable\n# on the command line or in any\n# script that runs on a file based\n# keychain\noptions(keyring_backend=\"file\")\n```\n\n``` r\n# on the command line set your key\nrs_set_key(\n  user = \"earth_data_user\",\n  password = \"XXXXXXXXXXXXXXXXXXXXXX\"\n  )\n```\n\nWhen using a file based keychain you will need to set the environmental option\nat the beginning of each session (on the command line) or at the\nbeginning of each script (before login commands).\n\n``` r\n# set the environmental variable\n# on the command line or in any\n# script that runs on a file based\n# keychain\noptions(keyring_backend=\"file\")\n\n# submit a request\nrs_request(...)\n```\n\nUpon the start of each session/script you will be asked to provide your\npassword, unlocking all `appeears` credentials for this session. Should\nyou ever forget the password just delete the file at:\n`~/.config/r-keyring/appeears.keyring` and re-enter all your credentials\non the command line (see above).\n\n### Point based data requests\n\nAll point based queries are made by first creating a\ntidy data frame with the desired products and layers\nto query.\n\nIn this data frame `task` specifies the overall name\nof the task to run (this prefix will be used to name\nthe final downloaded files). The `subtask` denotes the\nvarious locations and or products you want to query. As\nsuch, you can query multiple locations in the same larger\ntask, avoiding multiple queries to the API.\n\nThe `latitude` and `longitude` fields specify geographic\ncoordinates of query locations, while `start` and `end`\ncolumns define the range of the data queried. Note that\nthe date range will cover the maximum date range across\nall `subtasks`. If date ranges vary widely it is advised\nto create separate tasks.\n\nFinally the `product` and `layer` columns denote the \nremote sensing product and particular layer to download.\nA full list of products can be queried using `rs_products()`,\nwhile the layers of a particular product can be listed\nusing `rs_layers()`. Note that the product needs to be\nspecified using the full product name, including the version\nof the product (as stored in the `ProductAndVersion` field).\n\nFor point and area based queries all data are saved in a\nsubdirectory of the main `path` as defined by the task name.\nAn abbreviated workflow can be found below, while a full\nworked example is provided in the vignettes.\n\n```r\n# Load the library\nlibrary(appeears)\n\n# list all products\nrs_products()\n\n# list layers of the MOD11A2.061 product\nrs_layers(\"MOD11A2.061\")\n\ndf \u003c- data.frame(\n  task = \"time_series\",\n  subtask = \"US-Ha1\",\n  latitude = 42.5378,\n  longitude = -72.1715,\n  start = \"2010-01-01\",\n  end = \"2010-12-31\",\n  product = \"MCD43A4.061\",\n  layer = c(\"Nadir_Reflectance_Band3\",\"Nadir_Reflectance_Band4\")\n)\n\n# build the area based request/task\n# rename the task name so data will\n# be saved in the \"point\" folder\n# as defined by the task name\ntask \u003c- rs_build_task(df = df)\n\n# request the task to be executed\nrs_request(\n  request = task,\n  user = \"earth_data_user\",\n  transfer = TRUE,\n  path = \"~/some_path\",\n  verbose = TRUE\n)\n````\n\n### Area based data requests\n\nYou can select a region-of-interest (ROI) instead of point based data,\nusing both `sf` polygons or the extent (bounding box) of an existing\n`terra` `SpatRaster` object. Both methods follow the same workflow.\n\n#### {sf} polygon ROI\n\nWhen using an `sf` object, provide it to the `roi` argument of the\n`rs_build_task()` function. The `sf` object must be of class `sf` not `sfc`\nwhen required convert `sfc` data using `st_as_sf()`.\n\nNote however that at the time only as simple polygon is supported. Multiple \npolygons in the same `sf` object might result in failure to query the data.\n\nFurthermore, no other means will be provided to specify a region-of-interest.\nAs such, you will always have to query a region-of-interest using an `sf`\nobject. This ensures consistency across queries and allows for rapid visualization\nof a region of interest (in contrast to a simple list of e.g. top-left,\nbottom-right coordinates).\n\n```r\n# load the required libraries\nlibrary(appeears)\nlibrary(sf)\nlibrary(dplyr)\n\ndf \u003c- data.frame(\n  task = \"time_series\",\n  subtask = \"subtask\",\n  latitude = 42.5378,\n  longitude = -72.1715,\n  start = \"2010-01-01\",\n  end = \"2010-12-31\",\n  product = \"MCD12Q2.006\",\n  layer = c(\"Greenup\")\n)\n\n# load the north carolina demo data\n# included in the {sf} package\n# and only retain Camden county\nroi \u003c- st_read(system.file(\"gpkg/nc.gpkg\", package=\"sf\"), quiet = TRUE) |\u003e\n  filter(\n    NAME == \"Camden\"\n  )\n\n# build the area based request/task\n# rename the task name so data will\n# be saved in the \"polygon\" folder\n# as defined by the task name\ndf$task \u003c- \"polygon\"\ntask \u003c- rs_build_task(\n  df = df,\n  roi = roi,\n  format = \"geotiff\"\n)\n\n# request the task to be executed\nrs_request(\n  request = task,\n  user = \"earth_data_user\",\n  transfer = TRUE,\n  path = \"~/some_path\",\n  verbose = TRUE\n)\n```\n\n#### {terra} SpatRaster ROI\n\nThe `terra` based region-of-interest workflow is similar to that of `sf`\npolygon based queries. One only has to provide a `SpatRaster` as an `roi`\nargument in `rs_build_task()` to query a region of the same extent as the\n`SpatRaster`. The use case for this functionality is obvious, creating a quick\nway to sample new data for an existing data set (using the same coverage).\n\nNote that unlike the `sf` method a bounding box is used and masked data is\nignored (the full extent is downloaded and masking will have to be repeated\nafterwards).\n\n```r\n# load the required libraries\nlibrary(terra)\n\n# create a SpatRaster ROI from the terra demo file\nf \u003c- system.file(\"ex/elev.tif\", package=\"terra\")\nroi \u003c- terra::rast(f)\n\n# build the area based request/task\n# rename the task name so data will\n# be saved in the \"raster\" folder\n# as defined by the task name\ndf$task \u003c- \"raster\"\ntask \u003c- rs_build_task(\n  df = df,\n  roi = roi,\n  format = \"geotiff\"\n)\n\n# request the task to be executed\nrs_request(\n  request = task,\n  user = \"earth_data_user\",\n  transfer = TRUE,\n  path = \"~/some_path\",\n  verbose = TRUE\n)\n```\n\n# Acknowledgements\n\nThe `appeears` package is a product of BlueGreen Labs, and has been in part supported by the LEMONTREE project funded through the Schmidt Futures fund, under the umbrella of the Virtual Earth System Research Institute (VESRI).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluegreen-labs%2Fappeears","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluegreen-labs%2Fappeears","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluegreen-labs%2Fappeears/lists"}