Components

A Viash component is a combination of a code block or script and a small amount of metadata that makes it easy to generate pipeline modules, facilitating the separation of component functionality from the pipeline workflow (Cannoodt et al., 2021). This enables developers to create reusable, modular, and robust components for OpenProblems, focusing on the specific functionality without having to worry about the chosen pipeline framework.

A Viash component consists of three main parts: a Viash config, a script, and one or more unit tests.

Example component

When creating a new Viash component, you will need to create a script and a config file. Below is an example of a simple Viash component written in Python. For a detailed explanation of the structure of a Viash component in more programming languages (Bash, Python, R), please review the Viash component guide.

Script

To help with prototyping, a Viash component’s script should be runnable standalone. You can do this by defining a Viash placeholder code block denoted by ## VIASH START and ## VIASH END comments.

The placeholder should contain a dictionary (or named list) with example values for all input/output arguments. During execution, Viash removes the placeholder and replaces it with the actual parameter values at runtime.

script.py

import anndata

## VIASH START
# Note: This codeblock is for prototyping and
# is removed by Viash at runtime.
par = {
  'input': 'test_resource.txt',
  'output': 'output.txt'
}
## VIASH END

# Print par
print(f"par: {par}")

# Read input file
adata = anndata.read_h5ad(par["input"])

# Print adata
print(f"adata: {adata}")

# Write output file
adata.write_h5ad(par["output"])

Tip

It is possible to store helper functions in separate files. Visit the Viash documentation for more information.

Viash config

config.vsh.yaml

name: mycomponent
label: My Component
summary: A short summary of the component.
description: |
  A multiline description.
arguments:
  - name: "--input"
    type: file
    description: Input h5ad
    example: input.h5ad
    required: true
  - name: "--output"
    type: file
    direction: output
    description: Output h5ad
    example: output.h5ad
    required: true
resources:
  - type: python_script
    path: script.py
tests:
  - type: python_script
    path: test.py
engines:
  - type: docker
    image: "python:3.10"
    setup:
      - type: python
        pypi: anndata
runners:
  - type: executable
  - type: nextflow

Tip

After adding arguments to the config, you can update your script’s placeholder using viash config inject command.

Component format specifications

OpenProblems tasks contain specifications for the common config fields shared between the same component types. These specifications are defined in src/api/comp_*.yaml files. For more information on how these specifications are formatted, see Design the API.

references

1. Cannoodt, R., Cannoodt, H., Van de Kerckhove, E., Boschmans, A., De Maeyer, D., & Verbeiren, T. (2021). Viash: from scripts to pipelines. arXiv. 10.48550/ARXIV.2110.11494 ↗