3

I'm not a software developer by trade but I am in the process of writing a Python package which models an experimental apparatus and physical process and generates simulated data. Results can be used to compare to measure data and extract physical parameters, or to predict how an apparatus will perform in order to modify or optimize it.

I'm aware of Github and Python Package Index and will make the software available through Github and hopefully PyPI though the latter may be a challenge for a first time package author.

I will then want to submit a paper for publication in an appropriate journal explaining the details (math and physics) of how the calculation works and demonstrate its agreement with measured data which would then refer to the software's source page(s).

Question: What kind of roadmap should I prepare for myself in order to do this smoothly and efficiently, and what are some likely pitfalls someone publishing for the first time may face?

I should note that there are one or two legacy packages that perform a somewhat similar set of functions, but they are roughly a decade old or more and available as compiled .exe files rather than open-source packages. I'm not using these or reverse-engineering them, but there will none-the-less be some overlapping in function.

Improve this question
6
  • different but somewhat related in that the answers and their links are instructive: Does building a Python library fall in the category of research? and also What is the threshold for a software paper to be publishable?
    – uhoh
    Jan 30, 2020 at 6:44
  • PyPI […] may be a challenge for a first time package author – Why? PyPI has not requirements for contributors AFAICT.
    – Wrzlprmft ♦
    Jan 30, 2020 at 14:09
  • @Wrzlprmft because there is a review and there are several requirements that need to be met before they will accept a package packaging.python.org/tutorials/packaging-projects First time package authors may find this more of a challenge than those who have done it several times.
    – uhoh
    Jan 30, 2020 at 14:14
  • because there is a review – I fail to find any mention of this on the linked web page. In my experience (which is a few years old), packaging is a bit tedious, but not an insurmountable barrier.
    – Wrzlprmft ♦
    Jan 30, 2020 at 15:53
  • @Wrzlprmft I'm confident that it "may be a challenge for a first time package author" is true as written. I never said anything about "an insurmountable barrier". I'm also pretty sure that humans review submitted packages before they are made available to the public on PyPL, as well as there being automated checks in place.
    – uhoh
    Jan 31, 2020 at 0:55

1 Answer 1

Reset to default
2

I published a paper on a Python package myself.

Finding a journal

My main recommendation is to start looking for a journal now, even before you start writing. Unless journals in your particular subfield of choice is very open to software papers, there are likely only a few journals you can choose from and those may have special requirements. These requirements may not be obvious and if you do not fulfil them on your first submission, you may not get a second chance, which in turn is particularly bad if alternative journals are scarce. Depending on the requirements, you may need to write your paper completely differently.

I would proceed as follows:

  • Find a journal whose target audience are potential users of your software.

  • Does the journal clearly state that it accepts software papers? If yes, do they clearly state the requirements for acceptance?

  • Are there any precedents of software papers in the journal? If yes, is any of them comparable to what you are going to do? Comparable here less refers to what the software does, but on how it is “sold” and what the paper does beyond software. For example, it could be that a software paper only got accepted through featuring new algorithms and yours may be rejected because it doesn’t.

  • When in doubt, contact the journal briefly outlining what your paper would contain and ask them whether they would consider publishing a paper of this kind.

In my case, the journal had a clearly stated policy for software papers and there was an existing paper for a competing software. Still, I encountered problems with one of the reviewers recommending to reject the paper on account of being a technical manual.

Consult field experts

Going by your question, you may not belong to the typical target audience of your software. If that is the case, try to solicit assistance from somebody in the target audience (if you do not have one at hand anyway), as to what they consider important in your kind of software or what they think about features of your software. You do not want to focus on a part of your software that the majority of your target audience doesn’t care about.

Also, by all means let somebody from the field who has not used your software review your manuscript before you submit. (There is even less need to worry about plagiarism here since you probably already published your software it this point.)

Writing process

Getting inspiration

There are many variants of software papers. I have seen some without any code (despite the software being a code library) and those with a lot. If the previous did not yield any clear recommendation in this respect, look for well-received software papers and let them inspire you. (Beware that a crappy software paper may be well cited because the software is popular despite the paper.)

Examples

Whether with code or not, you are likely to feature some examples. These usually only belong in one of the following categories:

  • Didactic examples that demonstrate how your software works. I found it very helpful to choose these with extreme care.

    For example, for me it was pretty clear that I needed five didactic examples that could not possibly be combined, but each of which could be chosen from a wide selection of use cases. I optimised some of these cases to be as simple as possible. I chose the remaining ones to exemplify other things as a side effect, so I would not need separate examples for these. (On the other hand, you do not want to leave the impression that everything is a special case requiring tricks.)

    Do not blindly take the examples from your documentation, because these are aiming at readers who are familiar with Python, have your software installed, and can directly test things. Also, your target audience in the journal is different. For example, it also includes professors who have last programmed twenty years ago in Fortran, but who may make some supervisee use your software. Importantly, the reviewers belong in this category. For instance, in my paper I took care not to use any advanced, non self-explaining features of Python in my examples, unless absolutely necessary (and Python is rather benign in this respect).

  • Impressing examples that demonstrate that your software is capable of handling particularly difficult cases, e.g., ones that no software before could handle or that are considerably better in your software. It may also be cases that show that your software can actually further science by doing facilitating novel results. It strongly depends on your software and the journal whether you need this, to what extent, and what to optimise for. Either way, again this example should be carefully chosen. If you show code in your paper, you also want to make sure that the example is not overly long.

Selling your software

Make it very clear why people should use your software as opposed to an existing one or doing everything by hand. Do not forget that usability may be a relevant feature.

This is also crucial for the review process: You have to convince the reviewers and journal that your software is something the readers have to read about. If the journal does not require a significance statement upon submission, consider to volunteer one anyway.

Improve this answer
2

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .