Files structure

https://github.com/bioexcel/biobb_template

Taking a look to the biobb_template files structure, we will find something like that:

.github
- ISSUE_TEMPLATE
  - bug_report.md
  - feature_request.md
- workflows
  - inactive_issues.yml
  - linting_and_testing.yml
- env.yaml
biobb_template/
- __init__.py
- adapters/
  - cwl/
  - pycompss/
- docs/
- json_schemas/
- notebooks/
- template/
  - __init__.py
  - template.py
  - template_container.py
- test/
conda_env/
- biobb_template.pth
- environment.yml
.gitignore
.readthedocs.yaml
LICENSE
README.md
setup.py

.github folder

https://github.com/bioexcel/biobb_template/tree/master/.github

This folder contains all the files necessary for testing the biobb package in the GitHub repository through GitHub Actions.

env.yaml

https://github.com/bioexcel/biobb_template/blob/master/.github/env.yaml

File with all the dependencies needed for running the biobb package in a conda environment.

workflows folder

https://github.com/bioexcel/biobb_template/tree/master/.github/workflows

This folder contains the GitHub actions workflows.

linting_and_testing.yml

https://github.com/bioexcel/biobb_template/blob/master/.github/workflows/linting_and_testing.yml

This file is the workflow that runs the tests in an external Virtual Machine configured to run automatically through GitHub actions. When the developer pushes code to the repository, the workflow is launched performing linting and running the tests developed in the Unittests section.

The structure of this file is explained in the Github Actions section.

inactive_issues.yml

https://github.com/bioexcel/biobb_template/blob/master/.github/workflows/inactive_issues.yml

This file checks if there are inactive issues and put them as stale if there hasn’t been activity in the last 30 days or close them in case it has been 14 days since the issue was put as stale. This workflow is executed automatically once per day.

The structure of this file is explained in the Github Actions section.

ISSUE_TEMPLATE folder

This contains the templates for issues.

bug_report.md

Template for opening a new issue related to bugs.

---
name: Bug report
about: Create a report to help us improve
title: ''
labels: ''
assignees: ''

---

**Describe the bug**
A clear and concise description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:

**Expected behavior**
A clear and concise description of what you expected to happen.

**Desktop (please complete the following information):**
 - OS: [e.g. ubuntu]
 - Python version: [e.g. 3.8]
 - BioBB version [e.g. 4.0.0]

**Additional context**
Add any other context about the problem here.

feature_request.md

Template for opening a new issue related to feature requesting.

---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: ''
assignees: ''

---

**Is your feature request related to a problem? Please describe.**
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

biobb_template

https://github.com/bioexcel/biobb_template/tree/master/biobb_template

This folder contains the whole project.

init.py

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/__init__.py

Files named __init__.py are used to mark directories on disk as Python package directories. In this first level we define the package name (biobb_template) all the modules contained in this package -only one in this example (template)- and the package version:

name = "biobb_template"
__all__ = ["template"]
__version__ = "4.1.0"

adapters folder

Take into account that this folder is not standard for a biobb. Before add your biobb to a new Git repository it’s strongly recommended to add it to the .gitignore file as explained in this section

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/adapters

This folder contains templates’ adapters to use the BioBBs with several workflow managers. More examples of BioBB adapters can be found at https://github.com/bioexcel/biobb_adapters/.

cwl folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/adapters/cwl

This folder contains the Common Workflow Language template.

More information in the CWL section.

pycompss folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/adapters/pycompss

This folder contains the PyCOMPSs template.

More information in the PyCOMPSs section.

docs folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/docs

In this folder there are all the files related to the documentation of the project. Although most of the documentation is automatically generated through sphinx, the section indexes, readme and command line section must be made by hand.

More information in the Documentation section.

json_schemas folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/json_schemas

The JSON Schemas of all the wrappers are stored in this tool. In addition, there is a JSON file with general information about the whole package.

More information in the JSON Schemas section.

notebooks folder

Take into account that this folder is not standard for a biobb. Before add your biobb to a new Git repository it’s strongly recommended to add it to the .gitignore file as explained in this section

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/notebooks

This folder contains a template with examples of the execution of biobb_template tools in Jupyter Notebook.

template folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/template

In this folder, we can find all the wrappers. In the biobb_template case there are two: template.py and template_container.py

init.py

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/__init__.py

Files named __init__.py are used to mark directories on disk as Python package directories. In this second level we define the folder name (template) and all the tools contained in this folder, only two in this example (template and template_container):

name = "template"
__all__ = ["template", "template_container"]

template.py

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/template.py

Example with all the code needed to generate a common BioExcel building block. In this case, the tool to wrap is zip.

More information about the structure of this file can be found in the Template section.

template_container.py

https://github.com/bioexcel/biobb_template/blob/master/biobb_template/template/template_container.py

Example with all the code needed to generate a BioExcel building block executing the wrapped tool through a container. In this case, the tool to wrap is zip and two containers are provided: Docker Hub and Singularity Hub (type singularity pull --name zip.sif shub://bioexcel/zip_container for installing it in your computer in .sif format or singularity pull shub://bioexcel/zip_container for installing it in your computer in .simg format).

More information about the structure of this file can be found in the TemplateContainer section.

test folder

https://github.com/bioexcel/biobb_template/tree/master/biobb_template/test

In this folder there are all the needed files for the unittests: data files, reference files, python tests and configuration file.

More information about the files structure of this folder and the execution of tests can be found in the Unittests secion.

conda_env

Take into account that this folder is not standard for a biobb. Before add your biobb to a new Git repository it’s strongly recommended to add it to the .gitignore file as explained in this section

https://github.com/bioexcel/biobb_template/tree/master/conda_env

This folder contains the two necessary files for building a new conda environment.

biobb_template.pth

https://github.com/bioexcel/biobb_template/blob/master/conda_env/biobb_template.pth

/path/to/biobb_template/
/path/to/biobb_template/biobb_template

The two lines of this file must be edited and changed by the correct path to your biobb_template project. This paths file is used for import local python packages to our conda environment.

environment.yml

https://github.com/bioexcel/biobb_template/blob/master/conda_env/environment.yml

name: biobb_template
channels:
  - conda-forge
  - bioconda
dependencies:
  - python
  - biobb_common>=4.1.0
  - nb_conda_kernels
  - pytest
  - zip
  - conda

In this YAML file we find all the pakcages that will be installed in our conda environment:

python: Last available version of python in anaconda.
biobb_common: BioBB library with all the necessary common functions for developing BioExcel Building Blocks.
nb_conda_kernels: This extension enables a Jupyter Notebook application in one conda environment to access kernels for several languages found in other environments.
pytest: Unittest python library.
zip: Software that will be wrapped in this biobb_template examples
conda: Installs conda client for easy the different conda instructions execution.

Root files

.gitignore

https://github.com/bioexcel/biobb_template/blob/master/.gitignore

A .gitignore file specifies intentionally untracked files that Git should ignore.

The biobb_template includes some folders not standard for a biobb, such as biobb_template/adapters/, biobb_template/notebooks/ or conda_env/. For the sake of having a pure biobb structure, you should uncomment the three last lines of the .gitignore file before creating a new git repository:

biobb_template/adapters
biobb_template/notebooks
conda_env

.readthedocs.yaml

https://github.com/bioexcel/biobb_template/blob/master/.readthedocs.yaml

A .readthedocs.yaml file configures your documentation builds with Read the Docs

LICENSE

https://github.com/bioexcel/biobb_template/blob/master/LICENSE

License for the package, usually Apache License 2.0

README.md

https://github.com/bioexcel/biobb_template/blob/master/README.md

Text file containing useful information about the BioBB package.

setup.py

https://github.com/bioexcel/biobb_template/blob/master/setup.py

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="biobb_template",
    version="4.1.0",
    author="Biobb developers",
    author_email="your@email.com",
    description="Biobb_template is a complete code template to promote and facilitate the creation of new Biobbs by the community.",
    long_description=long_description,
    long_description_content_type="text/markdown",
    keywords="Bioinformatics Workflows BioExcel Compatibility",
    url="https://github.com/bioexcel/biobb_template",
    project_urls={
        "Documentation": "http://biobb-template.readthedocs.io/en/latest/",
        "Bioexcel": "https://bioexcel.eu/"
    },
    packages=setuptools.find_packages(exclude=['adapters', 'docs', 'test']),
    install_requires=['biobb_common==4.1.0'],
    python_requires='>=3.8',
    entry_points={
        "console_scripts": [
            "template = biobb_template.template.template:main"
        ]
    },
    classifiers=(
        "Development Status :: 5 - Production/Stable",
        "Programming Language :: Python :: 3.8",
        "Programming Language :: Python :: 3.9",
        "Programming Language :: Python :: 3.10",
        "License :: OSI Approved :: Apache Software License",
        "Operating System :: MacOS :: MacOS X",
        "Operating System :: POSIX",
        "Operating System :: Unix"
    ),
)

In this setup.py file, the developers must fill several fields such as descriptions, author name, keywords and so on. The most important fields are:

version: version of the package
packages: the ones excluded won’t be automatically parsed in the building process of bioconda. It’s important to exclude all the folders containing Python files that must be excluded in this building process.
install_requires: dependencies of this package
python_requires: version of python

Files structure

.github folder

env.yaml

workflows folder

linting_and_testing.yml

inactive_issues.yml

ISSUE_TEMPLATE folder

bug_report.md

feature_request.md

biobb_template

__init__.py

adapters folder

cwl folder

pycompss folder

docs folder

json_schemas folder

notebooks folder

template folder

__init__.py

template.py

template_container.py

test folder

conda_env

biobb_template.pth

environment.yml

Root files

.gitignore

.readthedocs.yaml

LICENSE

README.md

setup.py

init.py

init.py