Tutorials and Training Articles

What is a publishable tutorial and/or training article?

As detailed below, a tutorial is largely a procedural guide to a particular piece of software, whereas a training article provides an introduction to a procedure or theory and thus provides general background preparation for performing molecular simulation calculations with diverse software packages. The guidelines below will discuss tutorials and training articles separately, but the editors recognize that authors may wish to submit hybrid training/tutorial articles. Authors pursuing a hybrid approach should carefully lay out their proposal in a pre-submission letter. The editors are not setting pre-conditions on hybrid articles, except that they should combine elements from both types of papers in a logical way suitable to the goals of the article.

Tutorials: Definition and scope

Tutorials are articles that take users through specific tasks or sequences of tasks within a particular established software platform, to help the users learn how to do these tasks on their own for other applications or purposes.

Tutorials are accompanied by associated other materials which help the reader put into practice the calculations described by the tutorial.
These additional materials may include

  • web pages with walkthroughs or instructional materials and downloadable files to work with
  • a website with training information and downloadable Jupyter notebooks teaching users how to perform a modeling task
  • a more extensive online course-like format with recorded lectures.

Tutorials must involve only software that has been previously validated through one or more peer-reviewed publications, and those must be referenced in the presubmission letter. Often, one of the software developers will be a tutorial author. In some cases, other users will have sufficient expertise to provide the highest-quality tutorials expected for LiveCoMS. If no developer is a proposed author of the tutorial, the presubmission letter should provide sufficient argument why the authors’ expertise is right for the tutorial.

Scope of tutorials: Tutorials should endeavor to cover a specific task or set of tasks at hand with explicit instructions, rather than cover too much information in a less detailed manner. However, they should also highlight how the steps might need to be modified, or additional care might need to be taken at particular points, to handle more general cases.

The scope of the tutorial, as well as the expected proficiencies / outcomes for researchers who complete the tutorial, should be clearly defined.

Prerequisites for tutorials: Tutorials should clearly define what concepts or abilities researchers will need to complete the tutorial (e.g., some proficiency in Python; experience with Jupyter notebooks; knowledge of classical MD; etc).

Tutorials should define what system and/or software requirements the researcher will need to complete the tutorial (e.g., VMD version 1.9 or newer, AMBER, etc.) in a clearly-marked section at the start of the manuscript; this information should also be provided within the presubmission letter to faciliate selection of appropriate reviewers. Tutorials requiring specific software packages must provide instructions and files for the referenced version of the software, as well as any information that might affect the output (e.g., what precision the binaries were compiled, what machines they were compiled on). As mentioned above, the software must have beeen previously published and validated, as the goal of a tutorial is not to introduce newly-developed software but to facilitate others’ using an established piece of software to carry out a particular task.

Pre-existing tutorials: The submission of existing tutorials, so long as they meet the journal standards described here, is explicitly welcomed. Our goal is to encourage the development of high quality tutorials by providing some degree of academic credit for these important and time-consuming efforts.

Additional criteria considered in the review of tutorials

  • Are files and necessary executables required to run the tutorial posted online in a permanent (or nearly so) way?
  • Are the tutorials suitable for the intended audience (e.g., researchers with only basic knowledge or advanced researchers)?
  • Do they include enough information on how to generalize the approach to handle other cases, and highlight major issues to consider?
  • Do the tutorials use commonly agreed on best practices?
  • Do the tutorial authors clearly provide, where possible, information (e.g., primary literature citations) about why particular choices are being made during the step-by-step process?
  • Does the tutorial require use of proprietary software or data? If so, are workarounds made available for researchers who may not have access to such software or data?

Revision schedule for tutorials

Authors should generally update tutorials as the software involved changes; these tutorials are expected to be kept functioning and if they do not, they may be indicated as out-of-date on LiveCoMS’ site.

Training articles: Definition and scope

Training articles are largely self-contained and introduce readers to the theory and/or typical procedures for a particular aspect of molecular simulation. Training articles need not refer to specific software commands and procedures but may do so to further the pedagogical goals of the paper. As needed, training articles are likely to display more details of calculations than typically are shown in research articles, for example, noting any mathematical principles or “tricks” used to derive key results.

Prerequisites for training articles: Training articles should clearly state the target audience and knowledge prerequisites. Although the authors may imagine a particular career-level (e.g., undergraduate or graduate), given the diversity of disciplinary curricula, it is more important to specify precisely any knowledge prerequisites (e.g., vector calculus, basic thermodynamics). If a particular software or programming environment plays a central role in the article, that should be specified. Key prerequisites should be noted in the article abstract to permit readers to rapidly ascertain an articles suitability.

Additional criteria considered in the review of training articles

  • Does the manuscript cover material of significance for computational molecular scientists?
  • Is the target audience clearly identified, appropriate, and likely to benefit from the manuscript?
  • Is the level of detail, explanation, and graphical illustration sufficient to ensure clarity for the proposed target audience?
  • Does the manuscript point to additional resources, including a range of software implementations, more fundamental or auxiliary theoretical reference?
  • Does the manuscript clearly indicate approximations employed in the formulation presented, as well as any other possible sources of error in implementations of the material?