├── .Rbuildignore ├── .github ├── .gitignore └── workflows │ ├── R-CMD-check.yaml │ ├── pkgdown.yaml │ └── test-coverage.yaml ├── .gitignore ├── DESCRIPTION ├── LICENSE.md ├── NAMESPACE ├── NEWS.md ├── R ├── plot.R ├── predict.R ├── prepare_time_series.R ├── shift_dates.R ├── train.R └── zzz.R ├── README.md ├── _pkgdown.yml ├── cran-comments.md ├── inst ├── .gitignore ├── CITATION ├── REFERENCES.bib └── mato_grosso_brazil │ ├── MOD13Q1_20110914_subset_from_h12v10.tif │ ├── MOD13Q1_20110930_subset_from_h12v10.tif │ ├── MOD13Q1_20111016_subset_from_h12v10.tif │ ├── MOD13Q1_20111101_subset_from_h12v10.tif │ ├── MOD13Q1_20111117_subset_from_h12v10.tif │ ├── MOD13Q1_20111203_subset_from_h12v10.tif │ ├── MOD13Q1_20111219_subset_from_h12v10.tif │ ├── MOD13Q1_20120101_subset_from_h12v10.tif │ ├── MOD13Q1_20120117_subset_from_h12v10.tif │ ├── MOD13Q1_20120202_subset_from_h12v10.tif │ ├── MOD13Q1_20120218_subset_from_h12v10.tif │ ├── MOD13Q1_20120305_subset_from_h12v10.tif │ ├── MOD13Q1_20120321_subset_from_h12v10.tif │ ├── MOD13Q1_20120406_subset_from_h12v10.tif │ ├── MOD13Q1_20120422_subset_from_h12v10.tif │ ├── MOD13Q1_20120508_subset_from_h12v10.tif │ ├── MOD13Q1_20120524_subset_from_h12v10.tif │ ├── MOD13Q1_20120609_subset_from_h12v10.tif │ ├── MOD13Q1_20120625_subset_from_h12v10.tif │ ├── MOD13Q1_20120711_subset_from_h12v10.tif │ ├── MOD13Q1_20120727_subset_from_h12v10.tif │ ├── MOD13Q1_20120812_subset_from_h12v10.tif │ ├── MOD13Q1_20120828_subset_from_h12v10.tif │ └── samples.gpkg ├── man ├── get_time_series_freq.Rd ├── plot.twdtw_knn1.Rd ├── predict.twdtw_knn1.Rd ├── prepare_time_series.Rd ├── pretty_arguments.Rd ├── print.twdtw_knn1.Rd ├── shift_dates.Rd └── twdtw_knn1.Rd ├── tests ├── testthat.R └── testthat │ └── test-twdtw_classify.R ├── vignettes.awk └── vignettes └── landuse-mapping.Rmd /.Rbuildignore: -------------------------------------------------------------------------------- 1 | ^.*\.Rproj$ 2 | ^\.Rproj\.user$ 3 | ^\vignettes$ 4 | ^examples/ 5 | 6 | # Other files 7 | README.md 8 | ^\.git/ 9 | .gitignore 10 | ^README\.Rmd$ 11 | ^figure$ 12 | ^.*\.png$ 13 | ^.*\.xml$ 14 | ^README-.*\.png$ 15 | ^cran-comments\.md$ 16 | TODO$ 17 | dtwSat-Ex_i386.Rout 18 | dtwSat-Ex_x64.Rout 19 | examples_i386 20 | examples_x64 21 | 22 | ^CRAN-RELEASE$ 23 | ^CRAN-SUBMISSION$ 24 | ^LICENSE\.md$ 25 | ^dtwSat\.Rproj$ 26 | ^\.github$ 27 | ^doc$ 28 | ^Meta$ 29 | 30 | vignettes.awk 31 | _pkgdown.yml 32 | ^_pkgdown\.yml$ 33 | ^docs$ 34 | ^pkgdown$ 35 | -------------------------------------------------------------------------------- /.github/.gitignore: -------------------------------------------------------------------------------- 1 | *.html 2 | -------------------------------------------------------------------------------- /.github/workflows/R-CMD-check.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | 9 | name: R-CMD-check 10 | 11 | jobs: 12 | R-CMD-check: 13 | runs-on: ${{ matrix.config.os }} 14 | 15 | name: ${{ matrix.config.os }} (${{ matrix.config.r }}) 16 | 17 | strategy: 18 | fail-fast: false 19 | matrix: 20 | config: 21 | - {os: macos-latest, r: 'release'} 22 | - {os: windows-latest, r: 'release'} 23 | - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'} 24 | - {os: ubuntu-latest, r: 'release'} 25 | - {os: ubuntu-latest, r: 'oldrel-1'} 26 | 27 | env: 28 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 29 | R_KEEP_PKG_SOURCE: yes 30 | 31 | steps: 32 | - uses: actions/checkout@v3 33 | 34 | - uses: r-lib/actions/setup-pandoc@v2 35 | 36 | - uses: r-lib/actions/setup-r@v2 37 | with: 38 | r-version: ${{ matrix.config.r }} 39 | http-user-agent: ${{ matrix.config.http-user-agent }} 40 | use-public-rspm: true 41 | 42 | - uses: r-lib/actions/setup-r-dependencies@v2 43 | with: 44 | extra-packages: any::rcmdcheck 45 | needs: check 46 | 47 | - uses: r-lib/actions/check-r-package@v2 48 | with: 49 | upload-snapshots: true 50 | -------------------------------------------------------------------------------- /.github/workflows/pkgdown.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | release: 9 | types: [published] 10 | workflow_dispatch: 11 | 12 | name: pkgdown 13 | 14 | jobs: 15 | pkgdown: 16 | runs-on: ubuntu-latest 17 | # Only restrict concurrency for non-PR jobs 18 | concurrency: 19 | group: pkgdown-${{ github.event_name != 'pull_request' || github.run_id }} 20 | env: 21 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 22 | permissions: 23 | contents: write 24 | steps: 25 | - uses: actions/checkout@v3 26 | 27 | - uses: r-lib/actions/setup-pandoc@v2 28 | 29 | - uses: r-lib/actions/setup-r@v2 30 | with: 31 | use-public-rspm: true 32 | 33 | - uses: r-lib/actions/setup-r-dependencies@v2 34 | with: 35 | extra-packages: any::pkgdown, local::. 36 | needs: website 37 | 38 | - name: Build site 39 | run: pkgdown::build_site_github_pages(new_process = FALSE, install = FALSE) 40 | shell: Rscript {0} 41 | 42 | - name: Deploy to GitHub pages 🚀 43 | if: github.event_name != 'pull_request' 44 | uses: JamesIves/github-pages-deploy-action@v4.4.1 45 | with: 46 | clean: false 47 | branch: gh-pages 48 | folder: docs 49 | -------------------------------------------------------------------------------- /.github/workflows/test-coverage.yaml: -------------------------------------------------------------------------------- 1 | # Workflow derived from https://github.com/r-lib/actions/tree/v2/examples 2 | # Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help 3 | on: 4 | push: 5 | branches: [main, master] 6 | pull_request: 7 | branches: [main, master] 8 | 9 | name: test-coverage 10 | 11 | jobs: 12 | test-coverage: 13 | runs-on: ubuntu-latest 14 | env: 15 | GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} 16 | 17 | steps: 18 | - uses: actions/checkout@v3 19 | 20 | - uses: r-lib/actions/setup-r@v2 21 | with: 22 | use-public-rspm: true 23 | 24 | - uses: r-lib/actions/setup-r-dependencies@v2 25 | with: 26 | extra-packages: any::covr 27 | needs: coverage 28 | 29 | - name: Test coverage 30 | run: | 31 | covr::codecov( 32 | quiet = FALSE, 33 | clean = FALSE, 34 | install_path = file.path(Sys.getenv("RUNNER_TEMP"), "package") 35 | ) 36 | shell: Rscript {0} 37 | 38 | - name: Show testthat output 39 | if: always() 40 | run: | 41 | ## -------------------------------------------------------------------- 42 | find ${{ runner.temp }}/package -name 'testthat.Rout*' -exec cat '{}' \; || true 43 | shell: bash 44 | 45 | - name: Upload test results 46 | if: failure() 47 | uses: actions/upload-artifact@v3 48 | with: 49 | name: coverage-test-failures 50 | path: ${{ runner.temp }}/package 51 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # History files 2 | .Rhistory 3 | .Rapp.history 4 | # Session Data files 5 | .RData 6 | # User-specific files 7 | .Ruserdata 8 | # Example code in package build process 9 | *-Ex.R 10 | # Output files from R CMD build 11 | /*.tar.gz 12 | # Output files from R CMD check 13 | /*.Rcheck/ 14 | # RStudio files 15 | .Rproj.user/ 16 | # produced vignettes 17 | vignettes/*.html 18 | vignettes/*.pdf 19 | # OAuth2 token, see https://github.com/hadley/httr/releases/tag/v0.3 20 | .httr-oauth 21 | # knitr and R markdown default cache directories 22 | *_cache/ 23 | /cache/ 24 | # Temporary files created by R markdown 25 | *.utf8.md 26 | *.knit.md 27 | # R Environment Variables 28 | .Renviron 29 | .Rproj.user 30 | .Rdata 31 | .DS_Store 32 | .quarto 33 | revdep/ 34 | CRAN-SUBMISSION 35 | 36 | # Other files 37 | src/symbols.rds 38 | *.o 39 | *.so 40 | /doc/ 41 | /Meta/ 42 | docs 43 | -------------------------------------------------------------------------------- /DESCRIPTION: -------------------------------------------------------------------------------- 1 | Package: dtwSat 2 | Type: Package 3 | Title: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis 4 | Version: 1.0-1 5 | Date: 2023-09-25 6 | Authors@R: 7 | c(person(given = "Victor", 8 | family = "Maus", 9 | role = c("aut", "cre"), 10 | email = "vwmaus1@gmail.com", 11 | comment = c(ORCID = "0000-0002-7385-4723")), 12 | person(given = "Marius", 13 | family = "Appel", 14 | role = c("ctb"), 15 | comment = c(ORCID = "0000-0001-5281-3896")), 16 | person(given = "Nikolas", 17 | family = "Kuschnig", 18 | role = c("ctb"), 19 | comment = c(ORCID = "0000-0002-6642-2543")), 20 | person(given = "Toni", 21 | family = "Giorgino", 22 | role = c("ctb"), 23 | comment = c(ORCID = "0000-0002-6642-2543")) 24 | ) 25 | Description: Provides a robust approach to land use mapping using multi-dimensional 26 | (multi-band) satellite image time series. By leveraging the Time-Weighted Dynamic 27 | Time Warping (TWDTW) distance metric in tandem with a 1 Nearest-Neighbor (1-NN) Classifier, 28 | this package offers functions to produce land use maps based on distinct seasonality patterns, 29 | commonly observed in the phenological cycles of vegetation. The approach is described in 30 | Maus et al. (2016) and Maus et al. (2019) . 31 | A primary advantage of TWDTW is its capability to handle irregularly sampled and noisy time series, 32 | while also requiring minimal training sets. The package includes tools for training the 1-NN-TWDTW model, 33 | visualizing temporal patterns, producing land use maps, and visualizing the results. 34 | License: GPL (>= 3) 35 | URL: https://github.com/vwmaus/dtwSat/ 36 | BugReports: https://github.com/vwmaus/dtwSat/issues/ 37 | Maintainer: Victor Maus 38 | VignetteBuilder: 39 | knitr 40 | Encoding: UTF-8 41 | Roxygen: list(markdown = TRUE) 42 | RoxygenNote: 7.2.3 43 | Depends: 44 | twdtw, 45 | sf, 46 | stars, 47 | ggplot2 48 | Imports: 49 | mgcv, 50 | stats, 51 | tidyr, 52 | proxy 53 | Suggests: 54 | knitr, 55 | rmarkdown, 56 | testthat (>= 3.0.0) 57 | Config/testthat/edition: 3 58 | Collate: 59 | 'plot.R' 60 | 'predict.R' 61 | 'prepare_time_series.R' 62 | 'shift_dates.R' 63 | 'train.R' 64 | 'zzz.R' 65 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | GNU General Public License 2 | ========================== 3 | 4 | _Version 3, 29 June 2007_ 5 | _Copyright © 2007 Free Software Foundation, Inc. <>_ 6 | 7 | Everyone is permitted to copy and distribute verbatim copies of this license 8 | document, but changing it is not allowed. 9 | 10 | ## Preamble 11 | 12 | The GNU General Public License is a free, copyleft license for software and other 13 | kinds of works. 14 | 15 | The licenses for most software and other practical works are designed to take away 16 | your freedom to share and change the works. By contrast, the GNU General Public 17 | License is intended to guarantee your freedom to share and change all versions of a 18 | program--to make sure it remains free software for all its users. We, the Free 19 | Software Foundation, use the GNU General Public License for most of our software; it 20 | applies also to any other work released this way by its authors. You can apply it to 21 | your programs, too. 22 | 23 | When we speak of free software, we are referring to freedom, not price. Our General 24 | Public Licenses are designed to make sure that you have the freedom to distribute 25 | copies of free software (and charge for them if you wish), that you receive source 26 | code or can get it if you want it, that you can change the software or use pieces of 27 | it in new free programs, and that you know you can do these things. 28 | 29 | To protect your rights, we need to prevent others from denying you these rights or 30 | asking you to surrender the rights. Therefore, you have certain responsibilities if 31 | you distribute copies of the software, or if you modify it: responsibilities to 32 | respect the freedom of others. 33 | 34 | For example, if you distribute copies of such a program, whether gratis or for a fee, 35 | you must pass on to the recipients the same freedoms that you received. You must make 36 | sure that they, too, receive or can get the source code. And you must show them these 37 | terms so they know their rights. 38 | 39 | Developers that use the GNU GPL protect your rights with two steps: **(1)** assert 40 | copyright on the software, and **(2)** offer you this License giving you legal permission 41 | to copy, distribute and/or modify it. 42 | 43 | For the developers' and authors' protection, the GPL clearly explains that there is 44 | no warranty for this free software. For both users' and authors' sake, the GPL 45 | requires that modified versions be marked as changed, so that their problems will not 46 | be attributed erroneously to authors of previous versions. 47 | 48 | Some devices are designed to deny users access to install or run modified versions of 49 | the software inside them, although the manufacturer can do so. This is fundamentally 50 | incompatible with the aim of protecting users' freedom to change the software. The 51 | systematic pattern of such abuse occurs in the area of products for individuals to 52 | use, which is precisely where it is most unacceptable. Therefore, we have designed 53 | this version of the GPL to prohibit the practice for those products. If such problems 54 | arise substantially in other domains, we stand ready to extend this provision to 55 | those domains in future versions of the GPL, as needed to protect the freedom of 56 | users. 57 | 58 | Finally, every program is threatened constantly by software patents. States should 59 | not allow patents to restrict development and use of software on general-purpose 60 | computers, but in those that do, we wish to avoid the special danger that patents 61 | applied to a free program could make it effectively proprietary. To prevent this, the 62 | GPL assures that patents cannot be used to render the program non-free. 63 | 64 | The precise terms and conditions for copying, distribution and modification follow. 65 | 66 | ## TERMS AND CONDITIONS 67 | 68 | ### 0. Definitions 69 | 70 | “This License” refers to version 3 of the GNU General Public License. 71 | 72 | “Copyright” also means copyright-like laws that apply to other kinds of 73 | works, such as semiconductor masks. 74 | 75 | “The Program” refers to any copyrightable work licensed under this 76 | License. Each licensee is addressed as “you”. “Licensees” and 77 | “recipients” may be individuals or organizations. 78 | 79 | To “modify” a work means to copy from or adapt all or part of the work in 80 | a fashion requiring copyright permission, other than the making of an exact copy. The 81 | resulting work is called a “modified version” of the earlier work or a 82 | work “based on” the earlier work. 83 | 84 | A “covered work” means either the unmodified Program or a work based on 85 | the Program. 86 | 87 | To “propagate” a work means to do anything with it that, without 88 | permission, would make you directly or secondarily liable for infringement under 89 | applicable copyright law, except executing it on a computer or modifying a private 90 | copy. Propagation includes copying, distribution (with or without modification), 91 | making available to the public, and in some countries other activities as well. 92 | 93 | To “convey” a work means any kind of propagation that enables other 94 | parties to make or receive copies. Mere interaction with a user through a computer 95 | network, with no transfer of a copy, is not conveying. 96 | 97 | An interactive user interface displays “Appropriate Legal Notices” to the 98 | extent that it includes a convenient and prominently visible feature that **(1)** 99 | displays an appropriate copyright notice, and **(2)** tells the user that there is no 100 | warranty for the work (except to the extent that warranties are provided), that 101 | licensees may convey the work under this License, and how to view a copy of this 102 | License. If the interface presents a list of user commands or options, such as a 103 | menu, a prominent item in the list meets this criterion. 104 | 105 | ### 1. Source Code 106 | 107 | The “source code” for a work means the preferred form of the work for 108 | making modifications to it. “Object code” means any non-source form of a 109 | work. 110 | 111 | A “Standard Interface” means an interface that either is an official 112 | standard defined by a recognized standards body, or, in the case of interfaces 113 | specified for a particular programming language, one that is widely used among 114 | developers working in that language. 115 | 116 | The “System Libraries” of an executable work include anything, other than 117 | the work as a whole, that **(a)** is included in the normal form of packaging a Major 118 | Component, but which is not part of that Major Component, and **(b)** serves only to 119 | enable use of the work with that Major Component, or to implement a Standard 120 | Interface for which an implementation is available to the public in source code form. 121 | A “Major Component”, in this context, means a major essential component 122 | (kernel, window system, and so on) of the specific operating system (if any) on which 123 | the executable work runs, or a compiler used to produce the work, or an object code 124 | interpreter used to run it. 125 | 126 | The “Corresponding Source” for a work in object code form means all the 127 | source code needed to generate, install, and (for an executable work) run the object 128 | code and to modify the work, including scripts to control those activities. However, 129 | it does not include the work's System Libraries, or general-purpose tools or 130 | generally available free programs which are used unmodified in performing those 131 | activities but which are not part of the work. For example, Corresponding Source 132 | includes interface definition files associated with source files for the work, and 133 | the source code for shared libraries and dynamically linked subprograms that the work 134 | is specifically designed to require, such as by intimate data communication or 135 | control flow between those subprograms and other parts of the work. 136 | 137 | The Corresponding Source need not include anything that users can regenerate 138 | automatically from other parts of the Corresponding Source. 139 | 140 | The Corresponding Source for a work in source code form is that same work. 141 | 142 | ### 2. Basic Permissions 143 | 144 | All rights granted under this License are granted for the term of copyright on the 145 | Program, and are irrevocable provided the stated conditions are met. This License 146 | explicitly affirms your unlimited permission to run the unmodified Program. The 147 | output from running a covered work is covered by this License only if the output, 148 | given its content, constitutes a covered work. This License acknowledges your rights 149 | of fair use or other equivalent, as provided by copyright law. 150 | 151 | You may make, run and propagate covered works that you do not convey, without 152 | conditions so long as your license otherwise remains in force. You may convey covered 153 | works to others for the sole purpose of having them make modifications exclusively 154 | for you, or provide you with facilities for running those works, provided that you 155 | comply with the terms of this License in conveying all material for which you do not 156 | control copyright. Those thus making or running the covered works for you must do so 157 | exclusively on your behalf, under your direction and control, on terms that prohibit 158 | them from making any copies of your copyrighted material outside their relationship 159 | with you. 160 | 161 | Conveying under any other circumstances is permitted solely under the conditions 162 | stated below. Sublicensing is not allowed; section 10 makes it unnecessary. 163 | 164 | ### 3. Protecting Users' Legal Rights From Anti-Circumvention Law 165 | 166 | No covered work shall be deemed part of an effective technological measure under any 167 | applicable law fulfilling obligations under article 11 of the WIPO copyright treaty 168 | adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention 169 | of such measures. 170 | 171 | When you convey a covered work, you waive any legal power to forbid circumvention of 172 | technological measures to the extent such circumvention is effected by exercising 173 | rights under this License with respect to the covered work, and you disclaim any 174 | intention to limit operation or modification of the work as a means of enforcing, 175 | against the work's users, your or third parties' legal rights to forbid circumvention 176 | of technological measures. 177 | 178 | ### 4. Conveying Verbatim Copies 179 | 180 | You may convey verbatim copies of the Program's source code as you receive it, in any 181 | medium, provided that you conspicuously and appropriately publish on each copy an 182 | appropriate copyright notice; keep intact all notices stating that this License and 183 | any non-permissive terms added in accord with section 7 apply to the code; keep 184 | intact all notices of the absence of any warranty; and give all recipients a copy of 185 | this License along with the Program. 186 | 187 | You may charge any price or no price for each copy that you convey, and you may offer 188 | support or warranty protection for a fee. 189 | 190 | ### 5. Conveying Modified Source Versions 191 | 192 | You may convey a work based on the Program, or the modifications to produce it from 193 | the Program, in the form of source code under the terms of section 4, provided that 194 | you also meet all of these conditions: 195 | 196 | * **a)** The work must carry prominent notices stating that you modified it, and giving a 197 | relevant date. 198 | * **b)** The work must carry prominent notices stating that it is released under this 199 | License and any conditions added under section 7. This requirement modifies the 200 | requirement in section 4 to “keep intact all notices”. 201 | * **c)** You must license the entire work, as a whole, under this License to anyone who 202 | comes into possession of a copy. This License will therefore apply, along with any 203 | applicable section 7 additional terms, to the whole of the work, and all its parts, 204 | regardless of how they are packaged. This License gives no permission to license the 205 | work in any other way, but it does not invalidate such permission if you have 206 | separately received it. 207 | * **d)** If the work has interactive user interfaces, each must display Appropriate Legal 208 | Notices; however, if the Program has interactive interfaces that do not display 209 | Appropriate Legal Notices, your work need not make them do so. 210 | 211 | A compilation of a covered work with other separate and independent works, which are 212 | not by their nature extensions of the covered work, and which are not combined with 213 | it such as to form a larger program, in or on a volume of a storage or distribution 214 | medium, is called an “aggregate” if the compilation and its resulting 215 | copyright are not used to limit the access or legal rights of the compilation's users 216 | beyond what the individual works permit. Inclusion of a covered work in an aggregate 217 | does not cause this License to apply to the other parts of the aggregate. 218 | 219 | ### 6. Conveying Non-Source Forms 220 | 221 | You may convey a covered work in object code form under the terms of sections 4 and 222 | 5, provided that you also convey the machine-readable Corresponding Source under the 223 | terms of this License, in one of these ways: 224 | 225 | * **a)** Convey the object code in, or embodied in, a physical product (including a 226 | physical distribution medium), accompanied by the Corresponding Source fixed on a 227 | durable physical medium customarily used for software interchange. 228 | * **b)** Convey the object code in, or embodied in, a physical product (including a 229 | physical distribution medium), accompanied by a written offer, valid for at least 230 | three years and valid for as long as you offer spare parts or customer support for 231 | that product model, to give anyone who possesses the object code either **(1)** a copy of 232 | the Corresponding Source for all the software in the product that is covered by this 233 | License, on a durable physical medium customarily used for software interchange, for 234 | a price no more than your reasonable cost of physically performing this conveying of 235 | source, or **(2)** access to copy the Corresponding Source from a network server at no 236 | charge. 237 | * **c)** Convey individual copies of the object code with a copy of the written offer to 238 | provide the Corresponding Source. This alternative is allowed only occasionally and 239 | noncommercially, and only if you received the object code with such an offer, in 240 | accord with subsection 6b. 241 | * **d)** Convey the object code by offering access from a designated place (gratis or for 242 | a charge), and offer equivalent access to the Corresponding Source in the same way 243 | through the same place at no further charge. You need not require recipients to copy 244 | the Corresponding Source along with the object code. If the place to copy the object 245 | code is a network server, the Corresponding Source may be on a different server 246 | (operated by you or a third party) that supports equivalent copying facilities, 247 | provided you maintain clear directions next to the object code saying where to find 248 | the Corresponding Source. Regardless of what server hosts the Corresponding Source, 249 | you remain obligated to ensure that it is available for as long as needed to satisfy 250 | these requirements. 251 | * **e)** Convey the object code using peer-to-peer transmission, provided you inform 252 | other peers where the object code and Corresponding Source of the work are being 253 | offered to the general public at no charge under subsection 6d. 254 | 255 | A separable portion of the object code, whose source code is excluded from the 256 | Corresponding Source as a System Library, need not be included in conveying the 257 | object code work. 258 | 259 | A “User Product” is either **(1)** a “consumer product”, which 260 | means any tangible personal property which is normally used for personal, family, or 261 | household purposes, or **(2)** anything designed or sold for incorporation into a 262 | dwelling. In determining whether a product is a consumer product, doubtful cases 263 | shall be resolved in favor of coverage. For a particular product received by a 264 | particular user, “normally used” refers to a typical or common use of 265 | that class of product, regardless of the status of the particular user or of the way 266 | in which the particular user actually uses, or expects or is expected to use, the 267 | product. A product is a consumer product regardless of whether the product has 268 | substantial commercial, industrial or non-consumer uses, unless such uses represent 269 | the only significant mode of use of the product. 270 | 271 | “Installation Information” for a User Product means any methods, 272 | procedures, authorization keys, or other information required to install and execute 273 | modified versions of a covered work in that User Product from a modified version of 274 | its Corresponding Source. The information must suffice to ensure that the continued 275 | functioning of the modified object code is in no case prevented or interfered with 276 | solely because modification has been made. 277 | 278 | If you convey an object code work under this section in, or with, or specifically for 279 | use in, a User Product, and the conveying occurs as part of a transaction in which 280 | the right of possession and use of the User Product is transferred to the recipient 281 | in perpetuity or for a fixed term (regardless of how the transaction is 282 | characterized), the Corresponding Source conveyed under this section must be 283 | accompanied by the Installation Information. But this requirement does not apply if 284 | neither you nor any third party retains the ability to install modified object code 285 | on the User Product (for example, the work has been installed in ROM). 286 | 287 | The requirement to provide Installation Information does not include a requirement to 288 | continue to provide support service, warranty, or updates for a work that has been 289 | modified or installed by the recipient, or for the User Product in which it has been 290 | modified or installed. Access to a network may be denied when the modification itself 291 | materially and adversely affects the operation of the network or violates the rules 292 | and protocols for communication across the network. 293 | 294 | Corresponding Source conveyed, and Installation Information provided, in accord with 295 | this section must be in a format that is publicly documented (and with an 296 | implementation available to the public in source code form), and must require no 297 | special password or key for unpacking, reading or copying. 298 | 299 | ### 7. Additional Terms 300 | 301 | “Additional permissions” are terms that supplement the terms of this 302 | License by making exceptions from one or more of its conditions. Additional 303 | permissions that are applicable to the entire Program shall be treated as though they 304 | were included in this License, to the extent that they are valid under applicable 305 | law. If additional permissions apply only to part of the Program, that part may be 306 | used separately under those permissions, but the entire Program remains governed by 307 | this License without regard to the additional permissions. 308 | 309 | When you convey a copy of a covered work, you may at your option remove any 310 | additional permissions from that copy, or from any part of it. (Additional 311 | permissions may be written to require their own removal in certain cases when you 312 | modify the work.) You may place additional permissions on material, added by you to a 313 | covered work, for which you have or can give appropriate copyright permission. 314 | 315 | Notwithstanding any other provision of this License, for material you add to a 316 | covered work, you may (if authorized by the copyright holders of that material) 317 | supplement the terms of this License with terms: 318 | 319 | * **a)** Disclaiming warranty or limiting liability differently from the terms of 320 | sections 15 and 16 of this License; or 321 | * **b)** Requiring preservation of specified reasonable legal notices or author 322 | attributions in that material or in the Appropriate Legal Notices displayed by works 323 | containing it; or 324 | * **c)** Prohibiting misrepresentation of the origin of that material, or requiring that 325 | modified versions of such material be marked in reasonable ways as different from the 326 | original version; or 327 | * **d)** Limiting the use for publicity purposes of names of licensors or authors of the 328 | material; or 329 | * **e)** Declining to grant rights under trademark law for use of some trade names, 330 | trademarks, or service marks; or 331 | * **f)** Requiring indemnification of licensors and authors of that material by anyone 332 | who conveys the material (or modified versions of it) with contractual assumptions of 333 | liability to the recipient, for any liability that these contractual assumptions 334 | directly impose on those licensors and authors. 335 | 336 | All other non-permissive additional terms are considered “further 337 | restrictions” within the meaning of section 10. If the Program as you received 338 | it, or any part of it, contains a notice stating that it is governed by this License 339 | along with a term that is a further restriction, you may remove that term. If a 340 | license document contains a further restriction but permits relicensing or conveying 341 | under this License, you may add to a covered work material governed by the terms of 342 | that license document, provided that the further restriction does not survive such 343 | relicensing or conveying. 344 | 345 | If you add terms to a covered work in accord with this section, you must place, in 346 | the relevant source files, a statement of the additional terms that apply to those 347 | files, or a notice indicating where to find the applicable terms. 348 | 349 | Additional terms, permissive or non-permissive, may be stated in the form of a 350 | separately written license, or stated as exceptions; the above requirements apply 351 | either way. 352 | 353 | ### 8. Termination 354 | 355 | You may not propagate or modify a covered work except as expressly provided under 356 | this License. Any attempt otherwise to propagate or modify it is void, and will 357 | automatically terminate your rights under this License (including any patent licenses 358 | granted under the third paragraph of section 11). 359 | 360 | However, if you cease all violation of this License, then your license from a 361 | particular copyright holder is reinstated **(a)** provisionally, unless and until the 362 | copyright holder explicitly and finally terminates your license, and **(b)** permanently, 363 | if the copyright holder fails to notify you of the violation by some reasonable means 364 | prior to 60 days after the cessation. 365 | 366 | Moreover, your license from a particular copyright holder is reinstated permanently 367 | if the copyright holder notifies you of the violation by some reasonable means, this 368 | is the first time you have received notice of violation of this License (for any 369 | work) from that copyright holder, and you cure the violation prior to 30 days after 370 | your receipt of the notice. 371 | 372 | Termination of your rights under this section does not terminate the licenses of 373 | parties who have received copies or rights from you under this License. If your 374 | rights have been terminated and not permanently reinstated, you do not qualify to 375 | receive new licenses for the same material under section 10. 376 | 377 | ### 9. Acceptance Not Required for Having Copies 378 | 379 | You are not required to accept this License in order to receive or run a copy of the 380 | Program. Ancillary propagation of a covered work occurring solely as a consequence of 381 | using peer-to-peer transmission to receive a copy likewise does not require 382 | acceptance. However, nothing other than this License grants you permission to 383 | propagate or modify any covered work. These actions infringe copyright if you do not 384 | accept this License. Therefore, by modifying or propagating a covered work, you 385 | indicate your acceptance of this License to do so. 386 | 387 | ### 10. Automatic Licensing of Downstream Recipients 388 | 389 | Each time you convey a covered work, the recipient automatically receives a license 390 | from the original licensors, to run, modify and propagate that work, subject to this 391 | License. You are not responsible for enforcing compliance by third parties with this 392 | License. 393 | 394 | An “entity transaction” is a transaction transferring control of an 395 | organization, or substantially all assets of one, or subdividing an organization, or 396 | merging organizations. If propagation of a covered work results from an entity 397 | transaction, each party to that transaction who receives a copy of the work also 398 | receives whatever licenses to the work the party's predecessor in interest had or 399 | could give under the previous paragraph, plus a right to possession of the 400 | Corresponding Source of the work from the predecessor in interest, if the predecessor 401 | has it or can get it with reasonable efforts. 402 | 403 | You may not impose any further restrictions on the exercise of the rights granted or 404 | affirmed under this License. For example, you may not impose a license fee, royalty, 405 | or other charge for exercise of rights granted under this License, and you may not 406 | initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging 407 | that any patent claim is infringed by making, using, selling, offering for sale, or 408 | importing the Program or any portion of it. 409 | 410 | ### 11. Patents 411 | 412 | A “contributor” is a copyright holder who authorizes use under this 413 | License of the Program or a work on which the Program is based. The work thus 414 | licensed is called the contributor's “contributor version”. 415 | 416 | A contributor's “essential patent claims” are all patent claims owned or 417 | controlled by the contributor, whether already acquired or hereafter acquired, that 418 | would be infringed by some manner, permitted by this License, of making, using, or 419 | selling its contributor version, but do not include claims that would be infringed 420 | only as a consequence of further modification of the contributor version. For 421 | purposes of this definition, “control” includes the right to grant patent 422 | sublicenses in a manner consistent with the requirements of this License. 423 | 424 | Each contributor grants you a non-exclusive, worldwide, royalty-free patent license 425 | under the contributor's essential patent claims, to make, use, sell, offer for sale, 426 | import and otherwise run, modify and propagate the contents of its contributor 427 | version. 428 | 429 | In the following three paragraphs, a “patent license” is any express 430 | agreement or commitment, however denominated, not to enforce a patent (such as an 431 | express permission to practice a patent or covenant not to sue for patent 432 | infringement). To “grant” such a patent license to a party means to make 433 | such an agreement or commitment not to enforce a patent against the party. 434 | 435 | If you convey a covered work, knowingly relying on a patent license, and the 436 | Corresponding Source of the work is not available for anyone to copy, free of charge 437 | and under the terms of this License, through a publicly available network server or 438 | other readily accessible means, then you must either **(1)** cause the Corresponding 439 | Source to be so available, or **(2)** arrange to deprive yourself of the benefit of the 440 | patent license for this particular work, or **(3)** arrange, in a manner consistent with 441 | the requirements of this License, to extend the patent license to downstream 442 | recipients. “Knowingly relying” means you have actual knowledge that, but 443 | for the patent license, your conveying the covered work in a country, or your 444 | recipient's use of the covered work in a country, would infringe one or more 445 | identifiable patents in that country that you have reason to believe are valid. 446 | 447 | If, pursuant to or in connection with a single transaction or arrangement, you 448 | convey, or propagate by procuring conveyance of, a covered work, and grant a patent 449 | license to some of the parties receiving the covered work authorizing them to use, 450 | propagate, modify or convey a specific copy of the covered work, then the patent 451 | license you grant is automatically extended to all recipients of the covered work and 452 | works based on it. 453 | 454 | A patent license is “discriminatory” if it does not include within the 455 | scope of its coverage, prohibits the exercise of, or is conditioned on the 456 | non-exercise of one or more of the rights that are specifically granted under this 457 | License. You may not convey a covered work if you are a party to an arrangement with 458 | a third party that is in the business of distributing software, under which you make 459 | payment to the third party based on the extent of your activity of conveying the 460 | work, and under which the third party grants, to any of the parties who would receive 461 | the covered work from you, a discriminatory patent license **(a)** in connection with 462 | copies of the covered work conveyed by you (or copies made from those copies), or **(b)** 463 | primarily for and in connection with specific products or compilations that contain 464 | the covered work, unless you entered into that arrangement, or that patent license 465 | was granted, prior to 28 March 2007. 466 | 467 | Nothing in this License shall be construed as excluding or limiting any implied 468 | license or other defenses to infringement that may otherwise be available to you 469 | under applicable patent law. 470 | 471 | ### 12. No Surrender of Others' Freedom 472 | 473 | If conditions are imposed on you (whether by court order, agreement or otherwise) 474 | that contradict the conditions of this License, they do not excuse you from the 475 | conditions of this License. If you cannot convey a covered work so as to satisfy 476 | simultaneously your obligations under this License and any other pertinent 477 | obligations, then as a consequence you may not convey it at all. For example, if you 478 | agree to terms that obligate you to collect a royalty for further conveying from 479 | those to whom you convey the Program, the only way you could satisfy both those terms 480 | and this License would be to refrain entirely from conveying the Program. 481 | 482 | ### 13. Use with the GNU Affero General Public License 483 | 484 | Notwithstanding any other provision of this License, you have permission to link or 485 | combine any covered work with a work licensed under version 3 of the GNU Affero 486 | General Public License into a single combined work, and to convey the resulting work. 487 | The terms of this License will continue to apply to the part which is the covered 488 | work, but the special requirements of the GNU Affero General Public License, section 489 | 13, concerning interaction through a network will apply to the combination as such. 490 | 491 | ### 14. Revised Versions of this License 492 | 493 | The Free Software Foundation may publish revised and/or new versions of the GNU 494 | General Public License from time to time. Such new versions will be similar in spirit 495 | to the present version, but may differ in detail to address new problems or concerns. 496 | 497 | Each version is given a distinguishing version number. If the Program specifies that 498 | a certain numbered version of the GNU General Public License “or any later 499 | version” applies to it, you have the option of following the terms and 500 | conditions either of that numbered version or of any later version published by the 501 | Free Software Foundation. If the Program does not specify a version number of the GNU 502 | General Public License, you may choose any version ever published by the Free 503 | Software Foundation. 504 | 505 | If the Program specifies that a proxy can decide which future versions of the GNU 506 | General Public License can be used, that proxy's public statement of acceptance of a 507 | version permanently authorizes you to choose that version for the Program. 508 | 509 | Later license versions may give you additional or different permissions. However, no 510 | additional obligations are imposed on any author or copyright holder as a result of 511 | your choosing to follow a later version. 512 | 513 | ### 15. Disclaimer of Warranty 514 | 515 | THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. 516 | EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 517 | PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER 518 | EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 519 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE 520 | QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE 521 | DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 522 | 523 | ### 16. Limitation of Liability 524 | 525 | IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY 526 | COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS 527 | PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, 528 | INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE 529 | PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE 530 | OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE 531 | WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 532 | POSSIBILITY OF SUCH DAMAGES. 533 | 534 | ### 17. Interpretation of Sections 15 and 16 535 | 536 | If the disclaimer of warranty and limitation of liability provided above cannot be 537 | given local legal effect according to their terms, reviewing courts shall apply local 538 | law that most closely approximates an absolute waiver of all civil liability in 539 | connection with the Program, unless a warranty or assumption of liability accompanies 540 | a copy of the Program in return for a fee. 541 | 542 | _END OF TERMS AND CONDITIONS_ 543 | 544 | ## How to Apply These Terms to Your New Programs 545 | 546 | If you develop a new program, and you want it to be of the greatest possible use to 547 | the public, the best way to achieve this is to make it free software which everyone 548 | can redistribute and change under these terms. 549 | 550 | To do so, attach the following notices to the program. It is safest to attach them 551 | to the start of each source file to most effectively state the exclusion of warranty; 552 | and each file should have at least the “copyright” line and a pointer to 553 | where the full notice is found. 554 | 555 | 556 | Copyright (C) 557 | 558 | This program is free software: you can redistribute it and/or modify 559 | it under the terms of the GNU General Public License as published by 560 | the Free Software Foundation, either version 3 of the License, or 561 | (at your option) any later version. 562 | 563 | This program is distributed in the hope that it will be useful, 564 | but WITHOUT ANY WARRANTY; without even the implied warranty of 565 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 566 | GNU General Public License for more details. 567 | 568 | You should have received a copy of the GNU General Public License 569 | along with this program. If not, see . 570 | 571 | Also add information on how to contact you by electronic and paper mail. 572 | 573 | If the program does terminal interaction, make it output a short notice like this 574 | when it starts in an interactive mode: 575 | 576 | Copyright (C) 577 | This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. 578 | This is free software, and you are welcome to redistribute it 579 | under certain conditions; type 'show c' for details. 580 | 581 | The hypothetical commands `show w` and `show c` should show the appropriate parts of 582 | the General Public License. Of course, your program's commands might be different; 583 | for a GUI interface, you would use an “about box”. 584 | 585 | You should also get your employer (if you work as a programmer) or school, if any, to 586 | sign a “copyright disclaimer” for the program, if necessary. For more 587 | information on this, and how to apply and follow the GNU GPL, see 588 | <>. 589 | 590 | The GNU General Public License does not permit incorporating your program into 591 | proprietary programs. If your program is a subroutine library, you may consider it 592 | more useful to permit linking proprietary applications with the library. If this is 593 | what you want to do, use the GNU Lesser General Public License instead of this 594 | License. But first, please read 595 | <>. 596 | -------------------------------------------------------------------------------- /NAMESPACE: -------------------------------------------------------------------------------- 1 | # Generated by roxygen2: do not edit by hand 2 | 3 | S3method(plot,twdtw_knn1) 4 | S3method(predict,twdtw_knn1) 5 | S3method(print,twdtw_knn1) 6 | export(shift_dates) 7 | export(twdtw_knn1) 8 | import(ggplot2) 9 | import(sf) 10 | import(stars) 11 | import(twdtw) 12 | importFrom(mgcv,gam) 13 | importFrom(mgcv,predict.gam) 14 | importFrom(mgcv,s) 15 | importFrom(proxy,dist) 16 | importFrom(stats,as.formula) 17 | importFrom(stats,predict) 18 | importFrom(stats,setNames) 19 | importFrom(tidyr,nest) 20 | importFrom(tidyr,pivot_longer) 21 | importFrom(tidyr,pivot_wider) 22 | importFrom(tidyr,unnest) 23 | -------------------------------------------------------------------------------- /NEWS.md: -------------------------------------------------------------------------------- 1 | # dtwSat v1.0.0 2 | 3 | ## Major Updates: 4 | 5 | * Dependency Updates: This release removes obsolete dependencies, notably raster, rgdal, and sp. 6 | 7 | * Reduced Dependencies: We have significantly minimized the number of package dependencies to streamline the installation and update process. 8 | 9 | * Spatial Data Handling with sf and stars: Spatial data handling has been overhauled. We've introduced support for the sf and stars packages to enhance this capability. 10 | 11 | * Improved Workflow Compatibility: The package now offers a workflow that aligns more seamlessly with other prevalent image classification workflows. 12 | 13 | # dtwSat v0.2.8 14 | 15 | * Adds faster implementation of TWDTW for logistic weight function 16 | 17 | * Fixes small bugs 18 | 19 | * Adds vignettes 20 | 21 | # dtwSat v0.2.7 22 | 23 | * Adds support to user defined TWDTW weight function 24 | 25 | * Drop support to parallel processing 26 | 27 | * Adds a minimalist function called twdtwReduceTime that is 3x faster than twdtwApply. This function can be used for high level parallel processing implemented by users 28 | 29 | # dtwSat v0.2.6 30 | 31 | * Fixes error in to - from : non-numeric argument to binary operator in "twdtwAssess" 32 | 33 | * Fixes bug in .twdtw fundtion 34 | 35 | * Adds function for fast time series classification "twdtw_reduce_time" (~3x faster than twdtwApply) 36 | 37 | # dtwSat v0.2.5 38 | 39 | * Adds dtwSat paper published on Journal of Statistical Software 40 | 41 | * Fixing bugs 42 | 43 | Fix error in plotAccuracy 44 | 45 | Generalizes twdwAssess to cases with only one map 46 | 47 | Fixes error in getTimeSeries due to time series with only one no observation 48 | 49 | # dtwSat v0.2.4 50 | 51 | * New features 52 | 53 | Include the function twdtwApplyParallel for TWDTW parallel processing using the package snow 54 | 55 | Include writeRaster for twdtwRaster class 56 | 57 | Improve tests and documentation 58 | 59 | Improve memory usage of twdtwApply 60 | 61 | Improve memory usage and speed of twdtwClassify 62 | 63 | Auto recognition of the argument "doy" to avoid naming the argument "doy = doy" 64 | 65 | * Fixing bugs 66 | 67 | Fix bug in twdtwAssess for class twdtwMatches 68 | 69 | Fix bug in twdtwRaster 70 | 71 | # dtwSat v0.2.3 72 | 73 | * New features 74 | 75 | Register TWDTW as a distance function into package proxy 76 | 77 | * Fixing bugs 78 | 79 | Fix typos in plot labels 80 | 81 | # dtwSat v0.2.2 Release Notes 82 | 83 | * New features 84 | 85 | New accuracy metrics (twdtwAssess) for classified map, including User's and Producer's accuracy, and area uncertainty. 86 | 87 | Include methods for accuracy visualization (plot and LaTeX tables) 88 | 89 | * Update data set names 90 | 91 | Rename the data sets in ordes to avoid future overwriting of functions and data sets. "example\_ts" replaced with "MOD13Q1.ts". Tthe data sets are now called: 92 | 93 | MOD13Q1.MT.yearly.patterns Data: patterns time series 94 | MOD13Q1.patterns.list Data: patterns time series 95 | MOD13Q1.ts Data: An example of satellite time series 96 | MOD13Q1.ts.labels Data: Labels of the satellite time series in MOD13Q1.ts 97 | MOD13Q1.ts.list 98 | 99 | * Fixing bugs 100 | 101 | Fix bug in twdtwApply wrong sign in 'by' argument 102 | 103 | Fix bug in time index for twdtwApply-twdtwRaster 104 | 105 | # dtwSat v0.2.1 Release Notes 106 | 107 | * Fix Solaris installation errors. 108 | 109 | # dtwSat v0.2.0 Release Notes 110 | 111 | * Include Fortran optimization 112 | 113 | This version includes functions written in Fortran. 114 | 115 | * Obsolete features 116 | 117 | The S4 class 'twdtw' no longer exists. 118 | 119 | * New features 120 | 121 | New S4 classes: twdtwTimeSeries, twdtwMatches, and twdtwRaster. 122 | 123 | plot methods for twdtwRaster object: 'maps', 'area', 'changes', and 'distance'. 124 | 125 | plot methods for twdtwTimeSeries objects: ''patterns'' and ''timeseries''. 126 | 127 | plot methods for twdtwMatches objects: ''paths'', ''matches'', ''alignments'', ''classification'', ''cost'', ''patterns'', and ''timeseries''. 128 | 129 | createPattern function to create temporal patterns based on set of time series. 130 | 131 | getTimeSeries extract time series from raster objects. 132 | 133 | twdtwApply apply the TWDTW analysis for raster and time series objects. 134 | 135 | 136 | # dtwSat v0.1.1 Release Notes 137 | 138 | * New features 139 | 140 | 'normalizeQuery' new normalization feature for TWDTW 141 | 142 | 'template.list' new dataset. List of template time series 143 | 144 | arguments 'from' and 'to' in 'classifyIntervals' updated to include 'character' or 'Dates' in in the format 'yyyy-mm-dd' 145 | 146 | Align query and template by name if names not null in 'twdtw' function 147 | 148 | * deprecated features 149 | 150 | argument 'x' from function 'waveletSmoothing' is deprecated and is scheduled to be removed in the next version. Please use 'timeseries' instead. 151 | 152 | argument 'template' from functions 'twdtw' and 'mtwdtw' is deprecated and is scheduled to be removed in the next version. Please use 'timeseries' instead. 153 | 154 | argument 'normalized' is deprecated and is scheduled to be removed in the next version from all methods 155 | 156 | 'createTimeSequence' is deprecated. Use 'getModisTimeSequence' instead. 157 | 158 | Fix function name. 'classfyIntervals' is deprecated. Use 'classifyIntervals' instead. 159 | 160 | * Fixing bugs 161 | 162 | Fix plot intervals in plotClassify 163 | 164 | replace range(x) for range(x, na.rm=TRUE) in all methods 165 | 166 | Bug fixed in cost matrix indexing 167 | 168 | 169 | # dtwSat v0.1.0 Release Notes 170 | 171 | * First version of dtwSat on CRAN 172 | 173 | # dtwSat v0.0.1 Release Notes 174 | 175 | * Earlier dtwSat development version 176 | -------------------------------------------------------------------------------- /R/plot.R: -------------------------------------------------------------------------------- 1 | #' Plot Patterns from twdtw-knn1 model 2 | #' 3 | #' This function visualizes time series patterns from the \code{"twdtw_knn1"} model. 4 | #' It produces a multi-faceted plot, where each facet represents a different time series 5 | #' label from the model's data. Within each facet, different bands or indices (attributes) 6 | #' are plotted as distinct lines, differentiated by color. 7 | #' 8 | #' @param x A model of class \code{"twdtw_knn1"}. 9 | #' 10 | #' @param bands A character vector specifying the bands or indices to plot. 11 | #' If NULL (default), all available bands or indices in the data will be plotted. 12 | #' 13 | #' @param ... Additional arguments passed to \code{\link[ggplot2]{ggplot}}. Currently not used. 14 | #' 15 | #' @return A \code{\link[ggplot2]{ggplot}} object displaying the time series patterns. 16 | #' 17 | #' @seealso twdtw_knn1 18 | #' 19 | #' @inherit twdtw_knn1 examples 20 | #' 21 | #' @export 22 | plot.twdtw_knn1 <- function(x, bands = NULL, ...) { 23 | 24 | # Convert the list of time series data into a long-format data.frame 25 | df <- x$data 26 | df$id <- 1:nrow(df) 27 | df <- unnest(df, cols = 'observations') 28 | 29 | # Select bands 30 | if(!is.null(bands)){ 31 | df <- df[c('id', 'time', 'label', bands)] 32 | } 33 | 34 | # Pivote data into long format for ggplot2 35 | df <- pivot_longer(df, !c('id', 'label', 'time'), names_to = "band", values_to = "value") 36 | 37 | # Construct the ggplot 38 | gp <- ggplot(df, aes(x = .data$time, y = .data$value, colour = .data$band, group = interaction(.data$id, .data$band))) + 39 | geom_line() + 40 | facet_wrap(~label) + 41 | theme(legend.position = "bottom") + 42 | guides(colour = guide_legend(title = "Bands")) + 43 | ylab("Value") + 44 | xlab("Time") 45 | 46 | return(gp) 47 | 48 | } 49 | -------------------------------------------------------------------------------- /R/predict.R: -------------------------------------------------------------------------------- 1 | #' Predict using the twdtw_knn1 model 2 | #' 3 | #' This function predicts the classes of new data using the Time Warped Dynamic Time Warping (TWDTW) 4 | #' method with a 1-nearest neighbor approach. The prediction is based on the minimum TWDTW distance 5 | #' to the known patterns stored in the `twdtw_knn1` model. 6 | #' 7 | #' @param object A `twdtw_knn1` model object generated by the `twdtw_knn1` function. 8 | #' @param newdata A data frame or similar object containing the new observations 9 | #' (time series data) to be predicted. 10 | #' @param ... Additional arguments passed to the \link[twdtw]{twdtw} function. 11 | #' If provided, they will overwrite twdtw arguments previously passed to \link[dtwSat]{twdtw_knn1}. 12 | #' 13 | #' @return A vector of predicted classes for the `newdata`. 14 | #' 15 | #' @seealso twdtw_knn1 16 | #' 17 | #' @inherit twdtw_knn1 examples 18 | #' 19 | #' @export 20 | predict.twdtw_knn1 <- function(object, newdata, ...){ 21 | 22 | # Update twdtw_args with new arguments passed via ... 23 | new_twdtw_args <- list(...) 24 | matching_twdtw_args <- intersect(names(new_twdtw_args), names(object$twdtw_args)) 25 | object$twdtw_args[matching_twdtw_args] <- new_twdtw_args[matching_twdtw_args] 26 | 27 | # Convert newdata to time series 28 | newdata_ts <- prepare_time_series(newdata) 29 | 30 | # Compute TWDTW distances 31 | distances <- sapply(object$data$observations, function(pattern){ 32 | sapply(newdata_ts$observations, function(ts) { 33 | do.call(proxy::dist, c(list(x = as.data.frame(ts), y = as.data.frame(pattern), method = 'twdtw'), object$twdtw_args)) 34 | }) 35 | }) 36 | 37 | # Find the nearest neighbor for each observation in newdata 38 | nearest_neighbor <- apply(distances, 1, which.min) 39 | 40 | # Return the predicted label for each observation based on the nearest neighbor 41 | return(factor(object$data$label[nearest_neighbor])) 42 | } 43 | -------------------------------------------------------------------------------- /R/prepare_time_series.R: -------------------------------------------------------------------------------- 1 | #' Prepare a Time Series Tibble from a 2D stars Object with Bands and Time Attributes 2 | #' 3 | #' This function reshapes a data frame, which has been converted from a stars object, into a nested wide tibble format. 4 | #' The stars object conversion often results in columns named in formats like "band.YYYY.MM.DD", "XYYYY.MM.DD.band", or "YYYY.MM.DD.band". 5 | #' 6 | #' @param x A data frame derived from a stars object containing time series data in wide format. 7 | #' The column names should adhere to one of the following formats: "band.YYYY.MM.DD", "XYYYY.MM.DD.band", or "YYYY.MM.DD.band". 8 | #' 9 | #' @return A nested tibble in wide format. Each row of the tibble corresponds to a unique 'ts_id' that maintains the order from the original stars object. 10 | #' The nested structure contains observations (time series) for each 'ts_id', including the 'time' of each observation, and individual bands are presented as separate columns. 11 | #' 12 | #' 13 | prepare_time_series <- function(x) { 14 | 15 | # Remove the 'geom' column if it exists 16 | x$geom <- NULL 17 | x$x <- NULL 18 | x$y <- NULL 19 | var_names <- names(x) 20 | var_names <- var_names[!var_names %in% 'label'] 21 | 22 | # Extract date and band information from the column names 23 | date_band <- do.call(rbind, lapply(var_names, function(name) { 24 | 25 | # Replace any hyphen with periods for consistent processing 26 | name <- gsub("-", "\\.", name) 27 | 28 | # Extract date and band info based on different name patterns 29 | if (grepl("^.+\\.\\d{4}\\.\\d{2}\\.\\d{2}$", name)) { 30 | date_str <- gsub("^.*?(\\d{4}\\.\\d{2}\\.\\d{2})$", "\\1", name) 31 | band_str <- gsub("^(.+)\\.\\d{4}\\.\\d{2}\\.\\d{2}$", "\\1", name) 32 | } 33 | else if (grepl("^X\\d{4}\\.\\d{2}\\.\\d{2}\\..+$", name)) { 34 | date_str <- gsub("^X(\\d{4}\\.\\d{2}\\.\\d{2})\\..+$", "\\1", name) 35 | band_str <- gsub("^X\\d{4}\\.\\d{2}\\.\\d{2}\\.(.+)$", "\\1", name) 36 | } 37 | else if (grepl("^\\d{4}\\.\\d{2}\\.\\d{2}\\..+$", name)) { 38 | date_str <- gsub("^(\\d{4}\\.\\d{2}\\.\\d{2})\\..+$", "\\1", name) 39 | band_str <- gsub("^\\d{4}\\.\\d{2}\\.\\d{2}\\.(.+)$", "\\1", name) 40 | } 41 | else { 42 | stop(paste("Unrecognized format in:", name)) 43 | } 44 | 45 | # Convert the date string to Date format 46 | date <- to_date_time(gsub("\\.", "-", date_str)) 47 | 48 | return(data.frame(time = date, band = band_str)) 49 | })) 50 | 51 | # Construct tiem sereis 52 | ns <- nrow(x) 53 | x$ts_id <- 1:ns 54 | if (!'label' %in% names(x)) { 55 | x$label <- NA 56 | } 57 | x <- pivot_longer(x, !c('ts_id', 'label'), names_to = 'band_date', values_to = 'value') 58 | x$band <- rep(date_band$band, ns) 59 | x$time <- rep(date_band$time, ns) 60 | x$band_date <- NULL 61 | result_df <- pivot_wider(x, id_cols = c('ts_id', 'label', 'time'), names_from = 'band', values_from = 'value') 62 | result_df <- nest(result_df, .by = c('ts_id', 'label'), .key = 'observations') 63 | 64 | return(result_df) 65 | 66 | } 67 | 68 | 69 | #### TO BE REMOVED: twdtw package will export this fucntion 70 | to_date_time <- function(x){ 71 | if (!inherits(x, c("Date", "POSIXt"))) { 72 | # check if all strings in the vector include hours, minutes, and seconds 73 | if (all(grepl("\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}", x))) { 74 | x <- try(as.POSIXct(x), silent = TRUE) 75 | } else { 76 | x <- try(as.Date(x), silent = TRUE) 77 | } 78 | if (inherits(x, "try-error")) { 79 | stop("Some elements of x could not be converted to a date or datetime format") 80 | } 81 | } 82 | return(x) 83 | } 84 | -------------------------------------------------------------------------------- /R/shift_dates.R: -------------------------------------------------------------------------------- 1 | #' Shift Dates to Start on a Specified Origin Year 2 | #' 3 | #' Shifts a vector of dates to start on the same day-of-year in a specified origin year 4 | #' while preserving the relative difference in days among the observations. 5 | #' This way the temporal pattern (e.g., seasonality) inherent to the original dates 6 | #' will also be preserved in the shifted dates. 7 | #' 8 | #' The primary goal of this function is to align a sequence of dates based on the day-of-year 9 | #' in a desired origin year. This can be particularly useful for comparing or visualizing 10 | #' two or more time series with different absolute dates but aiming to align them based on 11 | #' the day-of-year or another relative metric. 12 | #' 13 | #' @param x A vector of date strings or Date objects representing the sequence to shift. 14 | #' @param origin A date string or Date object specifying the desired origin year for the shifted dates. 15 | #' Default is "1970-01-01". 16 | #' 17 | #' @return A vector of Date objects with the shifted dates starting on the same day-of-year in the specified origin year. 18 | #' 19 | #' @examples 20 | #' 21 | #' x <- c("2011-09-14", "2011-09-30", "2011-10-16", "2011-11-01") 22 | #' 23 | #' shift_dates(x) 24 | #' 25 | #' @export 26 | shift_dates <- function(x, origin = "1970-01-01") { 27 | 28 | # Convert the input dates to Date objects 29 | x <- as.Date(x) 30 | 31 | # Extract the day-of-year from the first date in x 32 | doy <- as.numeric(format(x[1], "%j")) 33 | 34 | # Compute the new starting date in the origin year 35 | new_start <- as.Date(paste0(format(as.Date(origin), "%Y"), sprintf("-%03d", doy)), format="%Y-%j") 36 | 37 | # Determine the difference in days 38 | day_diff <- as.numeric(x[1] - new_start) 39 | 40 | # Adjust each date in x by this difference 41 | shifted_dates <- x - day_diff 42 | 43 | return(shifted_dates) 44 | } 45 | 46 | 47 | shift_ts_dates <- function(x) { 48 | x$time <- shift_dates(x$time) 49 | return(x) 50 | } 51 | -------------------------------------------------------------------------------- /R/train.R: -------------------------------------------------------------------------------- 1 | #' 2 | #' Train a KNN-1 TWDTW model with optional GAM resampling 3 | #' 4 | #' This function prepares a KNN-1 model with the Time Warp Dynamic Time Warping (TWDTW) algorithm. 5 | #' If a formula is provided, the training samples are resampled using Generalized Additive Models (GAM). 6 | #' 7 | #' @param x A three-dimensional stars object (x, y, time) with bands as attributes. 8 | #' @param y An sf object with the coordinates of the training points. 9 | #' @param time_weight A numeric vector with length two (steepness and midpoint of logistic weight) or a function. 10 | #' See details in \link[twdtw]{twdtw}. 11 | #' @param cycle_length The length of the cycle, e.g. phenological cycles. Details in \link[twdtw]{twdtw}. 12 | #' @param time_scale Specifies the time scale for the observations. Details in \link[twdtw]{twdtw}. 13 | #' @param formula Either NULL or a formula to reduce samples of the same label using Generalized Additive Models (GAM). 14 | #' Default is \code{band ~ s(time)}. See details. 15 | #' @param start_column Name of the column in y that indicates the start date. Default is 'start_date'. 16 | #' @param end_column Name of the column in y that indicates the end date. Default is 'end_date'. 17 | #' @param label_colum Name of the column in y containing land use labels. Default is 'label'. 18 | #' @param sampling_freq The time frequency for sampling, including the unit (e.g., '16 day'). 19 | #' If NULL, the function will infer the frequency. This parameter is only used if a formula is provided. 20 | #' @param ... Additional arguments passed to the \link[mgcv]{gam} function and to \link[twdtw]{twdtw} function. 21 | #' 22 | #' @details If \code{formula} is NULL, the KNN-1 model will retain all training samples. If a formula is passed (e.g., \code{band ~ \link[mgcv]{s}(time)}), 23 | #' then samples of the same label (land cover class) will be resampled using GAM. 24 | #' Resampling can significantly reduce prediction processing time. 25 | #' 26 | #' @return A 'twdtw_knn1' model containing the trained model information and the data used. 27 | #' 28 | #' @examples 29 | #' \dontrun{ 30 | #' 31 | #' # Read training samples 32 | #' samples_path <- 33 | #' system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat") 34 | #' 35 | #' samples <- st_read(samples_path, quiet = TRUE) 36 | #' 37 | #' # Get satellite image time sereis files 38 | #' tif_path <- system.file("mato_grosso_brazil", package = "dtwSat") 39 | #' tif_files <- dir(tif_path, pattern = "\\.tif$", full.names = TRUE) 40 | #' 41 | #' # Get acquisition dates 42 | #' acquisition_date <- regmatches(tif_files, regexpr("[0-9]{8}", tif_files)) 43 | #' acquisition_date <- as.Date(acquisition_date, format = "%Y%m%d") 44 | #' 45 | #' # Create a 3D datacube 46 | #' dc <- read_stars(tif_files, 47 | #' proxy = FALSE, 48 | #' along = list(time = acquisition_date), 49 | #' RasterIO = list(bands = 1:6)) 50 | #' dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 51 | #' dc <- split(dc, c("band")) 52 | #' 53 | #' # Create a knn1-twdtw model 54 | #' m <- twdtw_knn1(x = dc, 55 | #' y = samples, 56 | #' cycle_length = 'year', 57 | #' time_scale = 'day', 58 | #' time_weight = c(steepness = 0.1, midpoint = 50), 59 | #' formula = band ~ s(time)) 60 | #' 61 | #' print(m) 62 | #' 63 | #' # Visualize model patterns 64 | #' plot(m) 65 | #' 66 | #' # Classify satellite images 67 | #' system.time(lu <- predict(dc, model = m)) 68 | #' 69 | #' # Visualise land use classification 70 | #' ggplot() + 71 | #' geom_stars(data = lu) + 72 | #' theme_minimal() 73 | #' 74 | #' } 75 | #' @export 76 | twdtw_knn1 <- function(x, y, time_weight, cycle_length, time_scale, 77 | formula = NULL, start_column = 'start_date', 78 | end_column = 'end_date', label_colum = 'label', 79 | sampling_freq = NULL, ...){ 80 | 81 | # Check if x is a stars object with a time dimension 82 | if (!inherits(x, "stars") || dim(x)['time'] < 1 || length(dim(x)) != 3) { 83 | stop("x must be a three-dimensional stars object with a 'time' dimension") 84 | } 85 | 86 | x <- split(x, c("time")) 87 | 88 | # Check if y is an sf object with point geometry 89 | if (!inherits(y, "sf") || !all(st_is(y, "POINT"))) { 90 | stop("y must be an sf object with point geometry") 91 | } 92 | 93 | # check for minimum set of twdtw arguments 94 | if (!(is.function(time_weight) || (is.numeric(time_weight) && length(time_weight) == 2))) stop("'time_weight' should be either a function or a numeric vector with length two") 95 | if (is.null(cycle_length)) stop("The 'cycle_length' argument is missing.") 96 | if (is.null(time_scale)) stop("The 'time_scale' argument is missing for 'cycle_length' type character.") 97 | 98 | # Check for required columns in y 99 | required_columns <- c(start_column, end_column, label_colum) 100 | missing_columns <- setdiff(required_columns, names(y)) 101 | if (length(missing_columns) > 0) { 102 | stop(paste("Missing required columns in y:", paste(missing_columns, collapse = ", "))) 103 | } 104 | 105 | # adjust y column names 106 | st_geometry(y) <- 'geom' 107 | y <- y[, c(start_column, end_column, label_colum, 'geom')] 108 | 109 | # Convert columns to date-time 110 | y[, start_column] <- to_date_time(y[[start_column]]) 111 | y[, end_column] <- to_date_time(y[[end_column]]) 112 | 113 | # Prepare time series samples from stars object 114 | ts_data <- st_extract(x, y) 115 | ts_data$label <- y[[label_colum]] 116 | ts_data <- prepare_time_series(as.data.frame(ts_data)) 117 | ts_data$ts_id <- NULL 118 | 119 | if(!is.null(formula)) { 120 | 121 | # Check if formula has two 122 | if(length(all.vars(formula)) != 2) { 123 | stop("The formula should have only one predictor!") 124 | } 125 | 126 | # Determine sampling frequency 127 | if (is.null(sampling_freq)) { 128 | sampling_freq <- get_time_series_freq(ts_data) 129 | } 130 | 131 | # Shift dates 132 | ts_data$observations <- lapply(ts_data$observations, shift_ts_dates) 133 | 134 | # Split data frame by label 135 | ts_data <- unnest(ts_data, cols = 'observations') 136 | ts_data <- nest(ts_data, .by = 'label', .key = "observations") 137 | 138 | # Define GAM function 139 | gam_fun <- function(band, t, pred_t, formula, ...){ 140 | df <- setNames(list(band, as.numeric(t)), all.vars(formula)) 141 | pred_t[[all.vars(formula)[2]]] <- as.numeric(pred_t[[all.vars(formula)[2]]]) 142 | fit <- mgcv::gam(data = df, formula = formula, ...) 143 | predict(fit, newdata = pred_t) 144 | } 145 | 146 | # Apply GAM function 147 | ts_data$observations <- lapply(ts_data$observations, function(ts){ 148 | y_time <- ts$time 149 | ts$time <- NULL 150 | pred_time <- setNames(list(seq(min(y_time), max(y_time), by = sampling_freq)), all.vars(formula)[2]) 151 | cbind(pred_time, as.data.frame(sapply(as.list(ts), function(band) { 152 | gam_fun(band, y_time, pred_time, formula, ...) 153 | }))) 154 | }) 155 | 156 | } 157 | 158 | model <- list() 159 | model$call <- match.call() 160 | model$formula <- formula 161 | model$data <- ts_data 162 | # add twdtw arguments to model 163 | model$twdtw_args <- list(time_weight = time_weight, 164 | cycle_length = cycle_length, 165 | time_scale = time_scale, 166 | origin = NULL, 167 | max_elapsed = Inf, 168 | version = "f90") 169 | new_twdtw_args <- list(...) 170 | matching_twdtw_args <- intersect(names(model$twdtw_args), names(new_twdtw_args)) 171 | model$twdtw_args[matching_twdtw_args] <- new_twdtw_args[matching_twdtw_args] 172 | 173 | class(model) <- "twdtw_knn1" 174 | 175 | return(model) 176 | 177 | } 178 | 179 | #' Print method for objects of class twdtw_knn1 180 | #' 181 | #' This method provides a structured printout of the important components 182 | #' of a `twdtw_knn1` object. 183 | #' 184 | #' @param x An object of class `twdtw_knn1`. 185 | #' @param ... ignored 186 | #' 187 | #' @return Invisible `twdtw_knn1` object. 188 | #' 189 | #' @export 190 | print.twdtw_knn1 <- function(x, ...) { 191 | cat("\nModel of class 'twdtw_knn1'\n") 192 | cat("-----------------------------\n") 193 | 194 | # Printing the call 195 | cat("Call:\n") 196 | print(x$call) 197 | 198 | # Printing the formula, if available 199 | cat("\nFormula:\n") 200 | print(x$formula) 201 | 202 | # Printing the data summary 203 | cat("\nData:\n") 204 | print(x$data) 205 | 206 | # Printing twdtw arguments 207 | cat("\nTWDTW Arguments:\n") 208 | pretty_arguments(x$twdtw_args) 209 | 210 | invisible(x) # Returns the object invisibly, so it doesn't print twice 211 | } 212 | 213 | #' Print Pretty Arguments 214 | #' 215 | #' Display a list of arguments of a given function in a human-readable format. 216 | #' 217 | #' @param args A list of named arguments to display. 218 | #' 219 | #' @return Invisible NULL. The function is mainly used for its side effect of printing. 220 | #' 221 | #' @examples 222 | #' \dontrun{ 223 | #' pretty_arguments(formals(twdtw_knn1)) 224 | #' } 225 | #' 226 | pretty_arguments <- function(args) { 227 | 228 | if (is.null(args)) { 229 | cat("Arguments are missing.\n") 230 | return(invisible(NULL)) 231 | } 232 | 233 | for (name in names(args)) { 234 | default_value <- args[[name]] 235 | 236 | if (is.symbol(default_value)) { 237 | default_value <- as.character(default_value) 238 | 239 | } else if (is.null(default_value)) { 240 | default_value <- "NULL" 241 | 242 | } else if (is.vector(default_value) && !is.null(names(default_value))) { 243 | # Handle named vectors 244 | values <- paste(names(default_value), default_value, sep = "=", collapse = ", ") 245 | default_value <- paste0("c(", values, ")") 246 | } 247 | cat(paste0(" - ", name, ": ", default_value, "\n")) 248 | } 249 | } 250 | 251 | 252 | 253 | #' Compute the Most Common Sampling Frequency across all observations 254 | #' 255 | #' This function calculates the most common difference between consecutive time points. 256 | #' This can be useful for determining the aproximate sampling frequency of the time series data. 257 | #' 258 | #' @param x A data frame including a column called `observations`` with the time series 259 | #' 260 | #' @return A difftime object representing the most common time difference between consecutive samples. 261 | #' 262 | get_time_series_freq <- function(x) { 263 | 264 | # Extract the time dimension 265 | time_values <- unlist(lapply(x$observations, function(ts) ts$time)) 266 | 267 | # Compute the differences between consecutive time points 268 | time_diffs <- unlist(lapply(x$observations, function(ts) diff(ts$time))) 269 | 270 | # Convert differences to days (while retaining the difftime class) 271 | time_diffs <- as.difftime(time_diffs, units = "days") 272 | 273 | # Identify the mode 274 | mode_val_index <- which.max(tabulate(match(time_diffs, unique(time_diffs)))) 275 | freq <- diff(time_values[mode_val_index:(mode_val_index+1)]) 276 | 277 | return(freq) 278 | 279 | } 280 | -------------------------------------------------------------------------------- /R/zzz.R: -------------------------------------------------------------------------------- 1 | #' @import twdtw 2 | #' @import sf 3 | #' @import stars 4 | #' @import ggplot2 5 | #' @importFrom stats as.formula predict setNames 6 | #' @importFrom mgcv gam s predict.gam 7 | #' @importFrom tidyr pivot_longer pivot_wider nest unnest 8 | #' @importFrom proxy dist 9 | #' 10 | NULL 11 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # dtwSat 2 | 3 | 4 | [![License](https://img.shields.io/badge/license-GPL%20%28%3E=%202%29-brightgreen.svg?style=flat)](https://www.gnu.org/licenses/gpl-3.0.html) 5 | [![R-CMD-check](https://github.com/vwmaus/dtwSat/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/vwmaus/dtwSat/actions/workflows/R-CMD-check.yaml) 6 | [![Coverage Status](https://img.shields.io/codecov/c/github/vwmaus/dtwSat/main.svg)](https://app.codecov.io/gh/vwmaus/dtwSat) 7 | [![CRAN](https://www.r-pkg.org/badges/version/dtwSat)](https://cran.r-project.org/package=dtwSat) 8 | [![Downloads](https://cranlogs.r-pkg.org/badges/dtwSat?color=brightgreen)](https://www.r-pkg.org/pkg/dtwSat) 9 | [![total](http://cranlogs.r-pkg.org/badges/grand-total/dtwSat)](http://www.r-pkg.org/pkg/dtwSat) 10 | [![cran checks](https://badges.cranchecks.info/worst/dtwSat.svg)](https://cran.r-project.org/web/checks/check_results_dtwSat.html) 11 | [![status](https://tinyverse.netlify.com/badge/dtwSat)](https://CRAN.R-project.org/package=dtwSat) 12 | 13 | 14 | 15 | Provides a robust approach to land use mapping using multi-dimensional 16 | (multi-band) satellite image time series. By leveraging the Time-Weighted Dynamic 17 | Time Warping (TWDTW) distance metric in tandem with a 1 Nearest-Neighbor (1-NN) Classifier, 18 | this package offers functions to produce land use maps based on distinct seasonality patterns, 19 | commonly observed in the phenological cycles of vegetation. The approach is described in 20 | Maus et al. (2016) and Maus et al. (2019). 21 | A primary advantage of TWDTW is its capability to handle irregularly sampled and noisy time series, 22 | while also requiring minimal training sets. The package includes tools for training the 1-NN-TWDTW model, 23 | visualizing temporal patterns, producing land use maps, and visualizing the results. 24 | 25 | ## Getting Started 26 | 27 | You can install dtwSat from CRAN using the following command: 28 | 29 | ``` r 30 | install.packages("dtwSat") 31 | ``` 32 | 33 | Alternatively, you can install the development version from GitHub: 34 | 35 | ``` r 36 | devtools::install_github("vwmaus/dtwSat") 37 | ``` 38 | 39 | After installation, you can read the vignette for a quick start guide: 40 | 41 | ``` r 42 | vignette("landuse-mapping", "dtwSat") 43 | ``` 44 | 45 | 46 | ## References 47 | 48 |
49 | 50 |
51 | 52 | Maus, Victor, Gilberto Camara, Marius Appel, and Edzer Pebesma. 2019. 53 | “dtwSat: Time-Weighted Dynamic Time Warping 54 | for Satellite Image Time Series Analysis in R.” *Journal of Statistical 55 | Software* 88 (5): 1–31. . 56 | 57 |
58 | 59 |
60 | 61 | Maus, Victor, Gilberto Camara, Ricardo Cartaxo, Alber Sanchez, Fernando 62 | M. Ramos, and Gilberto R. de Queiroz. 2016. “A Time-Weighted Dynamic 63 | Time Warping Method for Land-Use and Land-Cover Mapping.” *IEEE Journal 64 | of Selected Topics in Applied Earth Observations and Remote Sensing* 9 65 | (8): 3729–39. . 66 | 67 |
68 | 69 |
70 | -------------------------------------------------------------------------------- /_pkgdown.yml: -------------------------------------------------------------------------------- 1 | url: http://www.victor-maus.com/dtwSat/ 2 | template: 3 | bootstrap: 5 4 | 5 | -------------------------------------------------------------------------------- /cran-comments.md: -------------------------------------------------------------------------------- 1 | # Test environments 2 | 3 | * win-builder 4 | devtools::check_win_release() 5 | devtools::check_win_devel() 6 | devtools::check_win_oldrelease() 7 | 8 | * R-hub 9 | rhub::check_for_cran(check_args = '--as-cran') 10 | rhub::check_for_cran(check_args = '--as-cran', valgrind = TRUE) 11 | 12 | * Local Ubuntu 22.04.1 LTS x86_64-pc-linux-gnu (64-bit), R 4.3.1 (2023-06-16) 13 | devtools::check(args = '--as-cran') 14 | devtools::submit_cran() 15 | 16 | # REVIEWS 17 | 18 | ## v1.0.0 19 | 20 | * Major release that removes obsolete dependencies, such as raster, rgdal, and sp. 21 | 22 | * Substantially reduced the number of dependencies. 23 | 24 | * Introduced sf and stars for spatial data handling. 25 | 26 | * Provided a workflow compatible with other image classification workflows. 27 | 28 | 29 | 30 | 31 | ## v0.2.8 32 | 33 | * Fixes errors from https://cran.r-project.org/web/checks/check_results_dtwSat.html 34 | 35 | * Speed improvements 36 | 37 | ## v0.2.7 38 | 39 | * Fixes error in cost TWDTW weighting function 40 | 41 | * Drop support to parallel processing 42 | 43 | * Drop projection method for twdtwRaster class as it was used only internally 44 | 45 | * Fixes errors from https://cran.r-project.org/web/checks/check_results_dtwSat.html 46 | 47 | ## v0.2.6 48 | 49 | * Fixes warnings from https://cran.r-project.org/web/checks/check_results_dtwSat.html 50 | 51 | ## v0.2.5 52 | 53 | * The DOI in the CITATION is for a new JSS publication that will be registered after publication on CRAN. 54 | 55 | ## v0.2.4 56 | 57 | ## v0.2.3 58 | 59 | * Fix check error 60 | checking re-building of vignette outputs ... [1s/1s] WARNING 61 | Error in re-building vignettes: 62 | ... 63 | 64 | ## v0.2.2 65 | 66 | ## v0.2.1 67 | 68 | * Fix Solaris installation errors. 69 | Replacing the GNU extension ISNAN with pure Fortran code to check for NAN. 70 | 71 | ## v0.2.0 72 | 73 | * Single quote software names in the Descriptoin. 74 | 75 | - Using dtwSat the user 76 | + Using 'dtwSat' the user 77 | 78 | * Please reduce to < 5 MB, I do not believe this is not possible. 79 | 80 | gdal_translate COMPRESS=DEFLATE reduced the size of the tiff files. 81 | 82 | * build_win() latex compilation error: 83 | 84 | I have successfully built and compiled the latex of the vignette using a personal Windows machine. However, 'build_win' gives an error while compiling the latex of vignette. The error message given by the server is unclear to me: 85 | 86 | * checking re-building of vignette outputs ... WARNING 87 | 88 | Error in re-building vignettes: 89 | 90 | ... 91 | 92 | Error: processing vignette 'applying_twdtw.Rmd' failed with diagnostics: 93 | 94 | Failed to compile applying_twdtw.tex. 95 | 96 | Execution halted 97 | 98 | 99 | 100 | 101 | 102 | There were no ERRORs or WARNINGs. 103 | 104 | There was 1 NOTE: 105 | 106 | * checking installed package size ... NOTE 107 | installed size is 7.3Mb 108 | sub-directories of 1Mb or more: 109 | lucc_MT 6.1Mb 110 | 111 | This version includes 'tif' files used to reproduce the examples in the vignette and documentation. The data set is the smallest that is still meaningful for a spatiotemporal analysis of land cover changes. This examples and data sets are crutial for the user to learn how to use the package. 112 | 113 | * Optimization 114 | 115 | + Fortran code for optimization. 116 | 117 | ## v0.1.0 118 | 119 | * authors / copyright holder 120 | 121 | - C code removed from the package 122 | 123 | * checking R code for possible problems ... NOTE 124 | plotCostMatrix: no visible global function definition for 'gray.colors' 125 | 126 | + importFrom("grDevices", "gray.colors") added to NAMESPACE 127 | 128 | * DESCRIPTION file 129 | 130 | - Description: The dtwSat provides ... 131 | + Description: Provides ... 132 | 133 | * Functions documentation 134 | 135 | General review in the documentation. 136 | 137 | 138 | ## R CMD check --as-cran results 139 | There were no ERRORs or WARNINGs. 140 | 141 | There was 1 NOTE: 142 | 143 | * checking CRAN incoming feasibility ... NOTE 144 | Maintainer: 'Victor Maus ' 145 | New submission 146 | 147 | This is my first submission. 148 | -------------------------------------------------------------------------------- /inst/.gitignore: -------------------------------------------------------------------------------- 1 | *.xml -------------------------------------------------------------------------------- /inst/CITATION: -------------------------------------------------------------------------------- 1 | bibentry(bibtype = "Article", 2 | title = "{dtwSat}: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis in {R}", 3 | author = c(person(given = "Victor", 4 | family = "Maus", 5 | email = "mailto:vwmaus1@gmail.com"), 6 | person(given = "Gilberto", 7 | family = "C{\\^a}mara"), 8 | person(given = "Marius", 9 | family = "Appel"), 10 | person(given = "Edzer", 11 | family = "Pebesma")), 12 | journal = "Journal of Statistical Software", 13 | year = "2019", 14 | volume = "88", 15 | number = "5", 16 | pages = "1--31", 17 | doi = "10.18637/jss.v088.i05", 18 | header = "To cite dtwSat in publications use:" 19 | ) 20 | 21 | bibentry(bibtype = "Article", 22 | title = "A Time-Weighted Dynamic Time Warping Method for Land-Use and Land-Cover Mapping", 23 | author = c(person(given = "Victor", 24 | family = "Maus", 25 | email = "mailto:vwmaus1@gmail.com"), 26 | person(given = "Gilberto", 27 | family = "C{\\^a}mara"), 28 | person(given = "Ricardo", 29 | family = "Cartaxo"), 30 | person(given = "Alber", 31 | family = "Sanchez"), 32 | person(given = "Fernando M.", 33 | family = "Ramos"), 34 | person(given = "Gilberto R.", 35 | family = "de Queiroz")), 36 | journal = "Selected Topics in Applied Earth Observations and Remote Sensing, IEEE Journal of", 37 | year = "2016", 38 | volume = "9", 39 | number = "8", 40 | pages = "3729--3739", 41 | doi = "10.1109/JSTARS.2016.2517118", 42 | ISSN = "1939-1404", 43 | month = "Aug", 44 | header = "To cite TWDTW method in publications use:" 45 | ) 46 | 47 | -------------------------------------------------------------------------------- /inst/REFERENCES.bib: -------------------------------------------------------------------------------- 1 | 2 | @article{Maus:2016, 3 | author = {Victor Maus and Gilberto Camara and Ricardo Cartaxo and Alber Sanchez and Fernando M. Ramos and Gilberto R. de Queiroz}, 4 | journal={IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing}, 5 | title={A Time-Weighted Dynamic Time Warping Method for Land-Use and Land-Cover Mapping}, 6 | year={2016}, 7 | volume={9}, 8 | number={8}, 9 | pages={3729--3739}, 10 | doi={10.1109/JSTARS.2016.2517118}, 11 | month={Aug} 12 | } 13 | 14 | @article{Maus:2019, 15 | author = {Victor Maus and Gilberto Camara and Marius Appel and Edzer Pebesma}, 16 | journal={Journal of Statistical Software}, 17 | title={{dtwSat}: Time-Weighted Dynamic Time Warping for Satellite Image Time Series Analysis in {R}}, 18 | year={2019}, 19 | volume={88}, 20 | number={5}, 21 | pages={1--31}, 22 | doi={10.18637/jss.v088.i05}, 23 | month={Jan} 24 | } 25 | 26 | @misc{Didan:2015, 27 | author = {Kamel Didan}, 28 | title = {{MOD13Q1 MODIS/Terra Vegetation Indices 16-Day L3 Global 29 | 250m SIN Grid V006 [Data set], NASA EOSDIS LP DAAC}}, 30 | year = {2015} 31 | } 32 | 33 | -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20110914_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20110914_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20110930_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20110930_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20111016_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20111016_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20111101_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20111101_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20111117_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20111117_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20111203_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20111203_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20111219_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20111219_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120101_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120101_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120117_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120117_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120202_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120202_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120218_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120218_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120305_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120305_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120321_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120321_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120406_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120406_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120422_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120422_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120508_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120508_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120524_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120524_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120609_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120609_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120625_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120625_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120711_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120711_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120727_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120727_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120812_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120812_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/MOD13Q1_20120828_subset_from_h12v10.tif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/MOD13Q1_20120828_subset_from_h12v10.tif -------------------------------------------------------------------------------- /inst/mato_grosso_brazil/samples.gpkg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/r-spatial/dtwSat/6704f05f153e5270839041994a6a7bd5f343b3ec/inst/mato_grosso_brazil/samples.gpkg -------------------------------------------------------------------------------- /man/get_time_series_freq.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/train.R 3 | \name{get_time_series_freq} 4 | \alias{get_time_series_freq} 5 | \title{Compute the Most Common Sampling Frequency across all observations} 6 | \usage{ 7 | get_time_series_freq(x) 8 | } 9 | \arguments{ 10 | \item{x}{A data frame including a column called `observations`` with the time series} 11 | } 12 | \value{ 13 | A difftime object representing the most common time difference between consecutive samples. 14 | } 15 | \description{ 16 | This function calculates the most common difference between consecutive time points. 17 | This can be useful for determining the aproximate sampling frequency of the time series data. 18 | } 19 | -------------------------------------------------------------------------------- /man/plot.twdtw_knn1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/plot.R 3 | \name{plot.twdtw_knn1} 4 | \alias{plot.twdtw_knn1} 5 | \title{Plot Patterns from twdtw-knn1 model} 6 | \usage{ 7 | \method{plot}{twdtw_knn1}(x, bands = NULL, ...) 8 | } 9 | \arguments{ 10 | \item{x}{A model of class \code{"twdtw_knn1"}.} 11 | 12 | \item{bands}{A character vector specifying the bands or indices to plot. 13 | If NULL (default), all available bands or indices in the data will be plotted.} 14 | 15 | \item{...}{Additional arguments passed to \code{\link[ggplot2]{ggplot}}. Currently not used.} 16 | } 17 | \value{ 18 | A \code{\link[ggplot2]{ggplot}} object displaying the time series patterns. 19 | } 20 | \description{ 21 | This function visualizes time series patterns from the \code{"twdtw_knn1"} model. 22 | It produces a multi-faceted plot, where each facet represents a different time series 23 | label from the model's data. Within each facet, different bands or indices (attributes) 24 | are plotted as distinct lines, differentiated by color. 25 | } 26 | \examples{ 27 | \dontrun{ 28 | 29 | # Read training samples 30 | samples_path <- 31 | system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat") 32 | 33 | samples <- st_read(samples_path, quiet = TRUE) 34 | 35 | # Get satellite image time sereis files 36 | tif_path <- system.file("mato_grosso_brazil", package = "dtwSat") 37 | tif_files <- dir(tif_path, pattern = "\\\\.tif$", full.names = TRUE) 38 | 39 | # Get acquisition dates 40 | acquisition_date <- regmatches(tif_files, regexpr("[0-9]{8}", tif_files)) 41 | acquisition_date <- as.Date(acquisition_date, format = "\%Y\%m\%d") 42 | 43 | # Create a 3D datacube 44 | dc <- read_stars(tif_files, 45 | proxy = FALSE, 46 | along = list(time = acquisition_date), 47 | RasterIO = list(bands = 1:6)) 48 | dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 49 | dc <- split(dc, c("band")) 50 | 51 | # Create a knn1-twdtw model 52 | m <- twdtw_knn1(x = dc, 53 | y = samples, 54 | cycle_length = 'year', 55 | time_scale = 'day', 56 | time_weight = c(steepness = 0.1, midpoint = 50), 57 | formula = band ~ s(time)) 58 | 59 | print(m) 60 | 61 | # Visualize model patterns 62 | plot(m) 63 | 64 | # Classify satellite images 65 | system.time(lu <- predict(dc, model = m)) 66 | 67 | # Visualise land use classification 68 | ggplot() + 69 | geom_stars(data = lu) + 70 | theme_minimal() 71 | 72 | } 73 | } 74 | \seealso{ 75 | twdtw_knn1 76 | } 77 | -------------------------------------------------------------------------------- /man/predict.twdtw_knn1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/predict.R 3 | \name{predict.twdtw_knn1} 4 | \alias{predict.twdtw_knn1} 5 | \title{Predict using the twdtw_knn1 model} 6 | \usage{ 7 | \method{predict}{twdtw_knn1}(object, newdata, ...) 8 | } 9 | \arguments{ 10 | \item{object}{A \code{twdtw_knn1} model object generated by the \code{twdtw_knn1} function.} 11 | 12 | \item{newdata}{A data frame or similar object containing the new observations 13 | (time series data) to be predicted.} 14 | 15 | \item{...}{Additional arguments passed to the \link[twdtw]{twdtw} function. 16 | If provided, they will overwrite twdtw arguments previously passed to \link[dtwSat]{twdtw_knn1}.} 17 | } 18 | \value{ 19 | A vector of predicted classes for the \code{newdata}. 20 | } 21 | \description{ 22 | This function predicts the classes of new data using the Time Warped Dynamic Time Warping (TWDTW) 23 | method with a 1-nearest neighbor approach. The prediction is based on the minimum TWDTW distance 24 | to the known patterns stored in the \code{twdtw_knn1} model. 25 | } 26 | \examples{ 27 | \dontrun{ 28 | 29 | # Read training samples 30 | samples_path <- 31 | system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat") 32 | 33 | samples <- st_read(samples_path, quiet = TRUE) 34 | 35 | # Get satellite image time sereis files 36 | tif_path <- system.file("mato_grosso_brazil", package = "dtwSat") 37 | tif_files <- dir(tif_path, pattern = "\\\\.tif$", full.names = TRUE) 38 | 39 | # Get acquisition dates 40 | acquisition_date <- regmatches(tif_files, regexpr("[0-9]{8}", tif_files)) 41 | acquisition_date <- as.Date(acquisition_date, format = "\%Y\%m\%d") 42 | 43 | # Create a 3D datacube 44 | dc <- read_stars(tif_files, 45 | proxy = FALSE, 46 | along = list(time = acquisition_date), 47 | RasterIO = list(bands = 1:6)) 48 | dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 49 | dc <- split(dc, c("band")) 50 | 51 | # Create a knn1-twdtw model 52 | m <- twdtw_knn1(x = dc, 53 | y = samples, 54 | cycle_length = 'year', 55 | time_scale = 'day', 56 | time_weight = c(steepness = 0.1, midpoint = 50), 57 | formula = band ~ s(time)) 58 | 59 | print(m) 60 | 61 | # Visualize model patterns 62 | plot(m) 63 | 64 | # Classify satellite images 65 | system.time(lu <- predict(dc, model = m)) 66 | 67 | # Visualise land use classification 68 | ggplot() + 69 | geom_stars(data = lu) + 70 | theme_minimal() 71 | 72 | } 73 | } 74 | \seealso{ 75 | twdtw_knn1 76 | } 77 | -------------------------------------------------------------------------------- /man/prepare_time_series.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/prepare_time_series.R 3 | \name{prepare_time_series} 4 | \alias{prepare_time_series} 5 | \title{Prepare a Time Series Tibble from a 2D stars Object with Bands and Time Attributes} 6 | \usage{ 7 | prepare_time_series(x) 8 | } 9 | \arguments{ 10 | \item{x}{A data frame derived from a stars object containing time series data in wide format. 11 | The column names should adhere to one of the following formats: "band.YYYY.MM.DD", "XYYYY.MM.DD.band", or "YYYY.MM.DD.band".} 12 | } 13 | \value{ 14 | A nested tibble in wide format. Each row of the tibble corresponds to a unique 'ts_id' that maintains the order from the original stars object. 15 | The nested structure contains observations (time series) for each 'ts_id', including the 'time' of each observation, and individual bands are presented as separate columns. 16 | } 17 | \description{ 18 | This function reshapes a data frame, which has been converted from a stars object, into a nested wide tibble format. 19 | The stars object conversion often results in columns named in formats like "band.YYYY.MM.DD", "XYYYY.MM.DD.band", or "YYYY.MM.DD.band". 20 | } 21 | -------------------------------------------------------------------------------- /man/pretty_arguments.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/train.R 3 | \name{pretty_arguments} 4 | \alias{pretty_arguments} 5 | \title{Print Pretty Arguments} 6 | \usage{ 7 | pretty_arguments(args) 8 | } 9 | \arguments{ 10 | \item{args}{A list of named arguments to display.} 11 | } 12 | \value{ 13 | Invisible NULL. The function is mainly used for its side effect of printing. 14 | } 15 | \description{ 16 | Display a list of arguments of a given function in a human-readable format. 17 | } 18 | \examples{ 19 | \dontrun{ 20 | pretty_arguments(formals(twdtw_knn1)) 21 | } 22 | 23 | } 24 | -------------------------------------------------------------------------------- /man/print.twdtw_knn1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/train.R 3 | \name{print.twdtw_knn1} 4 | \alias{print.twdtw_knn1} 5 | \title{Print method for objects of class twdtw_knn1} 6 | \usage{ 7 | \method{print}{twdtw_knn1}(x, ...) 8 | } 9 | \arguments{ 10 | \item{x}{An object of class \code{twdtw_knn1}.} 11 | 12 | \item{...}{ignored} 13 | } 14 | \value{ 15 | Invisible \code{twdtw_knn1} object. 16 | } 17 | \description{ 18 | This method provides a structured printout of the important components 19 | of a \code{twdtw_knn1} object. 20 | } 21 | -------------------------------------------------------------------------------- /man/shift_dates.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/shift_dates.R 3 | \name{shift_dates} 4 | \alias{shift_dates} 5 | \title{Shift Dates to Start on a Specified Origin Year} 6 | \usage{ 7 | shift_dates(x, origin = "1970-01-01") 8 | } 9 | \arguments{ 10 | \item{x}{A vector of date strings or Date objects representing the sequence to shift.} 11 | 12 | \item{origin}{A date string or Date object specifying the desired origin year for the shifted dates. 13 | Default is "1970-01-01".} 14 | } 15 | \value{ 16 | A vector of Date objects with the shifted dates starting on the same day-of-year in the specified origin year. 17 | } 18 | \description{ 19 | Shifts a vector of dates to start on the same day-of-year in a specified origin year 20 | while preserving the relative difference in days among the observations. 21 | This way the temporal pattern (e.g., seasonality) inherent to the original dates 22 | will also be preserved in the shifted dates. 23 | } 24 | \details{ 25 | The primary goal of this function is to align a sequence of dates based on the day-of-year 26 | in a desired origin year. This can be particularly useful for comparing or visualizing 27 | two or more time series with different absolute dates but aiming to align them based on 28 | the day-of-year or another relative metric. 29 | } 30 | \examples{ 31 | 32 | x <- c("2011-09-14", "2011-09-30", "2011-10-16", "2011-11-01") 33 | 34 | shift_dates(x) 35 | 36 | } 37 | -------------------------------------------------------------------------------- /man/twdtw_knn1.Rd: -------------------------------------------------------------------------------- 1 | % Generated by roxygen2: do not edit by hand 2 | % Please edit documentation in R/train.R 3 | \name{twdtw_knn1} 4 | \alias{twdtw_knn1} 5 | \title{Train a KNN-1 TWDTW model with optional GAM resampling} 6 | \usage{ 7 | twdtw_knn1( 8 | x, 9 | y, 10 | time_weight, 11 | cycle_length, 12 | time_scale, 13 | formula = NULL, 14 | start_column = "start_date", 15 | end_column = "end_date", 16 | label_colum = "label", 17 | sampling_freq = NULL, 18 | ... 19 | ) 20 | } 21 | \arguments{ 22 | \item{x}{A three-dimensional stars object (x, y, time) with bands as attributes.} 23 | 24 | \item{y}{An sf object with the coordinates of the training points.} 25 | 26 | \item{time_weight}{A numeric vector with length two (steepness and midpoint of logistic weight) or a function. 27 | See details in \link[twdtw]{twdtw}.} 28 | 29 | \item{cycle_length}{The length of the cycle, e.g. phenological cycles. Details in \link[twdtw]{twdtw}.} 30 | 31 | \item{time_scale}{Specifies the time scale for the observations. Details in \link[twdtw]{twdtw}.} 32 | 33 | \item{formula}{Either NULL or a formula to reduce samples of the same label using Generalized Additive Models (GAM). 34 | Default is \code{band ~ s(time)}. See details.} 35 | 36 | \item{start_column}{Name of the column in y that indicates the start date. Default is 'start_date'.} 37 | 38 | \item{end_column}{Name of the column in y that indicates the end date. Default is 'end_date'.} 39 | 40 | \item{label_colum}{Name of the column in y containing land use labels. Default is 'label'.} 41 | 42 | \item{sampling_freq}{The time frequency for sampling, including the unit (e.g., '16 day'). 43 | If NULL, the function will infer the frequency. This parameter is only used if a formula is provided.} 44 | 45 | \item{...}{Additional arguments passed to the \link[mgcv]{gam} function and to \link[twdtw]{twdtw} function.} 46 | } 47 | \value{ 48 | A 'twdtw_knn1' model containing the trained model information and the data used. 49 | } 50 | \description{ 51 | This function prepares a KNN-1 model with the Time Warp Dynamic Time Warping (TWDTW) algorithm. 52 | If a formula is provided, the training samples are resampled using Generalized Additive Models (GAM). 53 | } 54 | \details{ 55 | If \code{formula} is NULL, the KNN-1 model will retain all training samples. If a formula is passed (e.g., \code{band ~ \link[mgcv]{s}(time)}), 56 | then samples of the same label (land cover class) will be resampled using GAM. 57 | Resampling can significantly reduce prediction processing time. 58 | } 59 | \examples{ 60 | \dontrun{ 61 | 62 | # Read training samples 63 | samples_path <- 64 | system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat") 65 | 66 | samples <- st_read(samples_path, quiet = TRUE) 67 | 68 | # Get satellite image time sereis files 69 | tif_path <- system.file("mato_grosso_brazil", package = "dtwSat") 70 | tif_files <- dir(tif_path, pattern = "\\\\.tif$", full.names = TRUE) 71 | 72 | # Get acquisition dates 73 | acquisition_date <- regmatches(tif_files, regexpr("[0-9]{8}", tif_files)) 74 | acquisition_date <- as.Date(acquisition_date, format = "\%Y\%m\%d") 75 | 76 | # Create a 3D datacube 77 | dc <- read_stars(tif_files, 78 | proxy = FALSE, 79 | along = list(time = acquisition_date), 80 | RasterIO = list(bands = 1:6)) 81 | dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 82 | dc <- split(dc, c("band")) 83 | 84 | # Create a knn1-twdtw model 85 | m <- twdtw_knn1(x = dc, 86 | y = samples, 87 | cycle_length = 'year', 88 | time_scale = 'day', 89 | time_weight = c(steepness = 0.1, midpoint = 50), 90 | formula = band ~ s(time)) 91 | 92 | print(m) 93 | 94 | # Visualize model patterns 95 | plot(m) 96 | 97 | # Classify satellite images 98 | system.time(lu <- predict(dc, model = m)) 99 | 100 | # Visualise land use classification 101 | ggplot() + 102 | geom_stars(data = lu) + 103 | theme_minimal() 104 | 105 | } 106 | } 107 | -------------------------------------------------------------------------------- /tests/testthat.R: -------------------------------------------------------------------------------- 1 | # This file is part of the standard setup for testthat. 2 | # It is recommended that you do not modify it. 3 | # 4 | # Where should you do additional test configuration? 5 | # Learn more about the roles of various files in: 6 | # * https://r-pkgs.org/testing-design.html#sec-tests-files-overview 7 | # * https://testthat.r-lib.org/articles/special-files.html 8 | 9 | library(testthat) 10 | library(dtwSat) 11 | 12 | test_check("dtwSat") 13 | -------------------------------------------------------------------------------- /tests/testthat/test-twdtw_classify.R: -------------------------------------------------------------------------------- 1 | # Read training samples 2 | samples <- st_read(system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat"), quiet = TRUE) 3 | 4 | # Satellite image time sereis files 5 | tif_files <- dir(system.file("mato_grosso_brazil", package = "dtwSat"), pattern = "\\.tif$", full.names = TRUE) 6 | 7 | # The acquisition date is in the file name are not the true acquisition date 8 | # of each pixel. MOD13Q1 is a 16-day composite product, so the acquisition date 9 | # is the first day of the 16-day period 10 | acquisition_date <- as.Date(regmatches(tif_files, regexpr("[0-9]{8}", tif_files)), format = "%Y%m%d") 11 | 12 | # Read the data as a stars object setting the time/date for each observation 13 | # using along. This will prodcue a 4D array (data-cube) which will then be converted 14 | # to a 3D array by spliting the 'band' dimension 15 | dc <- read_stars(tif_files, 16 | proxy = FALSE, 17 | along = list(time = acquisition_date), 18 | RasterIO = list(bands = 1:6)) 19 | 20 | dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 21 | dc <- split(dc, c("band")) 22 | 23 | # Create a knn1-twdtw model 24 | system.time( 25 | m <- twdtw_knn1(x = dc, 26 | y = samples, 27 | cycle_length = 'year', 28 | time_scale = 'day', 29 | time_weight = c(steepness = 0.1, midpoint = 50), 30 | formula = band ~ s(time)) 31 | ) 32 | 33 | print(m) 34 | 35 | # Visualize model patterns 36 | plot(m) 37 | 38 | # Classify satellite image time series 39 | system.time(lu <- predict(dc, model = m)) 40 | 41 | # Visualise land use classification 42 | ggplot() + 43 | geom_stars(data = lu) + 44 | theme_minimal() 45 | 46 | ### OTHER TESTS 47 | m <- twdtw_knn1(x = dc, 48 | y = samples, 49 | cycle_length = 'year', 50 | time_scale = 'day', 51 | time_weight = c(steepness = 0.1, midpoint = 50), 52 | formula = band ~ s(time), 53 | sampling_freq = 60) 54 | 55 | plot(m) 56 | 57 | system.time( 58 | lu <- predict(dc, 59 | model = m, 60 | cycle_length = 'year', 61 | time_scale = 'day', 62 | time_weight = c(steepness = 0.1, midpoint = 50)) 63 | ) 64 | 65 | # Visualise land use classification 66 | ggplot() + 67 | geom_stars(data = lu) + 68 | theme_minimal() 69 | 70 | # Test model without samples reduction 71 | m <- twdtw_knn1(x = dc, 72 | y = samples, 73 | cycle_length = 'year', 74 | time_scale = 'day', 75 | time_weight = c(steepness = 0.1, midpoint = 50)) 76 | 77 | plot(m) 78 | 79 | plot(m, bands = c('EVI', 'NDVI')) 80 | -------------------------------------------------------------------------------- /vignettes.awk: -------------------------------------------------------------------------------- 1 | { 2 | if (NR == 4) { 3 | print("output: rmarkdown::html_vignette") 4 | } else if (NR > 4 && NR <= 10) { 5 | } else if (NR == 16) { 6 | print("\n**For a better version of the dtwSat vignettes see** https://vwmaus.github.io/dtwSat/articles/\n") 7 | } else if (NR == 19) { 8 | print 9 | print("knitr::opts_chunk$set(fig.height = 4.5)") 10 | print("knitr::opts_chunk$set(fig.width = 6)") 11 | } else 12 | print 13 | } 14 | -------------------------------------------------------------------------------- /vignettes/landuse-mapping.Rmd: -------------------------------------------------------------------------------- 1 | --- 2 | title: "1. Land use mapping using TWDTW-1NN and stars" 3 | author: "Victor Maus" 4 | output: 5 | html_document: 6 | toc: true 7 | toc_float: 8 | collapsed: false 9 | smooth_scroll: false 10 | toc_depth: 2 11 | vignette: > 12 | %\VignetteIndexEntry{1. Land use mapping using TWDTW-1NN and stars} 13 | %\VignetteEncoding{UTF-8} 14 | %\VignetteEngine{knitr::rmarkdown} 15 | bibliography: ./../inst/REFERENCES.bib 16 | --- 17 | 18 | 19 | ```{r setup, include=FALSE} 20 | knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, dev = "png") 21 | ``` 22 | 23 | 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 | The package utilizes Time-Weighted Dynamic Time Warping (TWDTW) along with a 1-Nearest Neighbor (1-NN) classifier. 25 | The subsequent sections will walk you through the process of creating a land-use map based on a set of training samples 26 | and a multi-band satellite image time series. 27 | 28 | ## Reading Training Samples 29 | 30 | First, let's read a set of training samples that come with the `dtwSat` package installation. 31 | 32 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 33 | library(dtwSat) 34 | 35 | samples <- st_read(system.file("mato_grosso_brazil/samples.gpkg", package = "dtwSat"), quiet = TRUE) 36 | ``` 37 | 38 | ## Preparing the Satellite Image Time Series 39 | 40 | The `dtwSat` package supports satellite images read into R using the `stars` package. 41 | The installation comes with a set of MOD13Q1 images for a region within the Brazilian Amazon. 42 | Note that timing is crucial for the TWDTW distance metric. To create a consistent image time series, 43 | we start by extracting the date of acquisition from the MODIS file names [@Didan:2015]. 44 | 45 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 46 | tif_files <- dir(system.file("mato_grosso_brazil", package = "dtwSat"), pattern = "\\.tif$", full.names = TRUE) 47 | 48 | acquisition_date <- as.Date(regmatches(tif_files, regexpr("[0-9]{8}", tif_files)), format = "%Y%m%d") 49 | 50 | print(acquisition_date) 51 | ``` 52 | 53 | *Side note:* The date in the file name is not the true acquisition date for each pixel. 54 | MOD13Q1 is a 16-day composite product, and the date in the file name is the first day of this 16-day period. 55 | 56 | With the files and dates in hand, we can construct a stars satellite image time series for `dtwSat`. 57 | 58 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 59 | # read data-cube 60 | dc <- read_stars(tif_files, 61 | proxy = FALSE, 62 | along = list(time = acquisition_date), 63 | RasterIO = list(bands = 1:6)) 64 | 65 | # set band names 66 | dc <- st_set_dimensions(dc, 3, c("EVI", "NDVI", "RED", "BLUE", "NIR", "MIR")) 67 | 68 | # convert band dimension to attribute 69 | dc <- split(dc, c("band")) 70 | 71 | print(dc) 72 | ``` 73 | 74 | Note that it's important to set the date for each observation using the parameter `along`. 75 | This will produce a 4D array (data-cube) that will be collapsed into a 3D array by converting 76 | the 'band' dimension into attributes. This prepares the data for training the TWDTW-1NN model. 77 | 78 | ## Create TWDTW-KNN1 model 79 | 80 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 81 | twdtw_model <- twdtw_knn1(x = dc, 82 | y = samples, 83 | cycle_length = 'year', 84 | time_scale = 'day', 85 | time_weight = c(steepness = 0.1, midpoint = 50), 86 | formula = band ~ s(time)) 87 | 88 | print(twdtw_model) 89 | ``` 90 | 91 | In addition to the mandatory arguments `x` (satellite data-cube) and `y` (training samples), 92 | the TWDTW distance calculation also requires setting `cycle_length`, `time_scale`, and `time_weight`. 93 | For more details, refer to the documentation using `?twdtw`. The argument `formula = band ~ s(time)` is optional. 94 | If provided, training samples time sereis are resampled using Generalized Additive Models (GAMs), 95 | collapsing all samples with the same land-use label into a single sample. This reduces computational 96 | demands. The sample in the model can be visualized as follows: 97 | 98 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 99 | plot(twdtw_model) 100 | ``` 101 | 102 | 103 | ## Land Use Prediction 104 | 105 | Finally, we predict the land-use classes for each pixel location in the data-cube: 106 | 107 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 108 | lu_map <- predict(dc, model = twdtw_model) 109 | print(lu_map) 110 | ``` 111 | 112 | The 'time' dimension was reduced to a single map. We can now visualize it using `ggplot`: 113 | 114 | ```{r , echo = TRUE, eval = TRUE, warning = FALSE, message = FALSE} 115 | ggplot() + 116 | geom_stars(data = lu_map) + 117 | theme_minimal() 118 | ``` 119 | 120 | Note that some pixels (in a 3x3 box) in the northeast part of the map have `NA` values due 121 | to a missing value in the blue band recorded on 2011-11-17. This limitation will be addressed 122 | in future versions of the dtwSat package. 123 | 124 | Ultimately, we can write the map to a TIFF file we can use: 125 | 126 | ```{r , echo = TRUE, eval = FALSE, warning = FALSE, message = FALSE} 127 | write_stars(lu_map, "lu_map.tif") 128 | ``` 129 | 130 | ## Further Reading 131 | 132 | This introduction outlined the use of `dtwSat` for land-use mapping. 133 | For more in-depth information, refer to the papers by @Maus:2016 and @Maus:2019 and the 134 | [`twdtw` R package documentation](https://CRAN.R-project.org/package=twdtw). 135 | 136 | For additional details on how to manage input and output satellite images, 137 | [`check` the stars documentation](https://CRAN.R-project.org/package=stars). 138 | 139 | ## References 140 | --------------------------------------------------------------------------------