The BioLib config.yml File

This document explains how to use the config.yml file.

Introduction

The file config.yml contains the information needed to render and run an application on BioLib. The config.yml defines the entry to your application and what input arguments the user can set. When you edit an application using the graphical interface on BioLib the config.yml file is automatically generated and updated. Hence, in most cases one does not need to manually edit the config.yml file. However, in some advanced instances, e.g. if you are autogenerating an application, or exporting an application directly from a repository elsewhere, you might want to edit the config file directly.

The location of the config file is always .biolib/config.yml.

Content of config.yml

To explain how the config.yml works, we go through each of the elements in the example configuration file below:

biolib_version: 1
modules:
    main:
        path: src/__main__.py
        executor: 'bl-python3:*'
    onnx:
        path: build/model.onnx
        executor: 'bl-onnx:*'
    samtools: 'bio-utils/samtools:0.0.1'
client_side_include:
    - src/__main__.py
    - build/model.onnx
arguments: 
    key: --function 
    description: 'Choose a function' 
    key_value_separator: '' 
    default_value: '' 
    type: dropdown 
    options: 
        'Command A': a 
        'Command B': b 
    sub_arguments: 
        a: 
            key: --argument_a 
            description: 'Argument A takes a file input' 
            type: file 
        b: 
            key: --argument_b 
            description: 'Argument B takes a text input' 
            type: text
description_file: README.md
license_file: LICENSE
citation:
    entry_type: book
    author: Dr. John Doe
    title: Using config.yml
    publisher: BioLib Community Press
    year: '2020'

biolib_version: This field specifies which version of the BioLib config.yml format is used. This option is included to ensure backwards compatibility of applications.

modules: This section specifies everything related to modules and executables. Applications must contain a module called 'main', which is the module that will be called when the user clicks "Start Computation", i.e. the entry of your application. Executable files, under source files, should be pointed to with their path and have specified a relevant executor. Another BioLib application can also be used as a module - in the config file this is specified using this syntax:

name-of-module: 
username-of-application-creator/application-name:version

client_side_include: Specifies which modules will be included for client-side execution. If this field is left blank, by default, all modules will be included for client-side execution.

arguments: Specifies how input options and settings will be rendered to the user of the application, and how inputs will be parsed. The field should follow this structure:

arguments: 
    - 
        key: --data # required 
        description: 'Input Dropdown' # required 
        key_value_separator: ' ' # optional, default is ' ' 
        default_value: '' # optional, default is '' 
        type: dropdown # required 
        options: 
            'This will be shown as option one': 'value1' 
            'This will be shown as option two': 'value2' 
        required: true # optional, default is true

Under type you have the following options:

• text provides a text input field
• hidden allows the application creator to provide a default input argument without it being shown to the end-user
• toggle provides a toggle switch where users can choose two options
• file provides a file select where users can upload an input file
• number provides a number input field
• radio provides a "radio select" where users can select one amongst a number of prespecified options
• dropdown provides a dropdown menu where users can select one amongst a number of prespecified options

sub_arguments: Allow you to specify arguments that are only rendered if a user chooses a particular option in the parent argument. For example, an application might allow the user to run one of two commands, where each of these commands would need different input arguments:

arguments: 
    - 
    key: --function 
    description: 'Choose a function' 
    key_value_separator: '' 
    default_value: '' 
    type: dropdown 
    options: 
        'Command A': a 
        'Command B': b 
    sub_arguments: 
        a: 
            - 
                key: --argument_a 
                description: "Argument A takes a file input" 
                type: file 
        b: 
            - 
                key: --argument_b 
                description: 'Argument B takes a text input' 
                type: text

Note, that developers can only add sub-arguments directly in the .yml configuration file and not through the graphical UI for configuring Input Arguments.

consumes_stdin: Allows you to specify whether your application takes data from Standard In. By default, this is set to false, if your application uses stdin change this to true.

output_type: Specifies how output files are rendered. By default, this is set to text, meaning that any output will be appended .txt and rendered as text. If your output is Markdown, this should be specified in with markdown which will append .md to the output and render as Markdown.

description_file: Specifies the path to the README file, which will be rendered as the description on the application page. The default path is README.md.

license_file: Specifies the path to the license file, which will be visible to users at the bottom of the application page. The default path is LICENSE.

citation: Allows you to provide a citation using the following structure:

citation:
    entry_type: book
    author: Dr. John Doe
    title: Using config.yml
    publisher: BioLib Community Press
    year: '2020'

Note that the choice of entry_type has implications for which fields are required. For a complete list of which fields are required for which types you can read more about the BibTex standard here.