-
Notifications
You must be signed in to change notification settings - Fork 2
/
README.Rmd
189 lines (139 loc) · 7.88 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
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# pathviewr
<!-- badges: start -->
[](https://www.repostatus.org/#active) [](https://github.com/ropensci/pathviewr/actions) [](https://app.codecov.io/gh/ropensci/pathviewr?branch=master) [](https://github.com/ropensci/software-review/issues/409)\
[](https://zenodo.org/badge/latestdoi/268906628) [](https://CRAN.R-project.org/package=pathviewr)
<!-- badges: end -->
`pathviewr` offers tools to import, clean, and visualize movement data, particularly from motion capture systems such as [Optitrack's Motive](https://optitrack.com/software/motive/), the [Straw Lab's Flydra](https://github.com/strawlab/flydra), or other sources. We provide functions to remove artifacts, standardize tunnel position and tunnel axes, select a region of interest, isolate specific trajectories, fill gaps in trajectory data, and calculate 3D and per-axis velocity. For experiments of visual guidance, we also provide functions that use subject position to estimate perception of visual stimuli.
## Installation
You can install `pathviewr` from CRAN via:
```{r install_cran, eval = FALSE}
install.packages("pathviewr")
```
Or to get the latest (developmental) version through GitHub, use:
```{r install_github, eval = FALSE}
devtools::install_github("ropensci/pathviewr")
```
## Example
#### Data import and cleaning via `pathviewr`
We'll also load two `tidyverse` packages for wrangling & plotting in this
readme.
```{r package_loading, message=FALSE, warning=FALSE}
library(pathviewr)
library(ggplot2)
library(magrittr)
```
We will import and clean a sample data set from `.csv` files exported by Optitrack's [Motive](https://optitrack.com/software/motive/) software. For examples of how to import and clean other types of data, [see the Basics of data import and cleaning vignette](https://docs.ropensci.org/pathviewr/articles/data-import-cleaning.html).
```{r import_motive}
## Import the Motive example data included in
## the package
motive_data <-
read_motive_csv(
system.file("extdata", "pathviewr_motive_example_data.csv",
package = 'pathviewr')
)
```
Several functions to clean and wrangle data are available, and we have a suggested pipeline for how these steps should be handled. For this example, we will use one of two "all-in-one" functions: `clean_viewr()`. [See the Basics of data import and cleaning vignette](https://docs.ropensci.org/pathviewr/articles/data-import-cleaning.html) for the full pipeline and the other "all-in-one" function.
```{r all_in_one, fig.height=3, fig.width=6, dpi=300}
motive_allinone <-
motive_data %>%
clean_viewr(
relabel_viewr_axes = TRUE,
gather_tunnel_data = TRUE,
trim_tunnel_outliers = TRUE,
standardization_option = "rotate_tunnel",
select_x_percent = TRUE,
desired_percent = 50,
rename_viewr_characters = FALSE,
separate_trajectories = TRUE,
max_frame_gap = "autodetect",
get_full_trajectories = TRUE,
span = 0.95
)
## Quick plot
## Colors correspond to unique trajectories (file_sub_traj)
motive_allinone %>%
ggplot(aes(x = position_length, y = position_width,
fill = file_sub_traj)) +
geom_point(pch = 21) +
coord_fixed() +
theme_classic() +
theme(
legend.position = "none"
)
```
To get a sense of what we've done, compare the data before and after it has passed through the pipeline.
```{r compare_before_and_after}
## Check out the data's structure before cleaning and wrangling:
str(motive_data)
## Check out the data's structure after cleaning and wrangling:
str(motive_allinone)
```
An important aspect of how `pathviewr` defines trajectories is by managing gaps in the data. [See the vignette on Managing frame gaps](https://docs.ropensci.org/pathviewr/articles/managing-frame-gaps.html) for more information on trajectory definition and frame gaps.
Now that the data is cleaned, `pathviewr` includes functions that estimate visual perceptions based on the distance between the subject/observer and visual stimuli on the walls of the experimental tunnel. For a complete description of these functions, [see the vignette on Estimating visual perceptions from tracking data](https://docs.ropensci.org/pathviewr/articles/visual-perception-functions.html).
#### Add more info about experiments
Now that our objects have been cleaned, we will use `insert_treatments()` to add information about the experiments that are necessary for calculating visual perceptions.
The data from this example were recorded in a V-shaped tunnel. Accordingly, the vertex angle and vertex height of the tunnel, along with information about the visual stimuli used during the experiment, will be added to the data to inform calculations of visual perception (next section).
```{r insert_treats}
motive_V <-
motive_allinone %>%
insert_treatments(
tunnel_config = "v",
perch_2_vertex = 0.4,
vertex_angle = 90,
tunnel_length = 2,
stim_param_lat_pos = 0.1,
stim_param_lat_neg = 0.1,
stim_param_end_pos = 0.3,
stim_param_end_neg = 0.3,
treatment = "lat10_end_30"
)
```
#### Estimate perception of visual stimuli
To calculate the spatial frequency of the visual stimuli as perceived by the subject some distance from the stimuli, we will use `get_sf()`.
This will require two intermediate steps: 1) calculating the minimum distance between a subject and each wall (via `calc_min_dist_v()`) and 2) estimating the visual angles from the subject's perspective (`get_vis_angle()`).
```{r calc_sf_V}
motive_V_sf <-
motive_V %>%
calc_min_dist_v(simplify_output = TRUE) %>%
get_vis_angle() %>%
get_sf()
```
Visualizing the calculations provides an more intuitive understanding of how these visual perceptions change as the subject moves throughout the tunnel. Please [see the vignette on Estimating visual perceptions from tracking data](https://docs.ropensci.org/pathviewr/articles/visual-perception-functions.html) for more examples of visualizing calculations.
```{r motive_V_sf_pos, fig.height=3, fig.width=6, dpi=300}
ggplot(motive_V_sf, aes(x = position_width, y = position_height)) +
geom_point(aes(color = sf_pos), shape=1, size=3) +
geom_segment(aes(x = 0, # dimensions of the positive wall
y = -0.3855,
xend = 0.5869,
yend = 0.2014)) +
geom_segment(aes(x = 0, # dimensions of the negative wall
y = -0.3855,
xend = -0.5869,
yend = 0.2014)) +
coord_fixed() +
theme_classic() +
theme(
legend.position = "none"
)
```
## Contributing and/or raising Issues
We welcome feedback on bugs, improvements, and/or feature requests. Please [see our Issues templates on GitHub](https://github.com/ropensci/pathviewr/issues/new/choose) to make a bug fix request or feature request.
To contribute code via a pull request, please consult our [Contributing Guide](https://github.com/ropensci/pathviewr/blob/master/.github/CONTRIBUTING.md) first.
## Citation
The preferred way to cite `pathviewr` (but subject to change) is:
Baliga VB, Armstrong MS, Press ER (2021). *pathviewr: Tools to import, clean, and visualize animal movement data in R*. R package version 1.1.7, <https://github.com/ropensci/pathviewr>. doi: 10.5281/zenodo.4270187
## License
GPL (\>= 3) + file LICENSE
🐢