Special Instructions for Software Notes

For other article types, see Author Guidelines.

Software Notes (SN) are short articles (typically within 4000-6000 words) describing software for ecological and biogeographical analyses. The software and its SN should follow the guidelines below.

Software Availability and Licensing

Only free and open-source software is eligible for software notes. Open-source contributions that rely on closed-source commercial systems (e.g., ArcGIS extensions or matlab packages) are not eligible. The software should be explicitly licensed with an open-source license, and this license should be clearly stated in the software and SN. Ecography recommends fully open licenses (e.g., MIT), but copy-left (e.g., GPL) licensed software is also accepted. If the software runs on a modular system (e.g., R), novel functions that are implemented in the software should be clearly explained in the text if used in code examples.

Scope

Software notes should present software that either introduces new techniques or substantial improvements on the implementation of existing techniques. Where possible, the software should be modular and general. For example, software that automates access to a single database would generally be too narrow. Software that allows the user analytical freedom and combines easily with other software is preferred to software focusing on wholesale streamlining of particular analytical workflows.

Software described by SN is expected to be regularly maintained. If source code maintenance of published software stops, so that it is no longer fully functional, a note should be addressed to the editor team. The SN will be marked with a note stating that it is currently unmaintained.

New software versions of existing software that have already been presented in a SN in Ecography or elsewhere are, as a general rule, not eligible for a new SN. However, material upgrades of software that introduce significant new functionality or capabilities may be eligible. Submissions presenting software updates should clearly state this and provide an argument for why the update needs a separate SN.

Quality control

The software is expected to have associated documentation that describes all aspects of the software and allows new users to learn how to use the software without consulting other sources. The source code itself is also expected to be well-documented. The software should contain and employ standard unit tests that test all central functionality of the software with a good coverage. All tests should pass at submission. If the source code is hosted on a service such as Github, we strongly recommend using continuous integration services that trigger a test run every time the source code is modified. Following a standard code style is also recommended.

Structure of Software Notes

Ecography does not enforce a specific format for SNs. However, all SNs should describe the software's background and its application in the field. In addition, the SN should detail the main methods and features of the software, and provide a short applied example. A conceptual figure is highly recommended. The requirements for each element are laid out below.

Background

The SN should clearly describe the relationship of the software to existing software in the field: does it supplement, supersede, or compete with existing software packages? What new features does it provide to users (e.g., a coherent analytical framework, novel functions or methods, increases in speed and stability)?

If the software is part of a modular system (e.g., R, Python, or Julia packages), it should describe which packages (and their versions) are used by the software, what functionality is used from them, and the specific contribution of the package. Imported packages and their versions should be cited using the appropriate references.

Methods and Features

If the software uses methods that are tested and well-described in the literature, a short well-referenced discussion of the relevance and use of the methods is sufficient.

If the software implements new methods, the SN should be expanded to include a rationale and description of these methods, preferably including simulation analyses, a comparison to existing methods, and possibly a brief empirical analysis.

Examples

The SN should offer readers a quick introduction that exemplifies working with the software. The SN should therefore contain an example of the most common uses of the software. The software should be distributed with an example to be run "out of the box" so reviewers and readers can run the example themselves without having to acquire extra data. If data are needed to run the example, they should be provided as supplementary materials. The example results should be presented graphically. If the software has graphical functions, default settings are preferred. Short output from running code examples should be presented in-text, while longer output can be reproduced in a supplemental file.

Peer Review

SN reviewers must have full access to the software, its documentation, and source code. To ensure that peer review is double blind, we recommend keeping the source code in a private repository. It can be made available to reviewers either via a service such as Anonymous Github (https://anonymous.4open.science/) or by submitting the full source-code package and data as a supplementary zip file.

Authors should expect the software to be fully tested by reviewers, using the provided example data and possibly additional datasets. Reviewers’ comments, suggestions, and issues will be taken into account for the editorial decision on the SN. Critical bugs and major software flaws will cause the SN to be rejected for publication.

Citations and DOI

Details for obtaining the software and source code (such as a download link or Github/SVN repository) should be stated clearly in the software note, along with directions for obtaining the existing software documentation (technical description, help file, etc.) and compiled binaries where applicable. If the final version is not publicly available for use at the time of submission, the submission files should include the newest version of the software, so that reviewers can run the example code. In this case, the cover letter should also indicate an approximate date for when the software will become publicly available so that publication of the SN can be delayed until that date. The software version of record at the time of publication should be associated with a Digital Object Identifier (DOI), which can be acquired from Zenodo, and the DOI reported in the paper.

Versioning

All software published in SN should have a version number, and the major version number should be listed in the SN (i.e., "EcoSoft 1" if the full version number is "EcoSoft 1.3.4-2"). The version number must be at least 1.0 for consideration as a SN. The release date of the most recent version should also be clearly stated.

We suggest semantic versioning (http://semver.org/), where incrementing a major version number indicates breaking backwards compatibility, meaning the SN example codes may break for higher version numbers.

Citing software

Preferably, all software mentioned in Ecography papers should be cited using the associated research article, such as a SN. In the absence of an associated SN, software citations should include the name of the software, the authors, the version and release date, the web address of any public repository, and preferably a DOI.

File formats

Files for peer review can be uploaded as a Word document with embedded figures, or instead as a pdf. However, accepted manuscripts should be uploaded for editorial production as a .docx file with figures as separate image files.