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
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:
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
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
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
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
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 typefile
. When the type is not specified, the default type is simplyfile
. - 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 thepath
parameter. - path:
path/to/file
, the path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive withtext
. - 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
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