[JOSS Review] Paper Feedback

[sea-bass]

Thank you for submitting pyswarming to JOSS! As one of your reviewers, I'll collect a few issues here with the paper submission itself.

General Comments

I think the "Related Software Packages" section should come in earlier in the paper, before you introduce PySwarming. This should serve as part of your introduction leading to the "meat" of the paper, and meet the JOSS expectation below:

• State of the field: Do the authors describe how this software compares to other commonly-used packages?

Do the authors have any other published work that uses PySwarming? If so, it's a great opportunity to include this in the references, if it has not yet been added.

Lastly, the paper is missing a conclusion! Please add one.

---

Summary

The summary seems like it abruptly switches from an introduction to swarm robotics to a list of things that PySwarming can do. Consider making this a bit more gentle by following a layout like this:

• Introduce swarm robotics
• Identify the need for standard tooling for development/benchmarking/etc.
• Explicitly say something like "we introduce PySwarming, a tool that does XYZ"
• Briefly say what the tool does (see next paragraph) and what this paper covers.

On the note of "briefly say what the tool does", I think in your summary the citations to leaderless coordination, preferred direction, aggregation, etc. Consider talking about these algorithms in a separate section. Most papers will have

• Abstract: one paragraph similar to your summary, but a bit more brief and with little to no citations
• Introduction: A few paragraphs that perform a brief literature review (where these citations could go), plus the current state of the art methods. In the context of JOSS, this is where you could talk about related software packages such as Buzz.

---

Example Usage

I like this section! The only thing I would suggest here is maybe adding more details about how a user might use this tool to create their own new behaviors. The paper advertises that PySwarming is flexible and easy to extend, so it's worthwhile to talk about that a little bit.

---

Related Software Packages

• Typo: the first paragraph refers to "PySwarm", change to "PySwarming".
• I think this list could probably be expanded a little bit. I'm sure there are more than just the few resources pointed out, see e.g. this paper: https://www.mdpi.com/2079-3197/10/6/80
• If you have mentioned Carlo Pinciroli's Buzz programming language, you should also mention his ARGoS simulator: https://www.argos-sim.info/
• You should not mention your own contribution in this section, so you can remove that 3rd paragraph and move it to sections where you are talking about PySwarming.

https://github.com/openjournals/joss-reviews/issues/5647

[mrsonandrade]

@sea-bass, thank you very much for all the feedback. I have worked on all the points that you have mentioned above:

• General Comments;
• Summary;
• Example Usage;
• Related Software Packages;

Let me know what you think. And again, thank you for your time!

[sea-bass]

Somehow the editorialbot on the original issue isn't updating the paper, but I took a look at the updated markdown file for now.

It's looking good, I still have some additional comments.

Introduction

• I think generally, the introduction could do a better job of differentiating between the types of software related to swarm robotics. Particularly in "Related Software Packages" section, there is room to organize the software between simulators (ARGoS, Stage, etc.) and packages for behaviors (Buzz, ROS2Swarm, etc.). This will also let you more precisely position PySwarming in this category.
• You need to mention what need PySwarming meets. It's not the entire set of hardware+software needs, so what is it? My impression is that Python is arguably one of the most accessible languages for learning and prototyping today, so having a toolbox of standard swarm behavior primitives that someone can get going in < 1 hour can help lower the barrier for newcomers to the field, plus help more expert practitioners do basic prototyping of behaviors before trying to deploy them to embedded hardware. I think you have a more vague version of this in the "PySwarming" section, but it might be better served here instead.
• I also think you can explicitly say that a lot of the tools above, even if they may be capable, are NOT written in Python, so that in itself is a need being met by this tool!
• The statement of need is pretty sparse in general. Consider rolling in some of the discussions in the previous bullet point into that paragraph?
• Lastly, the Introduction section should also have some sentence saying "because of ABC, we introduce PySwarming, which does XYZ"

Example Usage

• Instead of "mid and final results", say "intermediate and final results".
• I also think this example should have a repulsion component so that the "final" image doesn't show all the robots stacked on top of each other. It looks better visually, but also makes your example more compelling by adding a 3rd behavior primitive!
• My original comment on this section still persists: Suggest adding more details about how a user might use this tool to create their own new behaviors. The paper advertises that PySwarming is flexible and easy to extend, so it's worthwhile to talk about that a little bit. You link to examples, but just a few sentences describing the approach of adding new behaviors would go a long way.

[mrsonandrade]

Excellent! Thank you for the feedback!

These are the points that I have worked on:

1. differentiating between the types of software related to swarm robotics;
2. organize the software between simulators and packages for behaviors;
3. mention what need PySwarming meets;
4. rolling in more discussion in the statement of need;
5. add something like "because of ABC, we introduce PySwarming, which does XYZ";
6. instead of "mid and final results", say "intermediate and final results";
7. add a repulsion component in the example;
8. adding more details about how a user might use this tool to create their own new behaviors;
9. talk about the "PySwarming is flexible and easy to extend" a little bit.

Let me know what you think. And again 😃 , thank you for your time!!

PS: If you have an issue downloading the updated paper, you can access the actions and download the pdf from the Artifacts section.

[sea-bass]

Thank you! I really like your latest changes, and especially good to see you added the repulsion behavior to your example.

Only 2 remaining comments:

• The table of related software packages is a nice addition; however, the paragraph is very long and difficult to follow. I suggest breaking it up a bit, though the content is fine. I also think your post-table paragraphs are better at the beginning, as they introduce the two types of packages before getting into the list. So I'd rearrange a little as well.
• Typo: "In addition, the PySwarming package comes with a simple read-to-use simulation feature" -- there is a typo, should be "ready-to-use".

[mrsonandrade]

Great! I have split this paragraph into two: (1) from lines 31 to 39; and (2) from lines 39 to 55.

I did not get the idea in "your post-table paragraphs are better at the beginning". As I understood, are you talking about the paragraphs after the table (the statement of need)?

[sea-bass]

I did not get the idea in "your post-table paragraphs are better at the beginning". As I understood, are you talking about the paragraphs after the table (the statement of need)?

Yes, exactly! I think introducing the difference between simulation and behavior packages before going through the list and table may work better. Very minor.