search

openjournals / joss-reviews

Reviews for the Journal of Open Source Software
Creative Commons Zero v1.0 Universal
700 stars 36 forks source link

[REVIEW]: py-opc: operate the Alphasense OPC-N2 from a raspberry pi or other popular microcontrollers/microcomputers #782

Closed whedon closed 6 years ago

whedon commented 6 years ago

Submitting author: @dhhagan (David Henry Hagan) Repository: https://github.com/dhhagan/py-opc Version: v1.6.0 Editor: @Kevin-Mattheus-Moerman Reviewer: @tshu Archive: 10.5281/zenodo.1299205

Status

status

Status badge code:

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

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

@tshu, 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 @Kevin-Mattheus-Moerman know.

Review checklist for @tshu

Conflict of interest

Code of Conduct

General checks

Functionality

Documentation

Software paper

whedon commented 6 years ago

Hello human, I'm @whedon. I'm here to help you with some common editorial tasks. @tshu it looks like you're currently assigned as the reviewer for this paper :tada:.

:star: Important :star:

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:

watching

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

notifications

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

@whedon commands
whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

@dhhagan this is where the review takes place. My colleague @tshu has the device and will start review shortly.

Kevin-Mattheus-Moerman commented 6 years ago

Hi @dhhagan your references field in the paper appears empty. Can you check this out? If you make changes to the paper and want to re-generate the pdf here you can also use: @whedon generate pdf Let me know if you have questions.

dhhagan commented 6 years ago

@Kevin-Mattheus-Moerman Interesting - I thought they were supposed to be somehow pulled from the bib file? I tried copying over from some accepted repositories; is there an easy way to pull them in this way?

arfon commented 6 years ago

@dhhagan - you need to cite them directly for them to be included in the compilation. (You can read how to do that here)

tshu commented 6 years ago

@dhhagan Thanks for your submission. I should be able to finish this end of week so long as there are no major roadblocks. I will keep you posted if there are any.

dhhagan commented 6 years ago

@whedon commands

whedon commented 6 years ago

Here are some things you can ask me to do:

# List all of Whedon's capabilities
@whedon commands

# Assign a GitHub user as the sole reviewer of this submission
@whedon assign @username as reviewer

# Add a GitHub user to the reviewers of this submission
@whedon add @username as reviewer

# Remove a GitHub user from the reviewers of this submission
@whedon remove @username as reviewer

# List of editor GitHub usernames
@whedon list editors

# List of reviewers together with programming language preferences and domain expertise
@whedon list reviewers

# Change editorial assignment
@whedon assign @username as editor

# Set the software archive DOI at the top of the issue e.g.
@whedon set 10.0000/zenodo.00000 as archive

# Open the review issue
@whedon start review

🚧 🚧 🚧 Experimental Whedon features 🚧 🚧 🚧

# Compile the paper
@whedon generate pdf
dhhagan commented 6 years ago

@Kevin-Mattheus-Moerman @arfon Is there a way to update the version number being reviewed? Since it's been a while since submission, the software is now at v1.6 as opposed to 1.4.1.

dhhagan commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

dhhagan commented 6 years ago

@arfon Is there a way to locally generate the pdf to validate the references show up? It seems like there must be an error with the BibTex syntax, but I can't seem to figure out what's going on. Is there any output from the @whedon generate pdf command?

arfon commented 6 years ago

@dhhagan does this help? https://github.com/greatfireball/docker_whedon_translate4joss

This is the command that Whedon executes to compile the PDF.

tshu commented 6 years ago

@dhhagan I've added issues #68-70 at https://github.com/dhhagan/py-opc/issues. In addition to these, the pypi package version is 1.5.0 as listed on the repository while the review sheet is still at 1.4.1. I have updated the review sheet so that we are considering 1.5.0. Finally, the references in the paper.md are still in the wrong location.

Once the issues are addressed, I'll be happy to finish checking off the boxes.

dhhagan commented 6 years ago

@tshu Thanks for the help! I have fixed most of the concerns and will merge/push later today. I am still trying to figure out what is wrong with the references - seems to be a syntax error somewhere in paper.bib. Also, the final version with changes you suggested will be at v1.6.1. Is that an issue?

Kevin-Mattheus-Moerman commented 6 years ago

@dhhagan in relation to the release/version number. This is no problem. We can update the version number at a later stage.

tshu commented 6 years ago

@whedon generate pdf

tshu commented 6 years ago

@dhhagan Everything looks good. Once I can check the pdf for fixed references, my review will be complete.

@Kevin-Mattheus-Moerman whedon isn't working?

Kevin-Mattheus-Moerman commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

hmm perhaps only authors and editors can call whedon like that. Anyway the PDF is now regenerated.

dhhagan commented 6 years ago

Thanks @tshu I'll try and figure out what's wrong with the papers.bib file a bit later today...not sure what's going on there.

Kevin-Mattheus-Moerman commented 6 years ago

@dhagan did you try building the paper locally to trouble shoot this? perhaps remove the references and add a sigle bib file entry at a time to try to figure out what is going on.

arfon commented 6 years ago

The issue here is that you're not actually citing your references in the paper.md file which means they aren't included by Pandoc. Can you cite them directly please? (You can read how to do that here)

danielskatz commented 6 years ago

\hijack-thread-on

@arfon - can we provide some guidance on this in our docs? (which maybe just means pointing to the link you provided as part of a "how to write a JOSS paper and include references" section)

\hijack-thread-off

Kevin-Mattheus-Moerman commented 6 years ago

So @dhhagan it looks like you need to cite them inline in the text e.g. like:

Bla bla @py_usbiss and bla bla @py_spidev, bladibla @alphasense_opcn2.

Please also specifically cite the Crilley et al. article that is in review, this way it also appears in the reference list.

arfon commented 6 years ago

@arfon - can we provide some guidance on this in our docs? (which maybe just means pointing to the link you provided as part of a "how to write a JOSS paper and include references" section)

@danielskatz - we already having this in the example paper.md here: http://joss.theoj.org/about#author_guidelines but perhaps we could make this more obvious?


[rMarkdown](http://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html)
format.```
dhhagan commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

dhhagan commented 6 years ago

@arfon @Kevin-Mattheus-Moerman Thanks for the help - I didn't notice the individual citations throughout the abstract the first time around - I assumed it was just including the line bibliography: paper.bib. Regardless, it should be good now. Thanks!

dhhagan commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

@dhhagan great it looks like we are nearly there. @dhhagan 1) About the citation for doceme 2015, the author name field is a github name. Perhaps this is okay but it would be nice if we could replace this by a human name. I cannot see the name of this author either so perhaps we are forced to do it that way. @doceme How can we best cite you here?

@arfon 1) Do you know if the citations (doceme 2015, Tolmie (2016)) render okay? Seems inconsistent to have name date and name (date) like that, it seems to mix two formats? Or is that normal for our reference format, like one is rendered as a url accessed on a particular data and the other is an article citation? 2) For some reason all references in this paper have the date in them twice. Is this normal? Other papers do not seem to have it like that. I did notice that there is a year field as well as a urldate field in 3 of the 4 references but the 4th reference does not have that...

doceme commented 6 years ago

I just added my name (Stephen Caudle) to my profile. Feel free to use that.

Kevin-Mattheus-Moerman commented 6 years ago

@dhhagan @doceme wow this open peer review thing really works well eh: :rocket: :robot:

doceme commented 6 years ago

@Kevin-Mattheus-Moerman Open FTW!

Kevin-Mattheus-Moerman commented 6 years ago

@doceme thanks for "improving" your profile. Also, as a tip, and if you care (academics tend to) you could consider following these steps to create a citable DOI for your work: https://guides.github.com/activities/citable-code/. That way there is a common and permanent citable object. If you decide to do this and do it really soon let me know and we can add the DOI in the citation of the paper here. If not no worries then we'll leave it as is.

dhhagan commented 6 years ago

@whedon generate pdf

whedon commented 6 years ago 
Attempting PDF compilation. Reticulating splines etc...
whedon commented 6 years ago

--> Check article proof :page_facing_up: <--

Kevin-Mattheus-Moerman commented 6 years ago

Nice @dhhagan. Now I'll just wait for @arfon to weigh in on my questions about those references but other than that we are in good shape.

doceme commented 6 years ago

@Kevin-Mattheus-Moerman Done.

arfon commented 6 years ago

Do you know if the citations (doceme 2015, Tolmie (2016)) render okay? Seems inconsistent to have name date and name (date) like that, it seems to mix two formats? Or is that normal for our reference format, like one is rendered as a url accessed on a particular data and the other is an article citation?

This can be fixed by citing the papers like this [@py_spidev; @py_usbiss]

For some reason all references in this paper have the date in them twice. Is this normal? Other papers do not seem to have it like that. I did notice that there is a year field as well as a urldate field in 3 of the 4 references but the 4th reference does not have that...

I think this is because these are type online. The Crilley:2018 reference should be article type which will remove the extra date.

dhhagan commented 6 years ago

@whedon generate pdf