[REVIEW]: areal: An R package for areal weighted interpolation

[whedon]

Submitting author: @chris-prener (Christopher Prener)
Repository: https://github.com/slu-openGIS/areal
Version: v0.1.4.3
Editor: @lheagy
Reviewer: @sjsrey, @edzer
Archive: 10.5281/zenodo.2667289

Status

Status badge code:

HTML: <a href="http://joss.theoj.org/papers/3adac04a327078b3ae62f3232830ffb1"><img src="http://joss.theoj.org/papers/3adac04a327078b3ae62f3232830ffb1/status.svg"></a>
Markdown: [![status](http://joss.theoj.org/papers/3adac04a327078b3ae62f3232830ffb1/status.svg)](http://joss.theoj.org/papers/3adac04a327078b3ae62f3232830ffb1)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@sjsrey & @edzer, please carry out your review in this issue by updating the checklist below. If you cannot edit the checklist please:

1. Make sure you're logged in to your GitHub account
2. Be sure to accept the invite at this URL: https://github.com/openjournals/joss-reviews/invitations

The reviewer guidelines are available here: https://joss.theoj.org/about#reviewer_guidelines. Any questions/concerns please let @lheagy know.

✨ Please try and complete your review in the next two weeks ✨

Review checklist for @sjsrey

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: v0.1.4.3
• Authorship: Has the submitting author (@chris-prener) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

Review checklist for @edzer

Conflict of interest

• As the reviewer I confirm that I have read the JOSS conflict of interest policy and that there are no conflicts of interest for me to review this work.

Code of Conduct

• I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• Repository: Is the source code for this software available at the repository url?
• License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• Version: v0.1.4.3
• Authorship: Has the submitting author (@chris-prener) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?

Functionality

• Installation: Does installation proceed as outlined in the documentation?
• Functionality: Have the functional claims of the software been confirmed?
• Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• Automated tests: Are there automated tests or manual steps described so that the function of the software can be verified?
• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• Authors: Does the paper.md file include a list of authors with their affiliations?
• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• References: Do all archival references that should have a DOI list one (e.g., papers, datasets, software)?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @sjsrey, it looks like you're currently assigned as the reviewer for this paper 🎉.

⭐ Important ⭐

If you haven't already, you should seriously consider unsubscribing from GitHub notifications for this (https://github.com/openjournals/joss-reviews) repository. As a reviewer, you're probably currently watching this repository which means for GitHub's default behaviour you will receive notifications (emails) for all reviews 😿

To fix this do the following two things:

1. Set yourself as 'Not watching' https://github.com/openjournals/joss-reviews:

2. You may also like to change your default settings for this watching repositories in your GitHub profile here: https://github.com/settings/notifications

For a list of things I can do to help you, just type:

@whedon commands

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[lheagy]

👋 Many thanks @sjsrey, @edzer for being willing to review! In the main thread above, there is a checklist for you both to help guide the review. If you haven't previously reviewed for JOSS, please be sure to accept the invite: https://github.com/openjournals/joss-reviews/invitations. This will allow you to check off the items in the checklist. If possible, we would appreciate receiving your review within the next 2 weeks.

Please let me know if you have any questions or if I can provide clarification on anything.

[chris-prener]

Thanks @sjsrey and @edzer for volunteering to review - we're looking forward to your feedback!

[sjsrey]

opened chris-prener/areal#17

[edzer]

This is a nice package that provides relatively limited functionality over sf::st_interpolate_aw (which I wrote), but that explains and illustrates the whole areal interpolation process very well. Since JOSS does not demand new functionality, it is a nice addition to the existing package ecosystem around sf. I recommend that the authors address the following issues:

• The pdf of the paper shows R code on page 2, but this code is hidden where it runs off the page at the side.
• The manuscript claims it provides functions that "validate data suitability for areal interpolation", but does not explain what this validation does. What does it do?
• given that the package does little more than sf::st_interpolate_aw, and given that that function was available first, the added value of the packages would become more clear when it would
  • mention the name of that function (rather than refer to "the existing functionality in sf"),
  • show in a side-by-side comparison that areal::aw_interpolate and sf::st_interpolate_aw give identical results for an intensive an an extensive variable
  • give an example where areal::aw_interpolate does something different when there is a difference in areas, and show how large the effect of doing this is
• the correct reference for Pebesma, E. (2018) is found here
• change the wording of "black box", as this is not a black box. Closed source software is a black box
• the areal-weighted-interpolation vignette mentions "Spatially intensive operations are used when the data to be interpolated are a ratio." I'm afraid it is not this simple: a counter example is is CO2 emissions measured in tons/year: an extensive variable when interpolated spatially.

[chris-prener]

Thanks so much for the feedback @edzer - we can make these changes!

[sjsrey]

Well designed and documented package that extends important functionality for areal interpolation. A couple of points the authors may want to consider - these are not show stoppers by any means just food for thought and perhaps future extensions:

• Scaling: the current examples are well crafted and illustrate the core functionality. At the same time n is fairly modest here and one wonders if these methods were going to be used for larger n problems, or applied iteratively over many cities , would there be any bottlenecks users should be aware of?
• The distinction between extensive and intensive variables is handled nicely. One case that might also be considered is the choice between interpolation of an intensive variable directly versus deriving the intensive estimates as a ratio of two extensive variables that have been estimated: pct_black = black/total, for example could be based on first estimating black, and total, or it could be treated as an intensive variable that is estimated in one step.. Related to this is that there are inherent constraints that are likely violated when treating the intensive and extensive variables independently in certain cases. For example, in a simple world where where 'total = black + white, this implies pct_black + pct_white =1`. If the intensive and extensive variables involved are estimated independently, this constraint is likely to be violated.
• The weight argument names are a bit confusing. sum, to me, would seem a better name for the case where intersection between the target areas and a source area do not exhaust the source area. In other words, use the sum of the intersection area over the source area to form the percentage of the attribute to allocate. total, to me, seems to imply one would want to allocate the total value of the source area attribute value over the target areas.

[chris-prener]

Thanks @sjsrey - I appreciate your feedback. We can absolutely address your last point to clarify sum and total. We can also clarify point two a bit in the documentation.

Re: your first bullet - I imagine there would be speed issues with a large n... a benchmark where we interpolate from state to counties might possibly illustrate speed constraints?

In any event - we can address these points in an updated draft. Will post here when the paper manuscript and associated documentation for the package has been updated. @lheagy - aside from addressing reviewer concerns, are there any other steps we need to take at this stage?

[lheagy]

Thanks for getting in touch @chris-prener, addressing reviewer comments is the only thing that needs to be done at this stage. Please ping again when you feel they have all been addressed and we can proceed from there.

Many thanks @edzer and @sjsrey for your feedback!

[labarba]

👋 @chris-prener — How are you getting along? It looks like we're waiting here for you to respond to the reviewer comments. Can you give us a status update?

[chris-prener]

Hi @labarba and @lheagy - good - should have revisions wrapped up this week. I'll check in on Saturday at the latest.

[chris-prener]

We would like to thank both @edzer and @sjsrey as well as @lheagy for the feedback and the opportunity to revise both the software and the manuscript. We believe that the manuscript has been greatly strengthened as a result of your collective feedback and are excited to resubmit it for your review. @lheagy, if there is a better way to embed tables and to handle the appendix file we've created (available here), please let us know - we're happy to adapt both to any style that JOSS prefers.

Reviewer 1 - @edzer

• The pdf of the paper shows R code on page 2, but this code is hidden where it runs off the page at the side.

  • The example has been changed to return a tibble object rather than an sf object. A new line was added below the example that clarifies the sf functionality as well.

• The manuscript claims it provides functions that "validate data suitability for areal interpolation", but does not explain what this validation does. What does it do?

  • A description of the validation process has been added to the manuscript in the section titled The areal R package.

• given that the package does little more than sf::st_interpolate_aw, and given that that function was available first, the added value of the packages would become more clear when it would mention the name of that function (rather than refer to "the existing functionality in sf"),

  • A direct reference to sf::st_interpolate_aw has been added to the first paragraph of the section titled The areal R package.

• show in a side-by-side comparison that areal::aw_interpolate and sf::st_interpolate_aw give identical results for an intensive an extensive variable

  • This is included in the new A Quick Comparison with sf section with two figures, one for extensive interpolations and one for intensive interpolations.

• give an example where areal::aw_interpolate does something different when there is a difference in areas, and show how large the effect of doing this is

  • This is included in the new A Quick Comparison with sf section with a figure and a description of the difference as well as why one approach may be preferable over the other.

• the correct reference for Pebesma, E. (2018) is found here

  • This has been corrected

• change the wording of "black box", as this is not a black box. Closed source software is a black box

  • This has been changed to:

  "for users who need to unpack the interpolation workflow"

• the areal-weighted-interpolation vignette mentions "Spatially intensive operations are used when the data to be interpolated are a ratio." I'm afraid it is not this simple: a counter example is is CO2 emissions measured in tons/year: an extensive variable when interpolated spatially.

  • This has been changed to:

  "Spatially intensive operations are used when the data to be interpolated are, for example, a percentage or density value."

• Additionally, @edzer provided feedback about two packages listed as dependencies that may not be necessary.

  • Both lwgeom and tibble have been removed as dependencies

Reviewer 2 - @sjsrey

• Scaling: the current examples are well crafted and illustrate the core functionality. At the same time n is fairly modest here and one wonders if these methods were going to be used for larger n problems, or applied iteratively over many cities , would there be any bottlenecks users should be aware of?

  • We have added benchmarks to the end a new section titled Performance Notes as well as a discussion of a special case that areal handles, which is when geometry collections are returned by sf::st_intersection(). The process for handling this special case is more resource intensive and results in longer processing times.

• The distinction between extensive and intensive variables is handled nicely. One case that might also be considered is the choice between interpolation of an intensive variable directly versus deriving the intensive estimates as a ratio of two extensive variables that have been estimated

  • Mindful of the short length of JOSS manuscripts, we have included a discussion of this in the vignette on areal weighted interpolation in the section entitled Mixed Interpolations.

• The weight argument names are a bit confusing.

  • Since the package is already on CRAN, we are reluctant to change the argument. In the paper, however, we have made two clarifications to address this. The first was to explicitly link the names for both weights to their descriptions in the second to last paragraph of the section The areal R package. They now read:

  "...we offer a formula that matches the existing functionality in sf, which is based on the total area of the original source feature (specified with weight = "total")."

  "This uses a sum of the source feature areas remaining after the data are intersected as part of the spatial weight calculation process (specified with weight = "sum")."

  We also have added a section titled A Quick Comparison with sf that illustrates the difference between these two approaches, and includes a brief discussion of the selection process between both in the second and third full paragraphs. It includes the following language:

  "If we expect that our source and target data should overlap completely (but perhaps do not because of data quality issues), the "sum" approach will allocate all individuals into target features whereas "total"will not, instead allocating only a proportion of individuals relative to the overlap between the source and target features. In the example data provided in the areal package, this is the case - the Census tracts do not perfectly map onto the extent of the wards, and so the "total" approach is inappropriate."

[lheagy]

Many thanks @chris-prener for your thorough response!

👋 Hi @edzer, @sjsrey: it looks like most of the items on your checklist are checked-off. Do you have any remaining comments before we proceed with accepting the submission?

[sjsrey]

I think the author has responded to the points I raised, and I have no further comments. Looking forward to seeing it published.

[lheagy]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[lheagy]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

OK DOIs

- 10.32614/RJ-2018-009 is OK

MISSING DOIs

- https://doi.org/10.1016/j.compenvurbsys.2005.07.005 may be missing for title: Rapid facilitation of dasymetric-based population interpolation by means of raster pixel maps
- https://doi.org/10.1080/00182494.1973.10112670 may be missing for title: The linkage of data describing overlapping geographical units
- https://doi.org/10.2747/1548-1603.49.5.644 may be missing for title: The development of an areal interpolation ArcGIS extension and a comparative study

INVALID DOIs

- None

[lheagy]

@chris-prener: I left a few comments for grammar in the paper in chris-prener/areal#20, and it looks like there are a few missing doi's in the references. Would you please take a look at these and ping here when you are done? Thanks!

[lheagy]

👋 Hi @chris-prener just checking in - have you had a chance to take a look at the suggestions in chris-prener/areal#20?

[kyleniemeyer]

@whedon check references

[whedon]

Attempting to check references...

[whedon]

OK DOIs

- 10.1559/152304083783914958 is OK
- 10.1016/j.compenvurbsys.2005.07.005 is OK
- 10.1080/00182494.1973.10112670 is OK
- 10.32614/RJ-2018-009 is OK
- 10.5281/zenodo.2603540 is OK
- 10.2747/1548-1603.49.5.644 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[kyleniemeyer]

@chris-prener some minor edits for the paper:

• could you add full affiliation details (i.e., location) for the authors?
• the first paragraph ends in a comma

[chris-prener]

@whedon generate pdf

[whedon]

Attempting PDF compilation. Reticulating splines etc...

[whedon]

👉 Check article proof 📄 👈

[chris-prener]

@kyleniemeyer and @lheagy - made the two changes Kyle requested, and tagged a new released with the updated paper manuscript. The Zenodo DOI for the newest release is - 10.5281/zenodo.2857598

[kyleniemeyer]

@chris-prener sorry, looks like Zenodo is having some database issues right now, so I'm going to hold off moving forward until we can confirm the archive. Should be resolved within the day, I hope.

[chris-prener]

@kyleniemeyer and @lheagy - looks like everything is back up on the Zenodo end. the DOI is resolving correctly and Zenodo has the correct version of the updated software.

[arfon]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

OK DOIs

- 10.1559/152304083783914958 is OK
- 10.1016/j.compenvurbsys.2005.07.005 is OK
- 10.1080/00182494.1973.10112670 is OK
- 10.32614/RJ-2018-009 is OK
- 10.5281/zenodo.2603540 is OK
- 10.2747/1548-1603.49.5.644 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

Check final proof 👉 openjournals/joss-papers#704

If the paper PDF and Crossref deposit XML look good in openjournals/joss-papers#704, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.

@whedon accept deposit=true

[arfon]

@whedon accept deposit=true

[whedon]

Doing it live! Attempting automated processing of paper acceptance...

[whedon]

Posted to the Twitters: https://twitter.com/JOSS_TheOJ/status/1130248728525385728

[whedon]

🚨🚨🚨 THIS IS NOT A DRILL, YOU HAVE JUST ACCEPTED A PAPER INTO JOSS! 🚨🚨🚨

Here's what you must now do:

0. Check final PDF and Crossref metadata that was deposited 👉 Creating pull request for 10.21105.joss.01221 joss-papers#705
1. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.01221
2. If everything looks good, then close this review issue.
3. Party like you just published a paper! 🎉🌈🦄💃👻🤘

Any issues? notify your editorial technical team...

[arfon]

@sjsrey, @edzer - many thanks for your reviews here and to @lheagy for editing this submission ✨

@chris-prener - your paper is now accepted into JOSS ⚡🚀💥

[whedon]

🎉🎉🎉 Congratulations on your paper acceptance! 🎉🎉🎉

If you would like to include a link to your paper from your README use the following code snippets:

Markdown:
[![DOI](http://joss.theoj.org/papers/10.21105/joss.01221/status.svg)](https://doi.org/10.21105/joss.01221)

HTML:
<a style="border-width:0" href="https://doi.org/10.21105/joss.01221">
  <img src="http://joss.theoj.org/papers/10.21105/joss.01221/status.svg" alt="DOI badge" >
</a>

reStructuredText:
.. image:: http://joss.theoj.org/papers/10.21105/joss.01221/status.svg
   :target: https://doi.org/10.21105/joss.01221

This is how it will look in your documentation:

We need your help!

Journal of Open Source Software is a community-run journal and relies upon volunteer effort. If you'd like to support us please consider doing either one (or both) of the the following:

• Volunteering to review for us sometime in the future. You can add your name to the reviewer list here: http://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.salsalabs.org/donate-to-joss

[chris-prener]

@lheagy or @arfon - one follow-up question - does Google Scholar index JOSS publications right now? Googled around but didn't seem to find a clear answer...

[arfon]

@lheagy or @arfon - one follow-up question - does Google Scholar index JOSS publications right now? Googled around but didn't seem to find a clear answer...

Yes, but based on historical performance, it can take a month or two for them to show up.

[chris-prener]

Thanks @arfon!