submission: spatsoc

[robitalec]

Summary

• What does this package do? (explain in 50 words or less):

The spatsoc package detects spatial and temporal groups in GPS relocations. For social network analysis, spatsoc can be used to build proximity-based social networks and perform network randomizations. It can also be used to detect potential interactions between individuals, shared space use, etc.

• Paste the full DESCRIPTION file inside a code block below:

Package: spatsoc
Title: Group Animal Relocation Data by Spatial and Temporal Relationship
Version: 0.1.0
Authors@R: c(
    person("Alec L.", "Robitaille", role = c("aut", "cre"), email = "robit.alec@gmail.com"),
    person("Quinn", "Webber", role = c("aut")),
    person("Eric", "Vander Wal", role = c("aut"))
    )
Description: Detects spatial and temporal groups in GPS relocations. 
    It can be used to convert GPS relocations to
    gambit-of-the-group format to build proximity-based social networks.
    In addition, the randomizations function provides data-stream
    randomization methods suitable for GPS data.
Depends: R (>= 3.4)
License: GPL-3 | file LICENSE
Encoding: UTF-8
LazyData: true
Imports: data.table (>= 1.10.5),
    sp,
    rgeos,
    adehabitatHR,
    igraph,
    methods
Suggests: testthat,
    knitr,
    rmarkdown
SystemRequirements: GEOS (>= 3.2.0)
RoxygenNote: 6.0.1
VignetteBuilder: knitr
Roxygen: list(markdown = TRUE)
BugReports: https://www.gitlab.com/robit.a/spatsoc/issues
URL: https://spatsoc.gitlab.io

• URL for the package (the development repository, not a stylized html page):

https://gitlab.com/robit.a/spatsoc/

(also mirrored to https://github.com/robitalec/spatsoc)

• Please indicate which category or categories from our package fit policies this package falls under and why:

data munging and geospatial - because it manipulates a specific type of spatial data (GPS relocations) to assist social network analysis

• Who is the target audience and what are scientific applications of this package?

The spatsoc package targets researchers using social network analysis with animal relocation datasets. The applications include disease transmission modeling, interactions between individuals, community structure.

• Are there other R packages that accomplish the same thing? If so, how does
  yours differ or meet our criteria for best-in-category?

There are no other R packages for creating social networks from GPS relocations. Other R packages exist for social network analysis, notably igraph and asnipe, but there is no overlap in functionality. spatsoc can be viewed as a precursor step before passing the outputs to the aforementioned packages.

• If you made a pre-submission enquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

Requirements

Confirm each of the following by checking the box. This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage, using services such as Travis CI, Coveralls and/or CodeCov.
• I agree to abide by ROpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

Publication options

• Do you intend for this package to go on CRAN?
• Do you wish to automatically submit to the Journal of Open Source Software? If so:
  • The package has an obvious research application according to JOSS's definition.
  • The package contains a paper.md matching JOSS's requirements with a high-level description in the package root or in inst/.
  • The package is deposited in a long-term repository with the DOI:
  • (Do not submit your package separately to JOSS)
• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:
  • The package is novel and will be of interest to the broad readership of the journal.
  • The manuscript describing the package is no longer than 3000 words.
  • You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)
  • (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no gaurantee that your manuscript willl be within MEE scope.)
  • (Although not required, we strongly recommend having a full manuscript prepared when you submit here.)
  • (Please do not submit your package separately to Methods in Ecology and Evolution)

Detail

• Does R CMD check (or devtools::check()) succeed? Paste and describe any errors or warnings:

There are no NOTEs, WARNINGs, or ERRORs.

• Does the package conform to rOpenSci packaging guidelines? Please describe any exceptions:

• If this is a resubmission following rejection, please explain the change in circumstances:

• If possible, please provide recommendations of reviewers - those with experience with similar packages and/or likely users of your package - and their GitHub user names:

[lmullen]

Editor checks:

• Fit: The package meets criteria for fit and overlap
• Automated tests: Package has a testing suite and is tested via Travis-CI or another CI service.
• License: The package has a CRAN or OSI accepted license
• Repository: The repository link resolves correctly
• Archive (JOSS only, may be post-review): The repository DOI resolves correctly
• Version (JOSS only, may be post-review): Does the release version given match the GitHub release (v1.0.0)?

---

Editor comments

@robitalec et al. Thanks for your submission. I will be editing this submission.

Local R CMD check looks fine.

There are 3 warnings and 1 note reported by R CMD check on your CI service (e.g., the most recent job). Please fix the WARNINGs, and the NOTE if possible, before the review begins.

There are several misspellings reported by spelling::spell_check(). Those should be corrected as well.

Good work on the test coverage.

Selection from goodpractice::gp()

It is good practice to


  ✖ not import packages as a whole, as this can cause name clashes between
    the imported packages. Instead, import only the specific functions you need.

This appears to be coming from a full import of the data.table package. Can you import only specific functions from that package?

I have begun soliciting reviewers and will let you all know when the review begins.

[robitalec]

Thanks @lmullen.

I've fixed the misspellings. There are some leftovers detected by spelling::spell_check_package but they are function arguments (e.g.: datetime, DT), last names, and "et al.".

We're importing the full data.table package because we use fread and data.table syntax in the tests and throughout the package's functions. It also does not have any of its own dependencies.

I've added @importFrom for all other functions (from other packages) used in the package.

I fixed the NOTEs and WARNINGs in the ci. I also added an r-devel image so we are testing on both the latest release and development version of R. Here is the latest pipeline.

[lmullen]

@robitalec Could you please add an "under review" badge to your repository? Here is the code:

[![](https://badges.ropensci.org/237_status.svg)](https://github.com/ropensci/onboarding/issues/237)

[lmullen]

Reviewer: @pmnatural
Reviewer: @FilipeamTeixeira
Due date: 2018-08-16

Thanks to our two reviewers for agreeing to undertake this peer review. As a reminder, you can find the reviewers' guide here, and you can ping me with questions.

[robitalec]

Badge added.

Thank you @pmnatural and @FilipeamTeixeira!

[FilipeamTeixeira]

@robitalec Here's my review. If there's something you feel like correcting please let me know. There's still quite some stuff to go through but for now I think that it's better to start from what I mention below and to go from there.

Package Review

Please check off boxes as applicable, and elaborate in comments below. Your review is not limited to these topics, as described in the reviewer guide

• As the reviewer I confirm that there are no conflicts of interest for me to review this work (If you are unsure whether you are in conflict, please speak to your editor before starting your review).

Documentation

The package includes all the following forms of documentation:

• A statement of need clearly stating problems the software is designed to solve and its target audience in README
• Installation instructions: for the development version of package and any non-standard dependencies in README
• Vignette(s) demonstrating major functionality that runs successfully locally
• Function Documentation: for all exported functions in R help
• Examples for all exported functions in R Help that run successfully locally
• Community guidelines including contribution guidelines in the README or CONTRIBUTING, and DESCRIPTION with URL, BugReports and Maintainer (which may be autogenerated via Authors@R).

Functionality

• Installation: Installation succeeds as documented.
• Functionality: Any functional claims of the software been confirmed.
• Performance: Any performance claims of the software been confirmed.
• Automated tests: Unit tests cover essential functions of the package
  and a reasonable range of inputs and conditions. All tests pass on the local machine.
• Packaging guidelines: The package conforms to the rOpenSci packaging guidelines

Final approval (post-review)

• The author has responded to my review and made changes to my satisfaction. I recommend approving this package.

Estimated hours spent reviewing:

---

Review Comments

test_check() gives 16 warnings with the following arguments:

test-pts.R:214: warning: withinGroup is not returned to the user
found duplicate id in a timegroup and/or splitBy - does your group_times threshold match the fix rate?

test-pts.R:229: warning: no rows are added to the result DT
found duplicate id in a timegroup and/or splitBy - does your group_times threshold match the fix rate?

test-pts.R:245: warning: only one column added to the result DT
found duplicate id in a timegroup and/or splitBy - does your group_times threshold match the fix rate?

test-pts.R:260: warning: group column is added to result
found duplicate id in a timegroup and/or splitBy - does your group_times threshold match the fix rate?
────────────────────────────────────────────────────────────────────────────────────────
✔ | 22   1   | test randomizations [2.6 s]
────────────────────────────────────────────────────────────────────────────────────────
test-random.R:11: warning: (unknown)
found duplicate id in a timegroup and/or splitBy - does your group_times threshold match the fix rate?
────────────────────────────────────────────────────────────────────────────────────────
✔ | 27   11   | test group_times [3.7 s]
────────────────────────────────────────────────────────────────────────────────────────
test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length

test-time.R:71: warning: threshold with minutes fails with > 60
number of items to replace is not a multiple of replacement length
────────────────────────────────────────────────────────────────────────────────────────

══ Results ═════════════════════════════════════════════════════════════════════════════
Duration: 64.2 s

OK:       163
Failed:   0
Warnings: 16`
Skipped:  0

Documentation

It would be interesting to have a help(spatsoc) available. This can be easily achieved and it saves the users from headaches or from having to go to the gitlab/github account to find some basic information about your package.

Same goes for the possibility of running a vignette("spatsoc").

Importing data

In the vignettes you start by importing the spatsoc example dataset. However, you're missing the library(data.table) as it is required by the function following your code. This might seem obvious for people familiar with the data.table package, but not everybody might be aware of it.

I would also recommend to create a function which imports data automatically. It's just two lines of code, but it might make the difference for unexperienced users. If I'm not aware that I have to use the data.table format, or even to convert the dates to a POSIXct format, it will take a while until I would understand what the error is. So you either have that at the beginning of your documentation (now it's at the end), or you create a specific function which does that for the user, and instruct the users that they should use that function.

Functions

group_times

Running the function with minutes goes well, but with hours and days gives me a warning.
As for hours, I get warnings:
Warning message: In group_times(DT, datetime = "datetime", threshold = "2 hours") : block, timegroup columns found in input DT and will be overwritten by this function

As for days I get the following warnings:
Warning messages: 1: In group_times(DT, datetime = "datetime", threshold = "5 days") : block, timegroup columns found in input DT and will be overwritten by this function 2: In group_times(DT, datetime = "datetime", threshold = "5 days") : the minimum and maximum days in DT are not evenly divisible by the provided block length

All functions

• Similar warnings occur along the package with other functions which from what I can see are generated by you. However, it's confusing on why does it generate this warning on demand. It doesn't necessarily mean that you have a problem, but it might confuse some users.

• I recommend as well that you mention what the output means. For example when running group_times() I get a variable called minday but I'm not sure of what am I getting. Is this something users should know if they are acquainted with the data? If not, there should be more information.

• Before looking at the rest of the code, I strongly recommend you to improve the documentation and to make it more accessible to other users. From how to import the data, what are the requirements (e.g. variables, format), to explain the warning messages and the output you get from those functions.

Summary

You're going on the right path, but there're some changes to be made. If there's something you don't agree with or something I've missed please let me know. As soon as you fix those issues or in case I'm wrong, explain what I'm missing, I'll proceed with the rest of the review.

Thank you