Skip to content

Latest commit

 

History

History
109 lines (81 loc) · 8.5 KB

.standard-GEM.md

File metadata and controls

109 lines (81 loc) · 8.5 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

To facilitate understanding, the definitions used throughout this guide are copied below from the wiki. For easier differentiation, we have associated colors to 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, in order to support automatic parsing and validation of this file. Some of the checkmarks are pre-applied based on the contents of the standard-GEM template repository. GEM authors have the responsibility of checking that their model repository does follow 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 master 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. The name can be prefixed by an abbreviation, 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, systems-biology can be added. Having this topic on your repository enables automatic finding using the GitHub API, and automatic validation of the standard.
    Topics are not copied from standard-GEM, so they need to be added manually.

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

Repository workflow

  • 🟥 Git branches
    The GEM repository must have at least two branches: master and devel.

  • 🟥 Releases
    Releases must use the tag format X.X.X where X are numbers, according to semantic versioning principles. The last field, also called “patch”, can also be used to indicate changes to the repository that do not actually change the GEM itself. The use of a v before the version number (v1.0) is discouraged. For more information about releases see the documentation at 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 the empty folder should not be ignored by git - without it git would simply not want to version empty directories. Once folders are not empty, it is okay to remove these files.

  • 🟥 /.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
    This file is provided by the template, 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/master/.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 organized.

  • 🟥 /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 /model folder.
    This folder must contain the model files, in multiple formats, according to the table below. As a general guideline, binary formats (.mat, .xlsx) must not exist on any other branches than master. The main reason for this 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 introducs 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 master branch devel 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, for example Gitter. When setting up the Gitter chat room, the GitHub activity should be synced with Gitter in order to see the latest updates of the repository in the chat room. A 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 version of 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), GitHub Actions (under .github/workflows).

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