3

There are several algorithms in my research area, and I'm the first to implement them all together in a R package with Rcpp. I'm working on a paper in which I'd like to compare those algorithms as well as introduce my R package.

This is my first time to introduce a package in my paper and I have no idea what kind of things readers might be interested in, for example, the implementation detail, the usage example or some benchmarks? Are there any general suggestions for these kind of papers?

1
  • Many packages for R and other platforms were formally published in a paper. Read a few such papers and see what's the trend. Sep 9, 2023 at 17:56

2 Answers 2

3

The first suggestion is to read other papers of this kind. Have a look at the Journal of Statistical Software, which has many such papers. When it comes to comparison of algorithms, it depends to some extent on your ambition. The Journal of Statistical Software has papers that are mainly about introducing a package, give usage examples, discuss options etc. (these also normally need to introduce the algorithms that are implemented, as you often wouldn't expect every reader to know all of these).

Data examples should be chosen so that they work well illustrating important features of the software and how it makes sense to use them. Data visualisation often helps a lot; not sure whether your package has tools for visualisation, but even if not, think about how to produce informative data images based on the results of these algorithms.

A comparison can be just done exemplary on a few benchmark datasets and/or with a small simulation. However if you want to do a comprehensive comparison, the outcome of which could be general recommendations regarding when to use what algorithm, this requires much more effort, as you'd want to cover a sufficiently large range of relevant situations and explore them intensively enough that generalisation seems plausible (this depends of course on what exactly the algorithms are about). Maybe this kind of thing could merit a stand-alone paper, separated from the introduction of the package. (To give you an idea of the complexities, look at this.)

There are also papers that compromise, i.e., they do more comparison than the bare minimum to add a nice illustration to the package, but they don't do a full scale benchmark study. You may want to have a look at other journals in computational statistics to find those, and also fully developed benchmark studies.

In a paper that mainly features the package, implementation details may be of interest; in a paper that focuses more on the comparison, they may not be that relevant (it's hard to say what counts as "detail" in your description; if I knew the details I could have a strong opinion about some things you really should cover and some things that really don't seem very relevant; without knowing what this is about, it could be either way). So a major decision is really whether to focus on the package or the comparison, or to do "a bit of both", or maybe ultimately go for two papers.

Also always have a target audience in mind, and ask yourself what these people need and would be interested in. A starting point would be what you would be interested in reading other people's papers of this kind.

1

Completely agree with the recommendation to submit to JSS. For technical and scientific writing, the first three paragraphs of the Introduction section should always be based on what's known with citations/references, what's unknown with citations/references, and how this paper is structured and how it contributes to the literature.

For your manuscript, what's known is that there are drawbacks of existing methods or packages. So think of all the reasons why you developed your algorithm. For software, I like to make paragraph 1 focus on the problems with the existing packages, which led to the creation of your package. In paragraph 2 focus on how the drawbacks in paragraph 1 impact the user in terms of (perhaps) precision, computational time/efficiency, reduced user productivity, and quite basically, why your algorithm is better and why people should use it.

Once the above is written, in paragraph 3 focus on the structure of your paper. For example "In the Data Used section we discuss the data used for example runs. In the Methods section, we discuss the fundamental basis of the calculations for X,Y,Z,..." Also, provide Use Cases with example runs. Other than that, everything else is straightforward.

You must log in to answer this question.

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