Formerly stored in our README, now here for reference:

Some notes on organization

• The /R folder is for function scripts (and accompanying roxygen2 documentation) only. Please do not add example scripts or any other files in this folder
• The /example_scripts is meant to house scripts that we write to not only showcase our functions to each other but also have examples we can run through to make sure things are working properly. This will be taken to an advanced level via the testthat package later on.

Guidelines for writing code

These are informed by the rOpenSci guide as well as my personal opinion

• Always spell out TRUE and FALSE entirely, e.g. use argument = TRUE instead of argument = T
• Limit line lengths to no more than 80 characters
  • In RStudio, I recommend going to Tools -> Global Options -> Code -> Display, then check the box next to Show margin and set Margin column to 80. This will generate a vertical guide line to point out where 80 characters is in your scripts.
• Use snake_case for naming all functions, arguments, and variables
  • Try to go with object_verb() or verb_object() naming schemes for functions when possible, e.g. stri_join() or read_csv()
  • Try to avoid using function names that appear in other packages, esp those in popular packages like ggplot2 or dplyr, e.g. don't make a read_csv()
• To auto-generate the Help file (and other useful stuff) we will rely on the roxygen2 package. This will entail adding roxygen-style comments above each of our functions. Here is a useful vignette on the topic.
• Anywhere you rely on a function from another package, you must use explicit naming in a package_name::function() format, e.g. readxl::read_excel()
• Avoid acronyms whenever possible unless something is more commonly known by its acronym (e.g. "csv")
• For functions, make the object/data the first argument whenever possible to allow it to be pipeable (%>%)
• rOpenSci advises against using <- for assignment and prefers = instead. That said, it's not a big deal so long as you are generally consistent with your choice
• spelling::spell_check_package() is your best friend

Package writing resources

• R packages by Hadley Wickham & Jenny Bryan
  • A slightly earlier version of this guide
    (which I used when developing workloopR)
• rOpenSci package guide
  • And if you want to see workloopR (as an example and something I'll
    periodically steal code from) see here
• roxygen2 vignette (one of many -- see the package)
• a guide to vignettes -- what they are and how to write them
• A handy Markdown guide
• GitHub emoji cheat sheet, the source of all my turtles

🐢

https://github.com/vbaliga/pathviewR/blob/21fded1eaac9da0300abd7a52dfcf44e382b72c1/R/analytical_functions.R#L416

I think I have identified a couple minor bugs in the calculations inside calc_vis_angle(). Take a look at the pdf I have attached here: 2020-07-18_vbb_calc_vis_angle.pdf

Assuming that I have correctly interpreted each object name and then done the math correctly, we might need to revise how certain objects like height_2_screen are being computed. I also think min_dist may not be correct. But it's very possible I am missing something, so I think meeting and going over this stuff together would very much help.

The other thing I am unsure about is how to deal with situations where the stimulus is not perfectly centered around the min_dist. I suspect I am missing something fundamental here though -- would be good to talk to you about this too. But as I say in the pdf, maybe the thing to do ultimately (or in addition) is to use min_dist to calculate how spatial frequency information is modulated overall.

In 21fded1, I inserted some comments within example_calc_vis_angle.R as I was going through the script. Most of these are relatively minor and it might be better to ignore this stuff until we're solid on all the calculations.

https://github.com/vbaliga/pathviewR/blob/5fab63cd5c6c921590b449a36e97867de0f6ad69/example_scripts/pathviewR_pancakes.R#L92

This will be something I need to look into. I suspect it's breaking because of a change to dplyr, which recently updated to 1.0.0

Hi

We preparing the next release of ggplot2 and our reverse dependency checks show that your package is failing with the new version. Looking into it we see that your package reaches into the internal structure of ggplot2 and those have changed in the new version.

You can install the release candidate of ggplot2 using devtools::install_github('tidyverse/[email protected]') to test this out.

We plan to submit ggplot2 by the end of October and hope you can have a fix ready before then

Kind regards
Thomas

Leaving this issue here as a reminder to myself to provide you guys with an example of how roxygen2 works

I just realized that the all-in-one argument check will accept arguments for separate_trajectories and get_full_trajectories even if I have set the functions to FALSE in the pipeline because I want to adjust the data first before I run those last two functions. Not a big deal obviously, but may want to adjust at some point in case users find this confusing?

https://github.com/vbaliga/pathviewR/blob/ba4663106698a4bd8f113a7f90909f928262518b/R/all_in_one_functions.R#L64

https://github.com/vbaliga/pathviewR/blob/51906db8a39b86fef38913872431fed33ddd9c32/R/utility_functions.R#L6

In my two most recent commits (here and here), I added an example of a roxygen block to our relabel_motiv_axes() function. Picked that function because it was one for which it was relatively easy to write a Help file.

As you look at this roxygen block, it may help you to look at the auto-generated Help file that corresponds to it. To access this, run the following:

library(devtools)
install()
library(pathviewR)
?relabel_motiv_axes

What you'll then see is how each subsection within the roxygen block corresponds to a section within the Help file.

If you'd like detailed guides on how this all works, check out the following:
http://r-pkgs.had.co.nz/man.html
https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html
There are more advanced features, but we can deal with those later.

Let me know if you have any questions/issues!

🐢

To ultimately submit this, we'll need the package to work in R 4.0 (and beyond). This new version also changes a lot about R itself (looking at you stringsAsFactors), so it's probably a good idea to update for your own sake. This likely means reinstalling packages, too.

It is also a good time to mention that there are several packages that aid in package writing and ideally we'll be using the same versions of these. To that end, I'll paste below the code I use to install these packages.

Note 1: I tend to prefer the developmental (github) versions over the CRAN versions -- it often helps to get the new features as they roll out. The danger is that a "developmental" version of a package (usually styled as version X.Y.Z.9000) may be buggy or broken. That said, the authors of the packages below tend to recognize what a dick move it would be to push a buggy version of their package to github -- most of these packages are used by thousands of people. So it's (hopefully) unlikely we'll encounter these types of issues.

install.packages("devtools")

## if any of the below fails, just go with the CRAN version via 
## install.packages()

## First restart R (Ctrl + Shift + F10 on Windows or CMD + Shift + F10 on Mac)

remotes::install_github("r-lib/rlang")
devtools::install_github("hadley/tidyverse")
devtools::install_github("r-lib/devtools")

## Again, restart R (Ctrl + Shift + F10 on Windows or CMD + Shift + F10 on Mac)

remotes::install_github("r-lib/remotes")
devtools::install_github("r-lib/usethis")
devtools::install_github("ropenscilabs/available")

## Restart R (Ctrl + Shift + F10 on Windows or CMD + Shift + F10 on Mac)

devtools::install_github("r-lib/testthat")
devtools::install_github("r-lib/pkgdown")
devtools::install_github("klutometis/roxygen")
devtools::install_github("r-lib/roxygen2", force = TRUE)
remotes::install_github('rstudio/rmarkdown')
devtools::install_github("r-lib/usethis")

## Restart R (Ctrl + Shift + F10 on Windows or CMD + Shift + F10 on Mac)

devtools::install_github("mangothecat/goodpractice")
devtools::install_github("ropensci/codemetar")
devtools::install_github("ropensci/spelling")

Note 2: The code below is an excerpt from a larger script I run each time I update R. The full script contains all the other packages I commonly use. I'll attach it to this Issue in case you'd like the whole thing. Gonna attach it as a .txt file because github doesn't support attaching .R files for some reason...

FOR_NEW_R_INSTALLS.txt

So I had previously been naming & classifying imported objects as motiv objects, e.g. read_motiv_csv() makes an object of class motiv. Going forward, we might want to drop this convention, especially if we end up integrating data import capabilities from other sources (e.g. Flydra)

One option is to use pathviewR, but perhaps style it as pathviewr. So once data are imported, the resultant object would have class pathviewr. But this convention is a bit more difficult for re-naming our functions like read_motiv_csv() -- I don't think we want to rename that as read_pathviewr_csv().

It would be great to use this Issue thread to brainstorm these naming conventions and come to a consensus

At present, it looks like further incorporating rotation data into our functions or analyses is something we'd benefit from doing. To that end, I think this "Issue" would be a good place to stash any resources or tutorials we find on how quaternions work, since Motive exports rotation data in that notation.

This site (and the youtube videos included therein) seem to be a great resource for understanding quaternions:
https://eater.net/quaternions

https://github.com/vbaliga/pathviewR/blob/5fab63cd5c6c921590b449a36e97867de0f6ad69/example_scripts/example_calc_vis_angle.R#L44

So I simply copied over the example scripts from the barflea repository and have not edited them. Eric, can you take a look at the scripts as they appear here and edit them to 1) be able to run from this repo, and 2) remove references to previous versions of your functions. Thanks!

This is a pretty important decision and also one for which I don't claim to have a lot of insight.

When you get a chance, please take a look at our options which can be accessed via: ?usethis::use_gpl3_license() (all the use_x_license() functions seem to point to the same "License a package" help file).

I used GPL (>= 3) for workloopR but that decision was based on: 1) lots of other R packages using that license, and 2) it seemed pretty reasonable.

We should definitely figure this step out together -- curious to see what you think

https://github.com/vbaliga/pathviewR/blob/f4a043e75cb22e993aebc82790ecd730604b5439/R/utility_functions.R#L1029

I made some changes to how the max_frame_gap argument of separate_trajectories() behaves. The gist:

• numeric values (e.g. max_frame_gap = 1) can be used and the function basically behaves as it always has. One minor thing: if this value is set too high (e.g. max_frame_gap = 10000000000), then the function internally resets it to the actual maximum frame gap found within the data.
• alternatively, you can set max_frame_gap = "autodetect" to ask the function to guesstimate this for you.
  • The autodetect procedure, right now, is to generate a list of all frame gaps (on a per-subject basis; I can explain why later) and then filter out all cases where the frame gap is 1 (i.e. things are working normally). From the remaining frame gaps, we then take the median value as a rough estimate of what a max_frame_gap value could be.

That said, I am not sold on the idea of the median observed frame gap being the best value to use.

I'm very enthusiastic about keeping Melissa's determine_fg_M() function in pathviewR (if she's cool with that). At the very least, it is a very useful function for a user to be able to visualize how things change with frame gap choice and not need to blindly trust what we may automate within separate_trajectories().

But I also think that in addition to keeping this standalone plotting function, some of determine_fg_M()'s internals can be added into separate_trajectories(). Automating the max_frame_gap value to be where the "elbow" of the plot is seems like a better way to go vs. choosing the median as I mentioned above.

To that end, I think something like changepoint detection could work. There's even a changepoint package that could be useful here. I have a little experience playing around with this; I'll leave this piece as an example.

Curious to see what you guys think. Also please scream if any changes I made today break stuff for you!

https://github.com/vbaliga/pathviewR/blob/3357cc06ed3e02f3e2b3c5d73d6159b171629d00/R/data_import_functions.R#L272

Data imported from a Motive CSV should be either "Rigid Body" or "Marker" in the "Type" line of the CSV (aside from the frame # and time). A check could be written at this line to stop import if other Types are found. Alternatively, we could just let this slide OR produce a warning() about our uncertainty. Hmm...

Let's keep updating this list as we think of possibilities. I suggest we try to get peer review of code in addition to a "software paper". But depending on how we develop this package, we may try other options. Ideally, it would be good to avoid a publication cost.

Some ideas we've had so far, not necessarily in order:

• rOpenSci (code peer-review)
• rOpenSci + Journal of Open Source Software paper
• rOpenSci + Methods in Ecology and Evolution paper
• Behavior Research Methods
• Source Code for Biology and Medicine ($$$)
• Journal of Neuroscience Methods
• PLOS Computational Biology ($$$)

https://github.com/vbaliga/pathviewR/blob/76e5d1cded3bf43fee8ff5e54a17d40140cd71ac/example_scripts/pathviewR_pancakes.R#L288

Just noticed this when I ran through pathviewR_pancakes.R. For some reason, the behavior of ellipsis arguments in functions (...) has now changed. The idea behind ... is to allow arguments to be passed to previous steps in our analytical pipeline. For example:

jul_29_percent74 <-
  jul_29_path %>% import_and_clean_viewr(desired_percent = 74)

had previously allowed the desired_percent argument to be changed from its default within the select_x_percent() function (the 6th of the 8 functions in the full pipeline).

Instead, we now get the following error:

Error in data.table::fread(text = readLines(file_con), header = FALSE,  : 
  unused argument (desired_percent = 74)

This could stem from the R 4.0 update, but I haven't seen it explicitly documented anywhere. Or I could just be misunderstanding the situation. Not sure what's up...

Please describe the nature of your feature request.
Is the request to improve the tool(s) currently within pathviewR or to provide a tool that adds to the package's capabilities?

Please explain the feature you would like to use in pathviewR.
Briefly describe the goal of the feature and/or which current aspects of pathviewR relate to your request.

Can you provide an example file to help explain your request?
Data on public repositories are preferred. If that is not an option, please contact one of the pathviewR authors directly.

Are you interested in contributing a function and/or code yourself?
If so, please feel free to make a pull request for us to review.

Additional context
Add any other context or screenshots about the feature request here.