Config

A Viash configuration is a YAML file which contains metadata to describe the behaviour and build target(s) of a component.
We commonly name this file config.vsh.yaml in our examples, but you can name it however you choose.

Example:

name: hello_world
arguments:
  - type: string
    name: --input
    default: "world"
resources:
  - type: bash_script
    path: script.sh
    text: echo Hello $par_input
runners:
  - type: executable
engines:
  - type: docker
    image: "bash:4.0"

__merge__

Type: File

Default: Empty

Config inheritance by including YAML partials. This is useful for defining common APIs in separate files. __merge__ can be used in any level of the YAML. For example, not just in the config but also in the argument_groups or any of the engines.

Example:

__merge__: ../api/common_interface.yaml

argument_groups

Type: List of ArgumentGroup

Default: Empty

A grouping of the arguments, used to display the help message.

  • name: foo, the name of the argument group.
  • description: Description of foo, a description of the argument group. Multiline descriptions are supported.
  • arguments: [arg1, arg2, ...], list of the arguments.

Examples:

argument_groups:
  - name: "Input"
    arguments:
      - name: "--id"
        type: string
        required: true
      - name: "--input"
        type: file
        required: true
  - name: "Output"
    arguments:
      - name: "--output"
        type: file
        direction: output
        required: true
      - name: "--output_optional"
        type: file
        direction: output

This results in the following output when calling the component with the --help argument:

component_name

  Input:
      --id
          type: string

      --input
          type: file

  Output:
      --output
          type: file

      --optional_output
          type: file

arguments

Type: List of Argument

Default: Empty

A list of arguments for this component. For each argument, a type and a name must be specified. Depending on the type of argument, different properties can be set. See these reference pages per type for more information:

authors

Type: List of Author

Default: Empty

A list of authors. An author must at least have a name, but can also have a list of roles, an e-mail address, and a map of custom properties.

Suggested values for roles are:

Role Abbrev. Description
maintainer mnt for the maintainer of the code. Ideally, exactly one maintainer is specified.
author aut for persons who have made substantial contributions to the software.
contributor ctb for persons who have made smaller contributions (such as code patches).
datacontributor dtc for persons or organisations that contributed data sets for the software
copyrightholder cph for all copyright holders. This is a legal concept so should use the legal name of an institution or corporate body.
funder fnd for persons or organizations that furnished financial support for the development of the software

The full list of roles is extremely comprehensive.

Example:

authors:
  - name: Jane Doe
    role: [author, maintainer]
    email: jane@doe.com
    info:
      github: janedoe
      twitter: janedoe
      orcid: XXAABBCCXX
      groups: [ one, two, three ]
  - name: Tim Farbe
    roles: [author]
    email: tim@far.be

dependencies

Type: List of Dependency

Default: Empty

Allows listing Viash components required by this Viash component

Examples:

Full specification of a repository

dependencies:
  - name: qc/multiqc
    repository: 
      type: github
      uri: openpipelines-bio/modules
      tag: 0.3.0

Full specification of a repository using sugar syntax

dependencies:
  - name: qc/multiqc
    repository: "github://openpipelines-bio/modules:0.3.0"

Reference to a repository fully specified under ‘repositories’

dependencies:
  - name: qc/multiqc
    repository: "openpipelines-bio"

description

Type: String

Default: Empty

A description of the component. This is only used for documentation. Multiline descriptions are supported.

Example:

description: |
  This component performs function Y and Z.
  It is possible to make this a multiline string.

engines

Type: List of Engine

Default: Empty

A list of engine environments to execute target artifacts in.

functionality

Type: Functionality

Default: ``

Warning

Deprecated since 0.9.0. Planned removal at 0.10.0. Functionality level is deprecated, all functionality fields are now located on the top level of the config file.

The functionality describes the behaviour of the script in terms of arguments and resources. By specifying a few restrictions (e.g. mandatory arguments) and adding some descriptions, Viash will automatically generate a stylish command-line interface for you.

info

Type: Json

Default: Empty

Structured information. Can be any shape: a string, vector, map or even nested map.

Example:

info:
  twitter: wizzkid
  classes: [ one, two, three ]

keywords

Type: List of String

Default: Empty

The keywords of the components.

Example:

keywords: [ bioinformatics, genomics ]

label

Type: String

Default: Empty

A clean version of the component’s name. This is only used for documentation.

Example:

label: "My component"

license

Type: String

Default: Empty

The license of the package.

Note

When the license field is left empty in a component’s configuration, the value of .version in the package config will be copied during build.

Example:

license: MIT

name

Type: String

Name of the component and the filename of the executable when built with viash build.

Example:

name: this_is_my_component

namespace

Type: String

Default: Empty

Namespace this component is a part of. See the Namespaces guide for more information on namespaces.

Example:

namespace: fancy_components

platforms

Type: List of Platform

Default: Empty

Warning

Deprecated since 0.9.0. Planned removal at 0.10.0. Use ‘engines’ and ‘runners’ instead.

A list of platforms to generate target artifacts for.

references

Type: References

Default: Empty

References to external resources related to the component.

Example:

references:
  doi: 10.1000/xx.123456.789
  bibtex: |
    @article{foo,
      title={Foo},
      author={Bar},
      journal={Baz},
      year={2024}
    }

repositories

Type: List of RepositoryWithName

Default: Empty

(Pre-)defines repositories that can be used as repository in dependencies. Allows reusing repository definitions in case it is used in multiple dependencies.

Note

Any repositories defined under .repositories in the package config will be prepended to the repositories defined in a component’s configuration of the .repositories field.

Example:

repositories:
  - name: openpipelines-bio
    type: github
    uri: openpipelines-bio/modules
    tag: 0.3.0

requirements

Type: ComputationalRequirements

Default: Empty

Computational requirements related to running the component. cpus specifies the maximum number of (logical) cpus a component is allowed to use., whereas memory specifies the maximum amount of memory a component is allowed to allicate. Memory units must be in B, KB, MB, GB, TB or PB for SI units (1000-base), or KiB, MiB, GiB, TiB or PiB for binary IEC units (1024-base).

Example:

requirements:
  cpus: 5
  memory: 10GB

resources

Type: List of Resource

Default: Empty

Resources are files that support the component. The first resource should be a script that will be executed when the component is run. Additional resources will be copied to the same directory.

Common properties:

  • type: file / r_script / python_script / bash_script / javascript_script / scala_script / csharp_script, specifies the type of the resource. The first resource cannot be of type file. When the type is not specified, the default type is simply file.
  • dest: filename, the resulting name of the resource. From within a script, the file can be accessed at meta["resources_dir"] + "/" + dest. If unspecified, dest will be set to the basename of the path parameter.
  • path: path/to/file, the path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.
  • text: …multiline text…, the content of the resulting file specified as a string. Mutually exclusive with path.
  • is_executable: true / false, whether the resulting resource file should be made executable.

Example:

resources:
  - type: r_script
    path: script.R
  - type: file
    path: resource1.txt

runners

Type: List of Runner

Default: Empty

A list of runners to execute target artifacts.

status

Type: Status

Default: Enabled

Allows setting a component to active, deprecated or disabled.

summary

Type: String

Default: Empty

A one-sentence summary of the component. This is only used for documentation.

Example:

summary: "A component for performing XYZ"

test_resources

Type: List of Resource

Default: Empty

One or more scripts to be used to test the component behaviour when viash test is invoked. Additional files of type file will be made available only during testing. Each test script should expect no command-line inputs, be platform-independent, and return an exit code >0 when unexpected behaviour occurs during testing. See Unit Testing for more info.

Example:

test_resources:
  - type: bash_script
    path: tests/test1.sh
  - type: r_script
    path: tests/test2.R
  - path: resource1.txt

usage

Type: String

Default: Empty

A description on how to use the component. This will be displayed with --help under the ‘Usage:’ section.

Example:

usage: Place the executable in a directory containing TSV files and run it

version

Type: String

Default: Empty

Version of the component. This field will be used to version the executable and the Docker container.

Note

When the version field is left empty in a component’s configuration, the value of .version in the package config will be copied during build.

Example:

version: 0.8