Joss-reviews: [REVIEW]: Peacock.jl: Photonic crystals in Julia

[whedon]

Submitting author: @sp94 (Samuel John Palmer)
Repository: https://github.com/sp94/Peacock.jl
Version: 0.1.1
Editor: @dpsanders
Reviewer: @mlxd, @nmoran
Archive: 10.5281/zenodo.4097236

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

Status

Status badge code:

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

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) by leaving comments 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

@mlxd & @nmoran, 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.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @dpsanders know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Review checklist for @mlxd

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@sp94) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] 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

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] 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

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

Review checklist for @nmoran

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

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

General checks

• [x] Repository: Is the source code for this software available at the repository url?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@sp94) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] 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

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] 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

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[whedon]

Hello human, I'm @whedon, a robot that can help you with some common editorial tasks. @mlxd, @nmoran it looks like you're currently assigned to review this paper :tada:.

:warning: JOSS reduced service mode :warning:

Due to the challenges of the COVID-19 pandemic, JOSS is currently operating in a "reduced service mode". You can read more about what that means in our blog post.

: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:

1. 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

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@whedon generate pdf

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- None

MISSING DOIs

- 10.1088/1367-2630/ab3f71 may be a valid DOI for title: Band topology in classical waves: Wilson-loop approach to topological numbers and fragile topology
- 10.1364/oe.8.000173 may be a valid DOI for title: Block-iterative frequency-domain methods for Maxwell’s equations in a planewave basis
- 10.1103/physrevb.95.075146 may be a valid DOI for title: Z2Pack: Numerical implementation of hybrid Wannier centers for identifying topological materials

INVALID DOIs

- https://doi.org/10.1073/pnas.2133313100 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1007/978-1-4615-1963-8_41 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1103/physrevlett.58.2486 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1038/nature01940 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1126/science.1133734 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1103/physrevlett.114.223901 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1103/physrevresearch.1.032005 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1002/qute.201900117 is INVALID because of 'https://doi.org/' prefix
- https://doi.org/10.1063/1.5086433 is INVALID because of 'https://doi.org/' prefix

[whedon]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[sp94]

@whedon check references

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1073/pnas.2133313100 is OK
- 10.1007/978-1-4615-1963-8_41 is OK
- 10.1103/physrevlett.58.2486 is OK
- 10.1038/nature01940 is OK
- 10.1103/PhysRevLett.95.146802 is OK
- 10.1103/PhysRevLett.95.226801 is OK
- 10.1126/science.1133734 is OK
- 10.1103/physrevlett.114.223901 is OK
- 10.1103/physrevresearch.1.032005 is OK
- 10.1002/qute.201900117 is OK
- 10.1063/1.5086433 is OK
- 10.1088/1367-2630/ab3f71 is OK
- 10.1364/OE.8.000173 is OK
- 10.1103/PhysRevB.95.075146 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[sp94]

@whedon generate pdf

[whedon]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[sp94]

@whedon generate pdf

[whedon]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[nmoran]

Myself and @mlxd are current colleagues at the same centre (ICHEC). I did not see anything specific mentioned in the COI policy that would make this a conflict of interest but thought I would check just in case?

[dpsanders]

Thanks for pointing that out. I'll look for an additional reviewer then.

[nmoran]

Installed the package alright and ran initial examples but getting the following error when trying to plot the Wilson loop winding https://github.com/sp94/Peacock.jl/issues/9.

[sp94]

Thanks! sp94/Peacock.jl#9 should be fixed now. I haven't tagged a new release yet so could you run ]dev Peacock in the REPL to check?

I missed this because I wasn't running the plot functions on Travis as I didn't know a good way to test the outputs. I've now added the plot functions to at least pick up runtime errors like this, even if the outputs are still going untested

[dpsanders]

👋 @PhilipVinc: Would you be able to review this submission for JOSS?

[mlxd]

hi @sp94 I have added two issues https://github.com/sp94/Peacock.jl/issues/11 and https://github.com/sp94/Peacock.jl/issues/12 to finish my review. Once these are resolved, and the final version tagged for release I am happy to give this a thumbs-up.

[sp94]

Thanks for your time @nmoran and @mlxd! I believe I've resolved these issues now.

I've tagged v0.1.1 with these fixes and will edit once it the registration is complete

Edit: v0.1.1 should be released

[sp94]

Hi @dpsanders, any update?

[dpsanders]

👋 @nmoran and @mlxd, have you finished your reviews and are you happy to proceed with publication? Thanks!

[mlxd]

Hi @dpsanders all boxes ticked for me. I'm happy for this to proceed.

[nmoran]

Hi @dpsanders, yes I'm also happy to proceed with publication.

[sp94]

Hi @dpsanders, as the reviewers are happy I've deposited v0.1.1 to Zenodo, the DOI is 10.5281/zenodo.4097236. I've set the Zenodo title and authors to match the JOSS paper.

[dpsanders]

@whedon generate pdf

[whedon]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[sp94]

@whedon check references

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1073/pnas.2133313100 is OK
- 10.1007/978-1-4615-1963-8_41 is OK
- 10.1103/PhysRevLett.58.2486 is OK
- 10.1038/nature01940 is OK
- 10.1103/PhysRevLett.95.146802 is OK
- 10.1103/PhysRevLett.95.226801 is OK
- 10.1126/science.1133734 is OK
- 10.1103/PhysRevLett.114.223901 is OK
- 10.1103/PhysRevResearch.1.032005 is OK
- 10.1002/qute.201900117 is OK
- 10.1063/1.5086433 is OK
- 10.1088/1367-2630/ab3f71 is OK
- 10.1364/OE.8.000173 is OK
- 10.1103/PhysRevB.95.075146 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[sp94]

@whedon generate pdf

[whedon]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[dpsanders]

Thanks @sp94, I think we're ready to proceed with publication!

[dpsanders]

@whedon accept

[whedon]

No archive DOI set. Exiting...

[dpsanders]

@whedon commands

[whedon]

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

# Re-invite a reviewer (if they can't update checklists)
@whedon re-invite @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

# Set the software version at the top of the issue e.g.
@whedon set v1.0.1 as version

# Open the review issue
@whedon start review

EDITORIAL TASKS

# All commands can be run on a non-default branch, to do this pass a custom 
# branch name by following the command with `from branch custom-branch-name`.
# For example:

# Compile the paper
@whedon generate pdf

# Compile the paper from alternative branch
@whedon generate pdf from branch custom-branch-name

# Remind an author or reviewer to return to a review after a
# certain period of time (supported units days and weeks)
@whedon remind @reviewer in 2 weeks

# Ask Whedon to do a dry run of accepting the paper and depositing with Crossref
@whedon accept

# Ask Whedon to check the references for missing DOIs
@whedon check references

# Ask Whedon to check repository statistics for the submitted software
@whedon check repository

EiC TASKS

# Invite an editor to edit a submission (sending them an email)
@whedon invite @editor as editor

# Reject a paper
@whedon reject

# Withdraw a paper
@whedon withdraw

# Ask Whedon to actually accept the paper and deposit with Crossref
@whedon accept deposit=true

[dpsanders]

@whedon set 0.1.1 as version

[whedon]

OK. 0.1.1 is the version.

[dpsanders]

@whedon set 10.5281/zenodo.4097236 as archive

[whedon]

OK. 10.5281/zenodo.4097236 is the archive.

[dpsanders]

@whedon accept

[whedon]

Attempting dry run of processing paper acceptance...

[whedon]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1073/pnas.2133313100 is OK
- 10.1007/978-1-4615-1963-8_41 is OK
- 10.1103/PhysRevLett.58.2486 is OK
- 10.1038/nature01940 is OK
- 10.1103/PhysRevLett.95.146802 is OK
- 10.1103/PhysRevLett.95.226801 is OK
- 10.1126/science.1133734 is OK
- 10.1103/PhysRevLett.114.223901 is OK
- 10.1103/PhysRevResearch.1.032005 is OK
- 10.1002/qute.201900117 is OK
- 10.1063/1.5086433 is OK
- 10.1088/1367-2630/ab3f71 is OK
- 10.1364/OE.8.000173 is OK
- 10.1103/PhysRevB.95.075146 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[whedon]

:wave: @openjournals/joss-eics, this paper is ready to be accepted and published.

Check final proof :point_right: https://github.com/openjournals/joss-papers/pull/1860

If the paper PDF and Crossref deposit XML look good in https://github.com/openjournals/joss-papers/pull/1860, then you can now move forward with accepting the submission by compiling again with the flag deposit=true e.g.
@whedon accept deposit=true

[kyleniemeyer]

Hi @sp94, in processing your submission, I noticed that Figure 1 references the Zi et al. 2003 PNAS paper for the copyright for part of it. In general, one would need to obtain permission from a publisher for reusing a figure from a published article, unless shared under a CC BY (or similar) license which explicitly gives permission. According to their policies, PNAS retains copyright for articles published up to 2008 (since the, the authors retain copyright).

Can you please reach out and get permission to use the image from that article, or find an alternative?

[sp94]

Hi @kyleniemeyer, we contacted PNAS and they confirmed that publishing in the JOSS counts as non-commercial usage, and express permission isn't required so long as we include that copyright notice.

Here is their full reply:

Thank you for checking. Yes, this qualifies as non-commercial use. Express permission from PNAS is not required if all of the following conditions hold true:

• The PNAS article published in 1993 to present under our standard exclusive license (we started offering two other licenses in Fall 2017)

• The requested material (whether figure, table, text extract) is original to the PNAS article (it does not contain previously published material, nor was adapted from an earlier source)

• The intended use is for noncommercial or educational purposes

If the article published between 1993 and 2008: Please include a complete citation for the original PNAS article when reusing the material, and include "Copyright (YEAR) National Academy of Sciences, U.S.A." as a copyright note.

If the article published from 2009 to present: Please include a complete citation for the original PNAS article when reusing the material (do not include a copyright note).

[kyleniemeyer]

Great! Thanks for sharing that response.

[kyleniemeyer]

@whedon accept deposit=true

[whedon]

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

[whedon]

🐦🐦🐦 👉 Tweet for this paper 👈 🐦🐦🐦

[whedon]

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

Here's what you must now do:

1. Check final PDF and Crossref metadata that was deposited :point_right: https://github.com/openjournals/joss-papers/pull/1865
2. Wait a couple of minutes to verify that the paper DOI resolves https://doi.org/10.21105/joss.02678
3. If everything looks good, then close this review issue.

4. Party like you just published a paper! 🎉🌈🦄💃👻🤘

   Any issues? Notify your editorial technical team...

[kyleniemeyer]

Congrats @sp94 on your article's publication in JOSS!

Many thanks to @mlxd and @nmoran for reviewing this, and @dpsanders for editing it.

[whedon]

:tada::tada::tada: Congratulations on your paper acceptance! :tada::tada::tada:

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

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

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

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

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: https://joss.theoj.org/reviewer-signup.html
• Making a small donation to support our running costs here: https://numfocus.org/donate-to-joss

[dpsanders]

Congrats @sp94!

Many thanks to @nmoran and @mlxd for the reviews, and to @kyleniemeyer for overseeing the process.

[sp94]

Great! Thanks @kyleniemeyer for overseeing, @dpsanders for editing (your comments in the prereview were really helpful), and @nmoran and @mlxd for reviewing!