Policy on Publishing Code

The overarching objective of our policy is to ensure that high quality code is readily available to our readers, ideally open source. The key principles we intend our policy to ensure are Quality, Usability, Accessibility and Functionality. More specifically:

Quality Through being published in Methods in Ecology and Evolution, readers and users should have confidence that peer review has been used to ensure that there is evidence of high standards of code preparation. By necessity this cannot include extensive testing, but reviewers will look for evidence of good coding practice.

Usability Code needs to be usable, so that readers are able to implement methods readily. This includes both the implementation and the platform. We will discourage the use of proprietary software where possible in favour of ones that respect established standards for software freedom (e.g. https://www.gnu.org/philosophy/free-sw.html). The implementation should include documentation and examples with benchmarking data where possible.

Accessibility We require a version of record: this should be the exact version of the code described in the journal and able to replicate all results presented. However, we recognise that code evolves and encourage the use of platforms that permit updating with version control.

Functionality Functionality needs to be novel and add to what is already available. Re-implementations of existing methods are not published, except where they take advantage of new methods permitting significant computational gains.

We are an academic journal and we have to recognise that our primary purpose and capability is to ensure rigorous peer review and the integrity of the publication process. However, as part of the British Ecological Society we have an objective to communicate ecological science and the above principles are intended to additionally ensure that the community is benefiting from well-communicated outputs that are accessible, as well as being designed to promote good research practice in the community.

What do we publish?

Our primary code outputs are applications papers. Although not restricted to code, a high proportion of Applications describe a range of different tools. The journal has a set of expert Associate Editors who deal with these papers, overseeing the review process and making recommendations to the senior editors. Applications papers describe the functionality of a tool and are intended to act as an overview of the application as well as to act as a citable source. Ideally the paper should succinctly describe what the code does including information relevant for both users and future developers. As described below, good coding practices will ensure that code is robust and able to be rigorously reviewed.

We also publish a range of other code outputs, although not always as the primary output of a paper. These include:

  • Scripts: many papers in Methods in Ecology and Evolution and other journals include scripts that perform data analysis and may be of interest to readers or users wishing to analyse their own data.
  • Spreadsheets: although not a common output, in some disciplines spreadsheets are an output that are particularly valuable for end users.
  • Web pages: some tools, particularly those underpinned by large datasets or databases, will be available through a web interface.

There are some outputs that we are reluctant to consider:

  • Proprietary programs that do not provide access to source code. In the absence of source code, reviewers are unable to view details of implementation. There are also issues of compatibility across platforms for pre-compiled applications. We of course recognise that some applications need to be compiled before they can be used, but in these cases source code should be provided.
  • We will not normally publish applications that are being developed commercially for sale. Commercial interests generate potential conflicts of interest and issues of accessibility, and we are unable to publish code that is being distributed commercially. We do not rule out, however, comparisons with commercial outputs however we would not normally publish code that replicates commercial packages simply because it is free.

Ensuring quality through peer review

We recognise that it is difficult for reviewers and editors to work line-by-line through submitted code. In reviewing code we therefore encourage the adoption of coding practices that facilitate the writing of robust code. These include:

  • Benchmark data: these should be included and where possible worked through from first principles as well as using code. For example, code may implement a new statistical method: it would be ideal to provide a worked example in the text or appendix of a paper that is then replicated by running the code.
  • Unit testing: for more complex applications unit-testing is a best-practice approach for testing components and demonstrating that they perform as expected.
  • Documentation: thorough documentation of code will facilitate understanding of overall structure for reviewers and users.
  • Version control: clear history of code with revisions tracked and documented will make clear how bugs are fixed and how subsequent versions of code relate to that originally submitted.

This is not an exhaustive list: the overall philosophy is that robustly written code will be easier to review and revise in the peer review as well as subsequently.

The above apply primarily to applications. However, the same principles apply to other code outputs: essentially code, where provided, should be written using good practice in terms of design and testing, and be well presented permitting peer review and eventual reuse.

Where should code be stored/shared?

There are a variety of platforms for storing and sharing code. We recommend that code is shared via such a platform. This should ideally permit version tracking so that the version of record can be clearly identified. Some platforms now permit a DOI to be assigned to code and we recommend this where possible for ready identification and tracking.

As mentioned above, some code needs to be compiled before being run. Developers should share the source code and instructions for compiling: our experience is that it cannot be guaranteed that pre-compiled applications will run on a given platform, and these may present security concerns in any case.

All code submitted to Methods in Ecology and Evolution must include a fully open source software license. This is because current copyright law prevents code sharing by default, thus necessitating a license explicitly allowing code sharing and reuse. Typically, the license text resides in a text file (commonly titled LICENSE.txt) with the code. A well-established list of such licenses can be found here: https://www.gnu.org/licenses/license-list.html#SoftwareLicenses Paper submissions including code that does not have accompanying open source licenses cannot be considered for publication.

Final  comments

Our primary aim is to ensure scientific integrity through high quality through peer review. This policy document highlights a series of criteria we will be working to and to indicate in broad terms what we expect of authors. Code outputs are heterogeneous, and it is not possible or desirable to be completely prescriptive. We recognise that good practice described here will greatly increase the quality of code as well as facilitate better peer review and this will fulfil the journal’s dual aims of ensuring high quality science and communicating ecological research.