Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 8.41 KB

.standard-GEM.md

File metadata and controls

109 lines (81 loc) · 8.41 KB
Raw

standard-GEM 0.5

For details about the aims, scope, and use case of this standard see the wiki pages of the standard-GEM repository.

Terminology

The definitions used throughout this guide are copied below from the wiki to facilitate understanding. For easier differentiation, we have associated colours with each of them.

Based on the ISO guidelines, tweaked for easy understanding.
🟥 Requirements: must, must not
🟧 Recommendations: should, should not
🟨 Possibility and capability: can

Instructions

This document serves as a checklist for creating an open source genome-scale metabolic model (GEM) on GitHub.

  • 🟥 All GEMs that follow the standard-GEM must contain this file.
    This serves as a traceable adherence to the standard, manually confirmed by the original authors. This file must be edited only with checkmarks, to support automatic parsing and validation. Some of the checkmarks are pre-applied based on the contents of the standard-GEM template repository. GEM authors are responsible for checking that their model repository follows the guidelines entirely.
    With further updates to standard-GEM, one should paste over the new version of this file, and see that the changes in the new guidelines are met.

Repository creation

  • 🟨 Navigate to standard-GEM and click on the button Use this template
    The standard-GEM template can be used to initiate a repository. This will copy the contents of the main branch into the new repository, which can be either private or public.

  • 🟥 Pick a repository name
    The name must be either a common name, KEGG organism, or taxonomy-derived short name, followed by the extension -GEM or -GSMM. The -GEM extension is preferred to ease pronunciation. An abbreviation can prefix the name, eg., ec (enzyme constrained), sec (with secretory pathways), mito (with mitochondrion pathways), pro (with protein structures).
    Example: ecYeast-GEM

  • 🟥 Pick a repository description
    The description must include the taxonomic classification in full.
    Example: The consensus GEM for Saccharomyces cerevisiae

  • 🟥 Add repository topic
    The topic standard-GEM must be added. Other topics like genome-scale-models and systems-biology can be added. Labelling the repository with this topic enables automatic finding using the GitHub API, and automatic validation of the standard.
    Topics are not copied from standard-GEM, so they must be added manually.

  • 🟨 Add a repository URL
    The URL can be the link to the publication/pre-print/website where the model is introduced, eg., via an identifier system (doi/EuropePMC/PubMed).

Repository workflow

  • 🟥 Git branches
    The GEM repository must have at least two branches: main and develop.

  • 🟥 Releases
    Releases must use the tag format X.X.X where X are numbers, according to semantic versioning principles. The last field, called “patch,” can also be used to indicate changes to the repository that do not change the GEM itself. Using a v before the version number (v1.0) is discouraged. For more information about releases, see the documentation on GitHub.

  • 🟨 Commits
    Commit messages can follow the style of semantic commits.

File tree

/ signifies the root of the repository.
.keep files are used to indicate that git will not ignore empty folders. Without these, git would simply not want to version empty directories. Once folders are not empty, these files can be removed.

  • 🟥 /.gitignore
    The repository must contain a /.gitignore file. This generic .gitignore was prepared for multiple programming languages. While it does not require modification, it can be further adapted to the needs of the repository.

  • 🟥 /.github
    The repository must contain a /.github folder, in which the contributing guidelines, code of conduct, issue templates and pull request templates must be placed. Defaults are provided and they do not require any modification.

  • 🟥 /.github/CONTRIBUTING.md
    The template provides this file, but it is empty. It must be filled in with the adequate contributing guideline instructions; a good example is https://github.com/SysBioChalmers/yeast-GEM/blob/main/.github/CONTRIBUTING.md.

  • 🟥 /code/README.md
    The repository must contain a /code folder. This folder must contain all the code used in generating the model. It must also include a README.md file that describes how the folder is organised.

  • 🟥 /data/README.md
    The repository must contain a /data folder. This folder contains the data used in generating the model. It must also include a README.md file that describes how the folder is organized.

  • 🟥 /model
    The repository must contain a/model folder.
    This folder must contain the model files in multiple formats depending on the branch, according to the table below. As a general guideline, binary formats (.mat, .xlsx) must not exist on any other branches than main. The main reason is that binary files cannot be diff´ed, which means changes cannot be compared to previous versions, thus increasing the chance of errors. Moreover, with time, the size of the repository can create difficulties, and we cannot yet recommend storing these files with Git LFS, as it introduces complexity.
    For more information on the sbtab file format, see sbtab.net.
    All model files must be named the same as the repository, and with the appropriate extension.
    Example: yeast-GEM.mat

Model file format main branch develop and other branches
JSON .json can
Matlab .mat should must not
sbtab .tsv can
Text file .txt must
Excel .xlsx must must not
SBML .xml must
YAML .yml must

  • 🟥 /LICENSE.md
    The repository must contain a license file. The default license is CC-BY 4.0 International. Unless a different license is desired, the file does not require modification.

  • 🟥 /README.md
    The repository must contain a README.md file. A default file is provided, and the adequate contents must be filled in.
    The /README.md file must include a version badge. A default is provided in the file.
    Additionally, the /README.md file should contain the Zenodo badge. As soon as the first public release is in made, the repository should be archived via Zenodo, and the corresponding badge be updated. A default is provided in the file.
    The /README.md can contain a contact badge, eg., Gitter. When setting up the Gitter chat room, the GitHub activity should be synced with Gitter in order to see the latest repository updates in the chat room. The default for this badge is provided in the file.

  • 🟥 /version.txt
    The repository must contain this file, which is required for the version badge in the /README.md. The value refers to the GEM, not of the standard-GEM. The value must be updated with each release.

  • 🟨 Files for continuous integration testing
    The repository can be set up for continuous integration testing using memote with, eg., Travis CI (.travis.yml), Jenkins (Jenkinsfile), and GitHub Actions (under .github/workflows).

  • 🟨 MEMOTE report
    The repository could contain a MEMOTE report on the main branch in .html format.