A Viash component can be translated into one or more platforms: Native, Docker, Nextflow. Each of these platforms result in a different artifact:
Native platform: a single executable is generated which runs natively on the host system. This assumes all dependencies are already installed by the user and is therefore not reproducible. Requirements: Bash.
Docker platform: a single executable is generated but it runs inside a Docker container instead. The Docker platform specification can help you install custom dependencies and will take care of auto-mounting input/output files. Requirements: Bash, Docker.
Nextflow platform: a Nextflow module which can be used as a standalone workflow or as a module in a larger workflow. Requirements: Nextflow and a containerization engine (e.g. Docker, Singularity, Podman).
Below we will create our first Viash component using any of the languages natively supported by Viash.
Create a script
When creating a new Viash component, you can write a new script or use a pre-existing script. Below is a script that simply copies an input file to an output destination.
The par variable(s) appear to be hard coded, but they’re not! When running this script with Viash, Viash will strip away the section between VIASH START and VIASH END, and replace it with parameter values at runtime. The values included in this script are thus entirely for development and debugging purposes. More information on how this works will be given in Variables and meta-variables.
Create a config
A Viash config file is a YAML file that describes the functionality of a component and the platform(s) it targets.
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_bashdescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: bash_scriptpath: script.shplatforms:-type: dockerimage:"bash:4.0"-type: native-type: nextflow
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_csharpdescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: csharp_scriptpath: script.csxplatforms:-type: dockerimage:"ghcr.io/data-intuitive/dotnet-script:1.3.1"-type: native-type: nextflow
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_jsdescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: javascript_scriptpath: script.jsplatforms:-type: dockerimage:"node:19-bullseye-slim"-type: native-type: nextflow
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_pythondescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: python_scriptpath: script.pyplatforms:-type: dockerimage:"python:3.10-slim"-type: native-type: nextflow
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_rdescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: r_scriptpath: script.Rplatforms:-type: dockerimage:"eddelbuettel/r2u:22.04"-type: native-type: nextflow
Create a file named config.vsh.yaml and add the contents below based on your chosen scripting language.
functionality:name: example_scaladescription: A minimal example component.arguments:-type: filename: --inputexample: file.txtrequired:true-type: filename: --outputdirection: outputexample: output.txtrequired:trueresources:-type: scala_scriptpath: script.scalaplatforms:-type: dockerimage:"sbtscala/scala-sbt:eclipse-temurin-19_36_1.7.2_2.13.10"-type: native-type: nextflow
Here’s a breakdown of the different sections:
functionality: A description of what the component does.
name: The name of the component.
arguments: The input and output parameters of the script.
resources: References to all necessary files and folders to make the component work.
platforms: Lists which platforms a component can target (i.e. Native, Docker or Nextflow).
Run the component
That’s it! With these two steps, you created your first component. Next, you can use the viash run command to test whether it actually works as intended.
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_bash
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_bash:latest'
[warning] Could not pull from 'example_bash:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_bash:latest' with Dockerfile
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/bash/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/bash/foo.txt'.
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_csharp
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_csharp:latest'
[warning] Could not pull from 'example_csharp:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_csharp:latest' with Dockerfile
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/csharp/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/csharp/foo.txt'.
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_js
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_js:latest'
[warning] Could not pull from 'example_js:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_js:latest' with Dockerfile
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/js/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/js/foo.txt'
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_python
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_python:latest'
[warning] Could not pull from 'example_python:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_python:latest' with Dockerfile
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/python/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/python/foo.txt'.
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_r
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_r:latest'
[warning] Could not pull from 'example_r:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_r:latest' with Dockerfile
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/r/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/r/foo.txt'.
[1] TRUE
You can call use the component’s --help functionality to get an overview its parameters and descriptions.
viash run config.vsh.yaml ----help
example_scala
A minimal example component.
Arguments:
--input
type: file, required parameter, file must exist
example: file.txt
--output
type: file, required parameter, output, file must exist
example: output.txt
As expected, this component has an --input and --output parameter. You can execute the component by providing values for these parameters.
viash run config.vsh.yaml ----input config.vsh.yaml --output foo.txt
[notice] Checking if Docker image is available at 'example_scala:latest'
[warning] Could not pull from 'example_scala:latest'. Docker image doesn't exist or is not accessible.
[notice] Building container 'example_scala:latest' with Dockerfile
warning: 1 deprecation; re-run with -deprecation for details
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/scala/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/scala/foo.txt'.
Note
The double dash (--) between the viash command and the arguments is used to signify the end of the arguments passed to Viash and the start of those passed to the script. If you forgot to add these, you’ll get an error similar to this:
viash run config.vsh.yaml \--input foo.txt \--output bar.txt
[scallop] Error: Unknown option 'input'
Build an executable
We will now turn the Viash component into an executable.
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/bash/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/bash/output.txt'.
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/csharp/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/csharp/output.txt'.
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/js/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/js/output.txt'
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/python/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/python/output.txt'.
warning: 1 deprecation; re-run with -deprecation for details
Copying '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/scala/config.vsh.yaml' to '/viash_automount/tmp/RtmpGyCAck/create_new_component44cd4ef3fa5/scala/output.txt'.