Functionality

The functionality-part of the config file 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.

add_resources_to_path

Type: Boolean

Warning

Removed since 0.5.11. Extending the PATH turned out to be not desirable.

Adds the resources directory to the PATH variable when set to true. This is set to false by default.

argument_groups

Type: List of ArgumentGroup

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 names.

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

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:

• string
• file
• integer
• double
• boolean
• boolean_true
• boolean_false

Example:

arguments:
  - name: --foo
    type: file
    alternatives: [-f]
    description: Description of foo
    default: "/foo/bar"
    must_exist: true
    direction: output
    required: false
    multiple: true
    multiple_sep: ","
  - name: --bar
    type: string

authors

Type: List of Author

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: Bob Cando
    roles: [maintainer, author]
    email: bob@can.do
    props: {github: bobcando, orcid: 0000-0001-0002-0003}
  - name: Tim Farbe
    roles: [author]
    email: tim@far.be

description

Type: String

A description of the component. This will be displayed with --help.

Example:

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

enabled

Type: Boolean

Warning

Deprecated since 0.6.0. Removed since 0.7.0. Use status instead.

Setting this to false with disable this component when using namespaces.

info

Type: Json

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

Example:

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

inputs

Type: List of Argument

Warning

Deprecated since 0.6.0. Removed since 0.7.0. Use arguments instead.

A list of input arguments in addition to the arguments list. Any arguments specified here will have their type set to file and the direction set to input by default.

Examples:

inputs:
  - name: input_file
  - name: another_input

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

component_with_inputs
  
  Inputs:
      input_file
          type: file
  
      another_input
          type: file

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

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

Example:

namespace: fancy_components

outputs

Type: List of Argument

Warning

Deprecated since 0.6.0. Removed since 0.7.0. Use arguments instead.

A list of output arguments in addition to the arguments list. Any arguments specified here will have their type set to file and thr direction set to output by default.

Examples:

outputs:
  - name: output_file
  - name: another_output

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

component_with_outputs
  
  Outputs:
      output_file
          type: file, output
  
      another_output
          type: file, output

requirements

Type: ComputationalRequirements

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.

Example:

requirements:
  cpus: 5
  memory: 10GB

resources

Type: List of Resource

Resources are files that support the component. The first resource should be a script that will be executed when the functionality 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

status

Type: Status

Allows setting a component to active, deprecated or disabled.

test_resources

Type: List of Resource

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

tests

Type: List of Resource

Warning

Deprecated since 0.5.13. Removed since 0.7.0. Use test_resources instead. No functional difference.

One or more Bash/R/Python 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.

usage

Type: String

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

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

Example:

version: 0.8