-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
251 lines (199 loc) · 8.63 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
## out.width = "100%"
fig.width = 6,
fig.asp = 0.7
)
```
# sftrack: Modern classes for tracking and movement data <img src="man/figures/sftrack-logo-200-transp-bg.png" align="right" width="200px"/>
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://opensource.org/license/mit/)
[](https://CRAN.R-project.org/package=sftrack)
[](https://CRAN.R-project.org/package=sftrack)
<!-- [](https://travis-ci.org/mablab/sftrack) -->
<!-- [](https://travis-ci.org/mablab/sftrack) -->
[](https://github.com/mablab/sftrack/actions)
<!-- badges: end -->
`sftrack` provides modern classes for **tracking and movement data**,
relying on `sf` spatial infrastructure. Tracking data are made of
tracks, i.e. series of locations with at least 2-dimensional spatial
coordinates (x,y), a time index (t), and individual identification
(id) of the object being monitored; movement data are made of
trajectories, i.e. the line representation of the path, composed by
steps (the straight-line segments connecting successive
locations). `sftrack` is designed to handle movement of both living
organisms and inanimate objects.
The development and design of the `sftrack` package follow three
simple principles:
1. **Minimal and focused:** this is basically the Unix philosophy. Do
a simple thing, and do it well. The scope of the package is limited
(see above), with as few dependencies as possible;
2. **User-friendly:** `sftrack` is designed to be as easy to use as
familiar R structures like `data.frame`s and `sf`
objects. `sftrack` objects are tidy, and follow the idea that rows
are records (locations) and columns are variable (following the
semantics of tracking and movement data);
3. **Flexible and extensible:** `sftrack` is meant first for users to
use on their data, but also directly designed to address other
developers' needs for their own tracking packages.
## Getting started
To get started, install `sftrack` directly from CRAN, or check the
development version on GitHub with the
[remotes](https://cran.r-project.org/package=remotes) package:
```r
# To install the stable version from CRAN
install.packages("sftrack")
# To install the dev version with built vignettes
remotes::install_github("mablab/sftrack", ref = "dev", build_vignettes = TRUE)
```
The `dev` version is updated much more frequently and should pass the
majority of CRAN checks. However, if you install the `dev` version,
understand it may still contain some bugs. Please submit any bug you
find to the [issues](https://github.com/mablab/sftrack/issues) page.
## A minimal introduction to `sftrack` and `sftraj` objects
The easiest way to create an `sftrack` object is to start from a
`data.frame` with all information as columns, typically the raw data
extracted from telemetry devices:
```{r raccoon}
library("sftrack")
data(raccoon)
raccoon$timestamp <- as.POSIXct(as.POSIXlt(raccoon$timestamp, tz = "EST5EDT"))
head(raccoon)
```
In order to convert your raw data into an `sftrack` object, use the
function `as_sftrack()`. The function requires the three main elements
of tracking data:
- coordinates of the locations in at least the `x` and `y` axes (can
be UTM, lat/long, etc., with projection provided in `crs`);
- timestamps of the locations as `POSIXct` (*or* as `integer`);
- grouping information (referred to as a "groups"), providing at least the
identity of each individual.
```{r sftrack}
my_sftrack <- as_sftrack(
data = raccoon,
coords = c("longitude","latitude"),
time = "timestamp",
group = "animal_id",
crs = 4326)
head(my_sftrack)
```
```{r summary}
summary_sftrack(my_sftrack)
```
While `sftrack` objects contain tracking data (locations), they can
easily be converted to movement data (with a step model instead) with
`as_sftraj`:
```{r sftraj}
my_sftraj <- as_sftraj(my_sftrack)
head(my_sftraj)
```
Both objects can easily be plotted with base R plot functions, which
highlights the fundamental difference between tracking and movement
data (`sftrack` on the left; `sftraj` on the right):
```{r plot, fig.show = "hold", out.width = "50%"}
plot(my_sftrack, main = "Tracking data (locations)")
plot(my_sftraj, main = "Movement data (steps)")
```
## Roadmap
* Data class converters from the main tracking packages, such as
`move::Move` and `trackeR::trackeRdata`, integrated into
`as_sftrack`;
* More plotting options for tracks and trajectories (in base R and
`ggplot2`);
* Provide Gantt chart-like or chronogram-like graphs;
* Dynamic exploration of trajectories.
## How can you help?
1. **Submit any bug you find to the
[issues](https://github.com/mablab/sftrack/issues) page;**
2. Address open questions (see below);
3. Contribute use cases (see below).
### Address open questions: *We need your feedback!*
While the foundations of the package are now pretty solid, we are
still dealing with open questions about several aspects of the
package, including the names of `sftrack` variables (e.g. coordinates,
timestamps, id and error), the structure of the grouping factor, or the
structure of the error term.
If you have strong opinions or simply want to help on the technical
side, we invite you to comment on those [open issues
here](https://github.com/mablab/sftrack/labels/question).
### Contribute use cases: *We need your feedback!*
We also need to precisely understand what is expected from such a
package. The idea here is to collect all possible use cases for a
trajectory object in R. We know they are multiple, and will contribute
our own use cases — however, we want `sftrack` to be as useful as
possible, and to act as a center piece for movement in R, so we need
you to tell us how you would use it. **In other words, we want to
understand what you expect from such a package, as a user or as a
developer.** For this, we ask you to fill out special issues in the
GitHub tracker of the package, following the ['Use case'
template](https://github.com/mablab/sftrack/issues/new?assignees=&labels=&template=use-case.md&title=%5BUse+case%5D+Change+this+title).
Use cases do not need to be very complicated, but need to present a
specific use in human terms, the technical requirements associated to
it, and the input and output of the use case. Such use case could look
like this:
> **[Use case] Amazing plot for trajectory**
>
> **Use case:**
>
> Plot a trajectory using my `special_trajplot` function, which shows
> [something amazing].
>
> **Requirements:**
>
> - spatial coordinates (x,y) as geographic coordinates with
> projection information
>
> - a time (t) as POSIXt object, ordered in time
>
> - information that identifies individuals (e.g. animal) for each
> location
>
> - data associated to each location directly accessible
>
> **Input:**
> a `sftrack` object
>
> **Output:**
> a plot with [something amazing] about the trajectory
>
> **Additional information:**
> See my `special_trajplot` function here [with link].
Another example could be like this:
> **[Use case] Fill in missing locations in a sequence**
>
> **Use case:**
> Fill in the missing locations of a trajectory that contains spatial or temporal gaps.
> (for instance coming from GPS with failed fixes); In other words
> add in the missing values of a trajectory, i.e. timestamps with no geographic
> coordinates.
>
> **Requirements:**
>
> - a time (t) as POSIXt object, ordered in time
>
> - information that identifies sequences of locations (optional, if
> several sequences), which could be different circuits of one
> individual, or different individuals, etc.
>
> - `sftrack` should be capable of handling/storing missing values
>
> **Input:**
> a `sftrack` object
>
> **Output:**
> a `sftrack` object with additional timestamps for gaps (but otherwise
> identical in every way to the original `sftrack`)
>
> **Additional information:**
> See `adehabitatLT::setNA`, which does exactly that on `ltraj`
> objects.