Viash Component Config

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.

A list of platforms to generate target artifacts for.

• Native
• Docker
• Nextflow

Which source directory to use for the viash ns commands.

Which version of Viash to use.

Which target directory to use for viash ns build.

Path to the config used during build.

Git tag.

Git remote name.

The Viash version that was used to build the component.

Folder path to the build artifacts.

The platform id used during build.

Git commit hash.

Output folder with main executable path.

If VIASH_HOME is not defined, the fallback HOME/.viash is used.

Location where specific downloaded versions of Viash will be cached and run from.

A specific Viash version can be set to run the commands with. If so required, the specific Viash version will be downloaded. This is useful when replicating older results or building Viash components that use outdated code.

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

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

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

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:

The full list of roles is extremely comprehensive.

Allows setting a component to active, deprecated or disabled.

Computational requirements related to running the component.

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.

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.

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.

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

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

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

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

Full name of the author, usually in the name of FirstName MiddleName LastName.

E-mail of the author.

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

Author properties. Must be a map of strings.

The maximum number of (logical) cpus a component is allowed to use.

A list of commands which should be present on the system for the script to function.

The maximum amount of memory a component is allowed to allocate. Unit must be one of B, KB, MB, GB, TB or PB.

The name of the argument group.

List of arguments.

Description of foo`, a description of the argument group. Multiline descriptions are supported.

Running a Viash component on a native platform means that the script will be executed in your current environment. Any dependencies are assumed to have been installed by the user, so the native platform is meant for developers (who know what they're doing) or for simple bash scripts (which have no extra dependencies).

As with all platforms, you can give a platform a different name. By specifying id: foo, you can target this platform (only) by specifying -p foo in any of the Viash commands.

The base container to start from. You can also add the tag here if you wish.

Run a Viash component on a Docker backend platform. By specifying which dependencies your component needs, users will be able to build a docker container from scratch using the setup flag, or pull it from a docker repository.

Name of a container's organization.

The URL to the a custom Docker registry

Specify a Docker image based on its tag.

The tag the resulting image gets. Advanced usage only.

The separator between the namespace and the name of the component, used for determining the image name. Default: "/".

Enables or disables automatic volume mapping. Enabled when set to Automatic or disabled when set to Manual. Default: Automatic

As with all platforms, you can give a platform a different name. By specifying id: foo, you can target this platform (only) by specifying -p foo in any of the Viash commands.

A list of requirements for installing the following types of packages:

• apt
• apk
• Docker setup instructions
• JavaScript
• Python
• R
• Ruby
• yum

The order in which these dependencies are specified determines the order in which they will be installed.

The working directory when starting the container. This doesn't change the Dockerfile but gets added as a command-line argument at runtime.

If anything is specified in the setup section, running the ---setup will result in an image with the name of <target_image>:<version>. If nothing is specified in the setup section, simply image will be used. Advanced usage only.

The source of the target image. This is used for defining labels in the dockerfile.

Additional requirements specific for running unit tests.

The URL where the resulting image will be pushed to. Advanced usage only.

The Docker setup strategy to use when building a container.

The organization set in the resulting image. Advanced usage only.

In Linux, files created by a Docker container will be owned by root. With chown: true, Viash will automatically change the ownership of output files (arguments with type: file and direction: output) to the user running the Viash command after execution of the component. Default value: true.

Platform for generating Nextflow VDSL3 modules.

Automated processing flags which can be toggled on or off.

Directives are optional settings that affect the execution of the process.

Specifies the Docker platform id to be used to run Nextflow.

Allows tweaking how the Nextflow Config file is generated.

Whether or not to print debug messages.

Every platform can be given a specific id that can later be referred to explicitly when running or building the Viash component.

Specify which apk packages should be available in order to run the component.

Specify which apt packages should be available in order to run the component.

If false, the Debian frontend is set to non-interactive (recommended). Default: false.

Specify which Docker commands should be run during setup.

Specify which JavaScript packages should be available in order to run the component.

Specify which Python packages should be available in order to run the component.

Sets the --upgrade flag when set to true. Default: true.

Sets the --user flag when set to true. Default: false.

Specify which R packages should be available in order to run the component.

Forces packages specified in bioc to be reinstalled, even if they are already present in the container. Default: false.

Specify which Ruby packages should be available in order to run the component.

Specify which yum packages should be available in order to run the component.

The name of the argument. Can be in the formats --trim, -t or trim. The number of dashes determines how values can be passed:

• --trim is a long option, which can be passed with executable_name --trim
• -t is a short option, which can be passed with executable_name -t
• trim is an argument, which can be passed with executable_name trim

A boolean type argument has two possible values: true or false.

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

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

The delimiter character for providing multiple values. : by default.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

The name of the argument. Can be in the formats --silent, -s or silent. The number of dashes determines how values can be passed:

• --silent is a long option, which can be passed with executable_name --silent
• -s is a short option, which can be passed with executable_name -s
• silent is an argument, which can be passed with executable_name silent

An argument of the boolean_true type acts like a boolean flag with a default value of false. When called as an argument it sets the boolean to true.

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

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

The name of the argument. Can be in the formats --no-log, -n or no-log. The number of dashes determines how values can be passed:

• --no-log is a long option, which can be passed with executable_name --no-log
• -n is a short option, which can be passed with executable_name -n
• no-log is an argument, which can be passed with executable_name no-log

An argument of the boolean_false type acts like an inverted boolean flag with a default value of true. When called as an argument it sets the boolean to false.

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

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

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

A double type argument has a numeric value with decimal points

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

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

The delimiter character for providing multiple values. : by default.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

A file type argument has a string value that points to a file or folder path.

If the output filename is a path and it does not exist, create it before executing the script (only for direction: output).

Makes this argument an input or an output, as in does the file/folder needs to be read or written. input by default.

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

Checks whether the file or folder exists. For input files, this check will happen before the execution of the script, while for output files the check will happen afterwards.

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

The delimiter character for providing multiple values. : by default.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

An integer type argument has a numeric value without decimal points.

Limit the amount of valid values for this argument to those set in this list. When set and a value not present in the list is provided, an error will be produced.

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

Maximum allowed value for this argument. If set and the provided value is higher than the maximum, an error will be produced. Can be combined with min to clamp values.

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

The delimiter character for providing multiple values. : by default.

Minimum allowed value for this argument. If set and the provided value is lower than the minimum, an error will be produced. Can be combined with max to clamp values.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

An long type argument has a numeric value without decimal points.

Limit the amount of valid values for this argument to those set in this list. When set and a value not present in the list is provided, an error will be produced.

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

Maximum allowed value for this argument. If set and the provided value is higher than the maximum, an error will be produced. Can be combined with min to clamp values.

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

The delimiter character for providing multiple values. : by default.

Minimum allowed value for this argument. If set and the provided value is lower than the minimum, an error will be produced. Can be combined with max to clamp values.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

The name of the argument. Can be in the formats --foo, -f or foo. The number of dashes determines how values can be passed:

• --foo is a long option, which can be passed with executable_name --foo=value or executable_name --foo value
• -f is a short option, which can be passed with executable_name -f value
• foo is an argument, which can be passed with executable_name value

A string type argument has a value made up of an ordered sequences of characters, like "Hello" or "I'm a string".

Limit the amount of valid values for this argument to those set in this list. When set and a value not present in the list is provided, an error will be produced.

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

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

The delimiter character for providing multiple values. : by default.

Treat the argument value as an array. Arrays can be passed using the delimiter --foo=1:2:3 or by providing the same argument multiple times --foo 1 --foo 2. You can use a custom delimiter by using the multiple_sep property. false by default.

Make the value for this argument required. If set to true, an error will be produced if no value was provided. false by default.

An executable Bash script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

An executable C# script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

An executable file.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

An executable JavaScript script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

A Nextflow script. Work in progress; added mainly for annotation at the moment.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

The name of the workflow to be executed.

Whether the resulting resource file should be made executable.

Resulting filename 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.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

A plain file. This can only be used as a supporting resource for the main script or unit tests.

Resulting filename 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.

An executable Python script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

An executable R script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

An executable Scala script. When defined in functionality.resources, only the first entry will be executed when running the built component or when running viash run. When defined in functionality.test_resources, all entries will be executed during viash test.

The path of the input file. Can be a relative or an absolute path, or a URI. Mutually exclusive with text.

The content of the resulting file specified as a string. Mutually exclusive with path.

Whether the resulting resource file should be made executable.

Resulting filename 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.

The beforeScript directive allows you to execute a custom (Bash) snippet before the main process script is run. This may be useful to initialise the underlying cluster environment or for other custom initialisation.

See beforeScript.

The accelerator directive allows you to specify the hardware accelerator requirement for the task execution e.g. GPU processor.

Viash implements this directive as a map with accepted keywords: type, limit, request, and runtime.

See accelerator.

The time directive allows you to define how long a process is allowed to run.

See time.

The afterScript directive allows you to execute a custom (Bash) snippet immediately after the main process has run. This may be useful to clean up your staging area.

See afterScript.

The executor defines the underlying system where processes are executed. By default a process uses the executor defined globally in the nextflow.config file.

The executor directive allows you to configure what executor has to be used by the process, overriding the default configuration. The following values can be used:

See executor.

The disk directive allows you to define how much local disk storage the process is allowed to use.

See disk.

The tag directive allows you to associate each process execution with a custom label, so that it will be easier to identify them in the log file or in the trace execution report.

See tag.

The machineType can be used to specify a predefined Google Compute Platform machine type when running using the Google Life Sciences executor.

See machineType.

The stageInMode directive defines how input files are staged-in to the process work directory. The following values are allowed:

See stageInMode.

The penv directive allows you to define the parallel environment to be used when submitting a parallel task to the SGE resource manager.

See penv.

The storeDir directive allows you to define a directory that is used as a permanent cache for your process results.

See storeDir.

The errorStrategy directive allows you to define how an error condition is managed by the process. By default when an error status is returned by the executed script, the process stops immediately. This in turn forces the entire pipeline to terminate.

Table of available error strategies:

See errorStrategy.

The memory directive allows you to define how much memory the process is allowed to use.

See memory.

The stageOutMode directive defines how output files are staged-out from the scratch directory to the process work directory. The following values are allowed:

See stageOutMode.

If true, an input tuple only containing only a single File (e.g. ["foo", file("in.h5ad")]) is automatically transformed to a map (i.e. ["foo", [ input: file("in.h5ad") ] ]).

Default: true.

If true, an output tuple containing a map with a File (e.g. ["foo", [ output: file("out.h5ad") ] ]) is automatically transformed to a map (i.e. ["foo", file("out.h5ad")]).

Default: true.

If true, the module's outputs are automatically published to params.publishDir. Will throw an error if params.publishDir is not defined.

Default: false.

If true, the module's transcripts from work/ are automatically published to params.transcriptDir. If not defined, params.publishDir + "/_transcripts" will be used. Will throw an error if neither are defined.

Default: false.

A series of default labels to specify memory and cpu constraints.

The default memory labels are defined as "mem1gb", "mem2gb", "mem4gb", ... upto "mem512tb" and follows powers of 2. The default cpu labels are defined as "cpu1", "cpu2", "cpu5", "cpu10", ... upto "cpu1000" and follows a semi logarithmic scale (1, 2, 5 per decade).

Conceptually it is possible for a Viash Config to overwrite the full labels parameter, however likely it is more efficient to add additional labels in the Viash Project with a config mod.