forked from morrowcj/remotePARTS
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.Rmd
285 lines (192 loc) · 10.1 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(echo = TRUE, collapse = TRUE, comment = "#>",
fig.path = "man/figures/README-", out.width = "100%"
)
```
# remotePARTS
<!-- badges: start -->
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.tidyverse.org/lifecycle/#maturing)
<!-- [](https://travis-ci.com/morrowcj/remotePARTS) -->
<!-- [](https://travis-ci.org/github/morrowcj/remotePARTS) -->
[](https://github.com/morrowcj/remotePARTS/actions)
<!-- badges: end -->
`remotePARTS` is an `R` package that contains tools for running spatio-temporal
auto regression analyses on large remotely-sensed data sets by partitioning data
into manageable chunks.
## Description
This package is based on the PARTS method for analyzing spatially
autocorrelated time series (Ives et al., in prep).
## Instalation
To install the package and it's dependencies, use the following R code:
```{r, eval = FALSE}
install.packages("devtools") # ensure you have the latest devtools
devtools::install_github("morrowcj/remotePARTS", build_vignettes = TRUE)
```
Then, upon successful installation, load the package with `library(remotePARTS)`.
The latest version of [Rtools](https://cran.r-project.org/bin/windows/Rtools/)
is required for Windows and C++11 is required for other systems.
To read documentation for any function use the `?` operator in front of the
function in the R console. For example, to learn more about `fitGLS()` type
`?fitGLS()` and hit enter.
### installation notes/troubleshooting:
If vignettes won't build, try installing without them and accessing the vignette
online, for now:
```{r eval = FALSE}
devtools::install_github("morrowcj/remotePARTS", build_vignettes = FALSE)
```
Also, you may need to ensure that build tools are properly installed on your
machine: [official Rstudio development prerequisites](https://support.rstudio.com/hc/en-us/articles/200486498-Package-Development-Prerequisites)
use `pkgbuild::has_build_tools(debug = TRUE)` and
`pkgbuild::check_build_tools(debug = TRUE)` to unsure that your build tools are
up to date.
#### Windows
The above installation code worked on my Windows (10.0.19041 x86)
machine but:
On Windows 10 PC, you may need to change the permission settings for R
in order for `install_github()` to work:
1) right click on "C:\\Program Files\\R\\R-4.0.2\\library\\base"
2) click properties
3) Select "Security" Tab
4) find and select select "Users" in the "Group or user names" scroll menu
5) tick "Full control"
#### Linux
On my linux machine (Ubuntu 20.04), The package would only install
successfully if `build_vignettes = FALSE`. Trying to build the vignettes
during the installation process made the package unusable (corrupt .rda files).
If you can't get the vignette to build, try installing without vignettes
using the above instructions.
#### OS X
I was able to install on my partner's macbook air after installing xcode.
## Example usage
For examples on how to use `remotePARTS` in it's current state, see the `Alaska`
vignette by using the following R code:
```{r, eval = FALSE}
vignette("Alaska")
```
The vignette is also available online:
https://morrowcj.github.io/remotePARTS/Alaska.html.
## Testing
`remotePARTS` is currently in early development. Stability and efficiency tests
are ongoing and improvements occur incrementally. Automated tests have exists for
some, but not all, of the functions and, at present, tests have only been
conducted in limited environments.
```
Test Environments:
1. Windows 10.0.19041 x64
2. Linux:
LSB Version: core-11.1.0ubuntu2-noarch:security-11.1.0ubuntu2-noarch
Description: Ubuntu 20.04.1 LTS
Release: 20.04
```
Please report any bugs or suggested features as git issues.
## Data formats
In general, this package requires data to be contained in R matrices.
Data stored in other formats such as image files or rasters will
need to be converted. Furthermore, it is highly recommended that map
pixels without data values (e.g. water in analyses of land patterns)
be removed entirely. This is especially true when using the partitioned
form of the analysis because the matrix multiplication can't handle
missing data or unequal dimensions.
The following resource demonstrates how to manipulate raster files in
R: [Geospatial raster with R data carpentry](http://datacarpentry.org/r-raster-vector-geospatial/)
## Planned Features / To-do
Since this package in developmental stages, there are many features that are
currently unimplemented. This section will keep track of the features and design
implementations that I plan to include or change in the next version as well.
* [ ] fix links in the @seealso documentation sections. The proper format is
`\code{\link{functioname}}` for internal functions,
`\code{\link[packagename]{functioname}}` for external functions, and
`\url{https://www.r-project.org}` for web pages.
* [ ] add all remaining functions to the remotePARTS-package.R file
(only `fitGLS`) is currently listed. Also, update ORCID information for authors.
* [ ] Allow GLS functions to bypass the model-comparison step
(i.e. t-test only) for possible performance gains when F-like tests are not
necessary.
* [ ] allow users to, optionally, input parameters (e.g. `r` and `a` in the
exponential-power function) instead of fitting ML parameters. This should also
provide an option to fit a spatial matrix by estimating all of `nugget`, `r`,
and (optionally) `a`. Use `optim()` to do so. In the partitioned version, option
to estimate for some (but maybe not all) partitions.
* [ ] add an option to `fitGLS.partition()` to break before calculating any
of the cross partition stats (this is broken down in the vignette).
* [x] add example for testing "is there an overall time trend" to the vignette -
this can be done with a t-test for the intercept-only model. I've added an
example in the "Alaska" vignette.
* [x] make providing distance matrix **optional** instead of required for
`fitGLS.partition_rcpp()` and the partitioned method as a whole. - now
`fitGLS.partition()` does this and the process is displayed in the Alaska
vignette. `fitGLS.partition_rcpp()` is deprecated.
* [ ] include parallelization and distributed comptuting options. If these are
not natively implemented (i.e. using openMP in C++), then examples of how to
make it work with other parallelization tools should be provided.
* [ ] more explicit handling of missing data: "How should a constant time series
be treated?"; "What happends if there is a missing data point within a single
time series?"
* [x] possibly change the CLS function so that it reads 1 line of data at a time
to save memory. Also, using `RcppEigen::fastLM()` may be better than `lm()` in
terms of speed. - Testing showed that `fastLM()` was actuallyl slower than
`lm()` for all the problems I tested.
* [x] **Break up C++ functions into more than 1 file**
* [ ] **WRITE TESTS FOR EVERY FUNCTION!!!** - most functions have at
least some automated tests but more are needed.
* [ ] update documentation for every function to include output format
and example usage. - most function have decent documentation but some of
the documentation is inconsistent across the package and some functions
are under-documented.
* [ ] replace `fitGLS` with `fitGLS2` code and change the way all other C++
functions handle lists. The C++ code in `fitGLS2` modifies an existing list
made in R rather than building one within the C++ code.
* [ ] create S3 constructors and methods (i.e. `print()`, `summary()`, etc.) for
all relevant functions.
- [x] `remoteGLS()` constructs a GLS object and `print.remoteGLS()`
prints a compact and summarized display.
- [x] `remoteCLS()` constructor and methods for CLS objects. Both the
pixel-level `fitCLS` and the map-level `fitCLS.map` have S3 methods.
- [x] `remoteAR()` constructor and methods for AR_REML objects. Both pixel
and map-level `fitAR()` have S3 methods.
- [ ] `PARTmat()`: partition matrix for the partitioned GLS method.
If there are any additional features that you would like to see implemented, or
bugs/issues that you ran into, please submit an issue on github.
<!-- ## Installation (OLD) -->
<!-- Currently to install this package, the best way is to install with the -->
<!-- `remotePARTS_[version].tar.gz` file created with `R CMD check`. -->
<!-- Once a user has the tar.gz file they can install it with -->
<!-- ``` -->
<!-- install.packages("remotePARTS_[version].tar.gz", repos = NULL, type = "source") -->
<!-- ``` -->
<!-- and then from the R console with load it with -->
<!-- ``` -->
<!-- library(remotePARTS) -->
<!-- ``` -->
<!-- Eventually, the following lines should replace the above installation info: -->
<!-- You can install the released version of remotePARTS from
[CRAN](https://CRAN.R-project.org) with: -->
<!-- ``` r -->
<!-- install.packages("remotePARTS") -->
<!-- ``` -->
<!-- And the development version from [GitHub](https://github.com/) with: -->
<!-- ``` r -->
<!-- # install.packages("devtools") -->
<!-- devtools::install_github("morrowcj/remotePARTS") -->
<!-- ``` -->
<!-- ## Example -->
<!-- This is a basic example which shows you how to solve a common problem: -->
<!-- ```{r example} -->
<!-- library(remotePARTS) -->
<!-- ## basic example code -->
<!-- ``` -->
<!-- What is special about using `README.Rmd` instead of just `README.md`? You can include R chunks like so: -->
<!-- ```{r cars} -->
<!-- summary(cars) -->
<!-- ``` -->
<!-- You'll still need to render `README.Rmd` regularly, to keep `README.md` up-to-date. -->
<!-- You can also embed plots, for example: -->
<!-- ```{r pressure, echo = FALSE} -->
<!-- plot(pressure) -->
<!-- ``` -->
<!-- In that case, don't forget to commit and push the resulting figure files, so they display on GitHub! -->