pathviewr

🐦 Tools to import, clean, and visualize animal movement data in R

Keywords

animal-movement flydra motion movement-data optitrack rstats rstats-package trajectories trajectory-analysis visual-guidance visual-perception

Last synced: 6 months ago · JSON representation ·

Repository

🐦 Tools to import, clean, and visualize animal movement data in R

Basic Info

Host: GitHub
Owner: ropensci
License: gpl-3.0
Language: HTML
Default Branch: master
Homepage: https://docs.ropensci.org/pathviewr/
Size: 154 MB

Statistics

Stars: 9
Watchers: 4
Forks: 3
Open Issues: 0
Releases: 5

Topics

animal-movement flydra motion movement-data optitrack rstats rstats-package trajectories trajectory-analysis visual-guidance visual-perception

Created over 5 years ago · Last pushed 8 months ago

Metadata Files

Readme Changelog Contributing License Citation Codemeta

README.Rmd

---
output: github_document
---



```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# pathviewr 



[![Project Status: Active -- The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![R build status](https://github.com/ropensci/pathviewr/workflows/R-CMD-check/badge.svg)](https://github.com/ropensci/pathviewr/actions) [![Codecov test coverage](https://codecov.io/gh/ropensci/pathviewr/graph/badge.svg)](https://app.codecov.io/gh/ropensci/pathviewr?branch=master) [![](https://badges.ropensci.org/409_status.svg)](https://github.com/ropensci/software-review/issues/409)\
[![DOI](https://zenodo.org/badge/268906628.svg)](https://zenodo.org/badge/latestdoi/268906628) [![CRAN status](https://www.r-pkg.org/badges/version/pathviewr)](https://CRAN.R-project.org/package=pathviewr)



`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.8, . doi: 10.5281/zenodo.4270187

## License

GPL (\>= 3) + file LICENSE

🐢

Owner

Name: rOpenSci
Login: ropensci
Kind: organization
Email: info@ropensci.org
Location: Berkeley, CA

Website: https://ropensci.org/
Twitter: rOpenSci
Repositories: 307
Profile: https://github.com/ropensci

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Baliga"
  given-names: "Vikram B."
  orcid: "https://orcid.org/0000-0002-9367-8974"
- family-names: "Armstrong"
  given-names: "Melissa S."
  orcid: "https://orcid.org/0000-0002-3059-0094"
- family-names: "Press"
  given-names: "Eric R."
  orcid: "https://orcid.org/0000-0002-1944-3755"
title: "pathviewr"
version: 1.1.8
doi: 10.5281/zenodo.4270187
date-released: 2021-05-06
url: "https://github.com/ropensci/pathviewr"

CodeMeta (codemeta.json)

{
  "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
  "@type": "SoftwareSourceCode",
  "identifier": "pathviewr",
  "description": "Tools to import, clean, and visualize movement data, particularly from motion capture systems such as Optitrack's 'Motive', the Straw Lab's 'Flydra', or from 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. ",
  "name": "pathviewr: Wrangle, Analyze, and Visualize Animal Movement Data",
  "relatedLink": [
    "https://docs.ropensci.org/pathviewr/",
    "https://CRAN.R-project.org/package=pathviewr"
  ],
  "codeRepository": "https://github.com/ropensci/pathviewr/",
  "issueTracker": "https://github.com/ropensci/pathviewr/issues/",
  "license": "https://spdx.org/licenses/GPL-3.0",
  "version": "1.1.8",
  "programmingLanguage": {
    "@type": "ComputerLanguage",
    "name": "R",
    "url": "https://r-project.org"
  },
  "runtimePlatform": "R version 4.4.0 (2024-04-24)",
  "provider": {
    "@id": "https://cran.r-project.org",
    "@type": "Organization",
    "name": "Comprehensive R Archive Network (CRAN)",
    "url": "https://cran.r-project.org"
  },
  "author": [
    {
      "@type": "Person",
      "givenName": "Vikram B.",
      "familyName": "Baliga",
      "email": "vbaliga87@gmail.com",
      "@id": "https://orcid.org/0000-0002-9367-8974"
    },
    {
      "@type": "Person",
      "givenName": "Melissa S.",
      "familyName": "Armstrong",
      "email": "melissa.armstrong@gmail.com",
      "@id": "https://orcid.org/0000-0002-3059-0094"
    },
    {
      "@type": "Person",
      "givenName": "Eric R.",
      "familyName": "Press",
      "email": "epress12@gmail.com",
      "@id": "https://orcid.org/0000-0002-1944-3755"
    }
  ],
  "maintainer": [
    {
      "@type": "Person",
      "givenName": "Vikram B.",
      "familyName": "Baliga",
      "email": "vbaliga87@gmail.com",
      "@id": "https://orcid.org/0000-0002-9367-8974"
    }
  ],
  "softwareSuggestions": [
    {
      "@type": "SoftwareApplication",
      "identifier": "knitr",
      "name": "knitr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=knitr"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "rmarkdown",
      "name": "rmarkdown",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=rmarkdown"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "testthat",
      "name": "testthat",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=testthat"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "anomalize",
      "name": "anomalize",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=anomalize"
    },
    {
      "@type": "SoftwareApplication",
      "identifier": "covr",
      "name": "covr",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=covr"
    }
  ],
  "softwareRequirements": {
    "1": {
      "@type": "SoftwareApplication",
      "identifier": "R.matlab",
      "name": "R.matlab",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=R.matlab"
    },
    "2": {
      "@type": "SoftwareApplication",
      "identifier": "data.table",
      "name": "data.table",
      "version": ">= 1.12.2",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=data.table"
    },
    "3": {
      "@type": "SoftwareApplication",
      "identifier": "magrittr",
      "name": "magrittr",
      "version": ">= 1.5",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=magrittr"
    },
    "4": {
      "@type": "SoftwareApplication",
      "identifier": "dplyr",
      "name": "dplyr",
      "version": ">= 1.0.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=dplyr"
    },
    "5": {
      "@type": "SoftwareApplication",
      "identifier": "stringr",
      "name": "stringr",
      "version": ">= 1.4.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=stringr"
    },
    "6": {
      "@type": "SoftwareApplication",
      "identifier": "tibble",
      "name": "tibble",
      "version": ">= 3.0.1",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tibble"
    },
    "7": {
      "@type": "SoftwareApplication",
      "identifier": "tidyr",
      "name": "tidyr",
      "version": ">= 1.1.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tidyr"
    },
    "8": {
      "@type": "SoftwareApplication",
      "identifier": "fANCOVA",
      "name": "fANCOVA",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=fANCOVA"
    },
    "9": {
      "@type": "SoftwareApplication",
      "identifier": "purrr",
      "name": "purrr",
      "version": ">= 0.3.3",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=purrr"
    },
    "10": {
      "@type": "SoftwareApplication",
      "identifier": "ggplot2",
      "name": "ggplot2",
      "version": ">= 3.4.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=ggplot2"
    },
    "11": {
      "@type": "SoftwareApplication",
      "identifier": "tidyselect",
      "name": "tidyselect",
      "version": ">= 1.1.0",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=tidyselect"
    },
    "12": {
      "@type": "SoftwareApplication",
      "identifier": "cowplot",
      "name": "cowplot",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=cowplot"
    },
    "13": {
      "@type": "SoftwareApplication",
      "identifier": "lubridate",
      "name": "lubridate",
      "provider": {
        "@id": "https://cran.r-project.org",
        "@type": "Organization",
        "name": "Comprehensive R Archive Network (CRAN)",
        "url": "https://cran.r-project.org"
      },
      "sameAs": "https://CRAN.R-project.org/package=lubridate"
    },
    "SystemRequirements": null
  },
  "fileSize": "1908.018KB",
  "citation": [
    {
      "@type": "SoftwareSourceCode",
      "datePublished": "2021",
      "author": [
        {
          "@type": "Person",
          "givenName": "Vikram B.",
          "familyName": "Baliga",
          "@id": "https://orcid.org/0000-0002-9367-8974"
        },
        {
          "@type": "Person",
          "givenName": "Melissa S.",
          "familyName": "Armstrong",
          "@id": "https://orcid.org/0000-0002-3059-0094"
        },
        {
          "@type": "Person",
          "givenName": "Eric R.",
          "familyName": "Press",
          "@id": "https://orcid.org/0000-0002-1944-3755"
        }
      ],
      "name": "pathviewR: Tools to import, clean, and visualize animal movement data in R",
      "identifier": "10.5281/zenodo.4270187",
      "url": "https://github.com/ropensci/pathviewR",
      "description": "R package version 1.1.8",
      "@id": "https://doi.org/10.5281/zenodo.4270187",
      "sameAs": "https://doi.org/10.5281/zenodo.4270187",
      "isPartOf": {
        "@type": "PublicationIssue",
        "datePublished": "2021",
        "isPartOf": {
          "@type": [
            "PublicationVolume",
            "Periodical"
          ],
          "name": "Github repository"
        }
      }
    }
  ],
  "releaseNotes": "https://github.com/ropensci/pathviewr/blob/master/NEWS.md",
  "readme": "https://github.com/ropensci/pathviewr/blob/master/README.md",
  "contIntegration": [
    "https://github.com/ropensci/pathviewr/actions",
    "https://app.codecov.io/gh/ropensci/pathviewr?branch=master"
  ],
  "developmentStatus": "https://www.repostatus.org/#active",
  "review": {
    "@type": "Review",
    "url": "https://github.com/ropensci/software-review/issues/409",
    "provider": "https://ropensci.org"
  },
  "keywords": [
    "movement-data",
    "motion",
    "animal-movement",
    "optitrack",
    "flydra",
    "visual-guidance",
    "visual-perception",
    "rstats",
    "rstats-package",
    "trajectory-analysis",
    "trajectories"
  ]
}

GitHub Events

Total

Watch event: 2
Issue comment event: 2
Push event: 6
Pull request event: 1
Fork event: 1

Last Year

Watch event: 2
Issue comment event: 2
Push event: 6
Pull request event: 1
Fork event: 1

Committers

Last synced: almost 3 years ago

All Time

Total Commits: 586
Total Committers: 4
Avg Commits per committer: 146.5
Development Distribution Score (DDS): 0.445

Top Committers

Name	Email	Commits
Vikram Baliga	v**7@g**m	325
epress12	6**2@u**m	146
Melissa	a**g@z**a	86
GitHub Actions	a**s@g**m	29

Committer Domains (Top 20 + Academic)

github.com: 1 zoology.ubc.ca: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 17
Total pull requests: 1
Average time to close issues: about 2 months
Average time to close pull requests: N/A
Total issue authors: 4
Total pull request authors: 1
Average comments per issue: 3.12
Average comments per pull request: 0.0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 0
Pull requests: 1
Average time to close issues: N/A
Average time to close pull requests: N/A
Issue authors: 0
Pull request authors: 1
Average comments per issue: 0
Average comments per pull request: 0.0
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

vbaliga (14)
epress12 (1)
thomasp85 (1)
scienceisfiction (1)

Pull Request Authors

teunbrand (1)

Top Labels

Issue Labels

bug (3) enhancement (3) documentation (2) help wanted (1)

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- cran 573 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 5
Total maintainers: 1

cran.r-project.org: pathviewr

Wrangle, Analyze, and Visualize Animal Movement Data

Homepage: https://github.com/ropensci/pathviewr/
Documentation: http://cran.r-project.org/web/packages/pathviewr/pathviewr.pdf
License: GPL-3
Latest release: 1.1.8
published 8 months ago

Versions: 5
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 573 Last month

Rankings

Forks count: 17.8%

Downloads: 20.3%

Stargazers count: 21.1%

Average: 24.9%

Dependent packages count: 29.8%

Dependent repos count: 35.5%

Maintainers (1)

vbaliga87@gmail.com

Last synced: 6 months ago

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Open Source Science

pathviewr

Science Score: 77.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.Rmd

Owner

Citation (CITATION.cff)

CodeMeta (codemeta.json)

GitHub Events

Total

Last Year

Committers

All Time

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

cran.r-project.org: pathviewr

Rankings

Maintainers (1)