From eab9180a2d7a3aa23ad65725e9fbb1d8c6849c51 Mon Sep 17 00:00:00 2001 From: vwmaus Date: Thu, 21 Sep 2023 20:47:16 +0200 Subject: [PATCH] Fixes vignette. Adds pkgdown workflow. --- .Rbuildignore | 3 ++ .github/workflows/pkgdown.yaml | 48 +++++++++++++++++++ DESCRIPTION | 2 +- README.md | 32 ++++++++----- vignettes.awk | 13 +++++ ...pping-01-stars.Rmd => landuse-mapping.Rmd} | 24 +++++----- 6 files changed, 96 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/pkgdown.yaml create mode 100644 vignettes.awk rename vignettes/{mapping-01-stars.Rmd => landuse-mapping.Rmd} (92%) diff --git a/.Rbuildignore b/.Rbuildignore index 314e13a..6cf7893 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -26,3 +26,6 @@ examples_x64 ^\.github$ ^doc$ ^Meta$ + +vignettes.awk +_pkgdown.yml \ No newline at end of file diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml new file mode 100644 index 0000000..ed7650c --- /dev/null +++ b/.github/workflows/pkgdown.yaml @@ -0,0 +1,48 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + branches: [main, master] + release: + types: [published] + workflow_dispatch: + +name: pkgdown + +jobs: + pkgdown: + runs-on: ubuntu-latest + # Only restrict concurrency for non-PR jobs + concurrency: + group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + permissions: + contents: write + steps: + - uses: actions/checkout@v3 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::pkgdown, local::. + needs: website + + - name: Build site + run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) + shell: Rscript {0} + + - name: Deploy to GitHub pages 🚀 + if: github.event_name != 'pull_request' + uses: JamesIves/github-pages-deploy-action@v4.4.1 + with: + clean: false + branch: gh-pages + folder: docs diff --git a/DESCRIPTION b/DESCRIPTION index 76e0c6b..f4ba85e 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: dtwSat Type: Package Title: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis Version: 1.0.0 -Date: 2023-09-20 +Date: 2023-09-21 Authors@R: c(person(given = "Victor", family = "Maus", diff --git a/README.md b/README.md index a4f1117..031f02c 100644 --- a/README.md +++ b/README.md @@ -12,31 +12,37 @@ +Provides a robust approach to land use mapping using multi-dimensional +(multi-band) satellite image time series. By leveraging the Time-Weighted Dynamic +Time Warping (TWDTW) distance metric in tandem with a 1 Nearest-Neighbor (1-NN) Classifier, +this package offers functions to produce land use maps based on distinct seasonality patterns, +commonly observed in the phenological cycles of vegetation. The approach is described in +Maus et al. (2016) and Maus et al. (2019). +A primary advantage of TWDTW is its capability to handle irregularly sampled and noisy time series, +while also requiring minimal training sets. The package includes tools for training the 1-NN-TWDTW model, +visualizing temporal patterns, producing land use maps, and visualizing the results. -### Time-Weighted Dynamic Time Warping for satellite image time series analysis +## Getting Started -The package *dtwSat* provides an implementation of the Time-Weighted -Dynamic Time Warping (TWDTW) method for land cover mapping using -multi-band satellite image time series (Maus et al. 2016, 2019). -*dtwSat* provides full cycle of land cover classification using image -time series, ranging from selecting temporal patterns to visualizing, -and assessing the results. - -## Installing - -Install either from CRAN +You can install dtwSat from CRAN using the following command: ``` r install.packages("dtwSat") ``` -or install the development versions from GitHub +Alternatively, you can install the development version from GitHub: ``` r -library(devtools) devtools::install_github("vwmaus/dtwSat") ``` +After installation, you can read the vignette for a quick start guide: + +``` r +vignette("landuse-mapping", "dtwSat") +``` + + ## References
diff --git a/vignettes.awk b/vignettes.awk new file mode 100644 index 0000000..0517265 --- /dev/null +++ b/vignettes.awk @@ -0,0 +1,13 @@ +{ + if (NR == 4) { + print("output: rmarkdown::html_vignette") + } else if (NR > 4 && NR <= 10) { + } else if (NR == 16) { + print("\n**For a better version of the dtwSat vignettes see** https://vwmaus.github.io/dtwSat/articles/\n") + } else if (NR == 19) { + print + print("knitr::opts_chunk$set(fig.height = 4.5)") + print("knitr::opts_chunk$set(fig.width = 6)") + } else + print +} diff --git a/vignettes/mapping-01-stars.Rmd b/vignettes/landuse-mapping.Rmd similarity index 92% rename from vignettes/mapping-01-stars.Rmd rename to vignettes/landuse-mapping.Rmd index 1085c05..1954cdd 100644 --- a/vignettes/mapping-01-stars.Rmd +++ b/vignettes/landuse-mapping.Rmd @@ -15,8 +15,9 @@ vignette: > bibliography: ./../inst/REFERENCES.bib --- -```{r, echo=FALSE, include=FALSE} -knitr::opts_chunk$set(collapse = TRUE) + +```{r setup, include=FALSE} +knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, dev = "png") ``` This vignette offers a concise guide for using version 1.0.0 or higher of the `dtwSat` package to generate a land-use map. @@ -24,7 +25,7 @@ The package utilizes Time-Weighted Dynamic Time Warping (TWDTW) along with a 1-N The subsequent sections will walk you through the process of creating a land-use map based on a set of training samples and a multi-band satellite image time series. -# Reading Training Samples +## Reading Training Samples First, let's read a set of training samples that come with the `dtwSat` package installation. @@ -35,7 +36,7 @@ samples <- system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat") |> st_read(quiet = TRUE) ``` -# Preparing the Satellite Image Time Series +## Preparing the Satellite Image Time Series The `dtwSat` package supports satellite images read into R using the `stars` package. The instalation comes with a set of MOD13Q1 images for a region within the Brazilian Amazon. @@ -61,15 +62,14 @@ dc <- read_stars(tif_files, along = list(time = acquisition_date), RasterIO = list(bands = 1:6)) |> st_set_dimensions(3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) |> - split(c("band")) |> - split(c("time")) + split(c("band")) ``` Note that it's important to set the date for each observation using the parameter `along`. -This will produce a 4D array (data-cube) that will be collapsed into a 2D array by splitting -the 'band' and 'time' dimensions. This prepares the data for training the TWDTW-1NN model. +This will produce a 4D array (data-cube) that will be collapsed into a 3D array by converting +the 'band' dimension into attributes. This prepares the data for training the TWDTW-1NN model. -# Create TWDTW-KNN1 model +## Create TWDTW-KNN1 model ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} twdtw_model <- twdtw_knn1(x = dc, @@ -92,7 +92,7 @@ plot(twdtw_model) ``` -# Land Use Prediction +## Land Use Prediction Finally, we predict the land-use classes for each pixel location in the data-cube: @@ -118,7 +118,7 @@ Ultimately, we can write the map to a TIFF file we can use: write_stars(lu_map, "lu_map.tif") ``` -# Further Reading +## Further Reading This introduction outlined the use of `dtwSat` for land-use mapping. For more in-depth information, refer to the papers by @Maus:2016 and @Maus:2019 and the @@ -127,4 +127,4 @@ For more in-depth information, refer to the papers by @Maus:2016 and @Maus:2019 For additional details on how to manage input and output satellite images, [`check` the stars documentation](https://cran.r-project.org/web/packages/stars). -# References +## References