Skip to main content

​
Overview

The Latch platform uses metadata objects to define and customize workflow interfaces. If you are using the Python SDK, you can define the metadata object in your workflow code. If you are using Nextflow or Snakemake, the metadata object is auto-generated from the nextflow_json.schema or config.yaml file using the latch generate-metadata command. This document provides a comprehensive reference for all metadata types available in the Latch SDK.

​
Examples

Visit a few examples that our engineers have curated below:
https://files.svgcdn.io/vscode-icons/file-type-nextflow.png

nf-core/atacseq

ATAC-seq peak-calling and QC analysis pipeline, uploaded using the Nextflow SDK. Workflow UI Source Code

Boltz-2

A biomolecular foundation model that jointly predicts structure and binding affinity, uploaded using the Python SDK. Workflow UI Source Code

​
Core Metadata Classes

​
LatchMetadata

The primary metadata class for Python SDK workflows. 
from latch.types.metadata import LatchMetadata, LatchParameter, LatchAuthor

metadata = LatchMetadata(
    display_name="Workflow Name",
    author=LatchAuthor(
        name="Your Name",
        email="your.email@example.com",
        github="https://github.com/username"
    ),
    documentation="https://github.com/author/my_workflow/README.md",
    repository="https://github.com/author/my_workflow",
    license="MIT",
    parameters={
        'param_name': LatchParameter(
            display_name="Parameter Display Name",
            description="Parameter description",
            hidden=False,
            section_title="Section Title"
        )
    },
    tags=["NGS", "MAG"],
    flow=[...],
    no_standard_bulk_execution=False,
    about_page_path=Path("about.md")
)

​
Parameters

  • display_name (str): The human-readable name of the workflow
  • author (LatchAuthor): Author information for the workflow
  • documentation (str, optional): Link to workflow documentation
  • repository (str, optional): Link to source code repository
  • license (str): SPDX license identifier (default: “MIT”)
  • parameters (Dict[str, LatchParameter]): Parameter definitions
  • wiki_url (str, optional): Link to wiki documentation
  • video_tutorial (str, optional): Link to video tutorial
  • tags (List[str]): Tags for workflow discovery
  • flow (List[FlowBase]): Custom parameter layouts
  • no_standard_bulk_execution (bool): Disable standard CSV bulk execution
  • about_page_path (Path, optional): Path to about page markdown file

​
NextflowMetadata

Metadata class for Nextflow workflows. 
from latch.types.metadata import NextflowMetadata, NextflowParameter, LatchAuthor
from latch.types.metadata import NextflowRuntimeResources

metadata = NextflowMetadata(
    display_name="Nextflow Workflow",
    author=LatchAuthor(name="Your Name"),
    parameters={
        'input_file': NextflowParameter(
            type=LatchFile,
            display_name="Input File",
            description="Input file description"
        )
    },
    runtime_resources=NextflowRuntimeResources(
        cpus=8,
        memory=16,
        storage_gib=200
    ),
    execution_profiles=["docker", "test"],
    log_dir=LatchDir("latch:///log_directory"),
    upload_command_logs=True
)

​
Parameters

  • display_name (str): Workflow display name
  • author (LatchAuthor): Author information
  • parameters (Dict[str, NextflowParameter]): Parameter definitions
  • runtime_resources (NextflowRuntimeResources): Resource configuration
  • execution_profiles (List[str]): Available execution profiles
  • log_dir (LatchDir, optional): Directory for workflow logs
  • upload_command_logs (bool): Upload command logs to Latch Data

​
SnakemakeMetadata

Metadata class for Snakemake workflows. 
from latch.types.metadata import SnakemakeMetadata, SnakemakeParameter, LatchAuthor
from latch.types.metadata import DockerMetadata, EnvironmentConfig

metadata = SnakemakeMetadata(
    display_name="Snakemake Workflow",
    author=LatchAuthor(name="Your Name"),
    parameters={
        'samples': SnakemakeParameter(
            type=List[Sample],
            display_name="Samples",
            samplesheet=True
        )
    },
    file_metadata={
        'samples': SnakemakeFileMetadata(
            path=Path('data/samples/'),
            config=True,
            download=False
        )
    },
    output_dir=LatchDir("latch:///output_directory"),
    docker_metadata=DockerMetadata(
        username="username",
        secret_name="docker_secret"
    ),
    env_config=EnvironmentConfig(
        use_conda=True,
        use_container=False
    ),
    cores=8,
    about_page_content=Path("about.md")
)

​
Parameters

  • display_name (str): Workflow display name
  • author (LatchAuthor): Author information
  • parameters (Dict[str, SnakemakeParameter]): Parameter definitions
  • file_metadata (FileMetadata): File-specific metadata
  • output_dir (LatchDir, optional): Output directory location
  • docker_metadata (DockerMetadata, optional): Docker credentials
  • env_config (EnvironmentConfig): Environment configuration
  • cores (int): Number of cores for Snakemake tasks
  • about_page_content (Path, optional): Path to about page content

​
Parameter Classes

​
LatchParameter

Base parameter class for Python SDK workflows. 
LatchParameter(
    display_name="Parameter Name",
    description="Parameter description",
    hidden=False,
    section_title="Section Title",
    placeholder="Enter value...",
    comment="Additional comment",
    output=False,
    batch_table_column=False,
    allow_dir=True,
    allow_file=True,
    appearance_type=LatchAppearanceEnum.line,
    rules=[LatchRule(...)],
    detail="Additional detail text",
    samplesheet=False,
    allowed_tables=[1, 2, 3]
)

​
Parameters

  • display_name (str, optional): Human-readable parameter name
  • description (str, optional): Parameter description/tooltip
  • hidden (bool): Whether parameter is hidden by default
  • section_title (str, optional): Section grouping title
  • placeholder (str, optional): Placeholder text for input
  • comment (str, optional): Additional comment text
  • output (bool): Whether parameter is an output
  • batch_table_column (bool): Show in batch mode table
  • allow_dir (bool): Accept directories in UI
  • allow_file (bool): Accept files in UI
  • appearance_type (LatchAppearance): UI appearance type
  • rules (List[LatchRule]): Validation rules
  • detail (str, optional): Secondary label text
  • samplesheet (bool, optional): Enable samplesheet input
  • allowed_tables (List[int], optional): Allowed registry tables

​
NextflowParameter

Parameter class for Nextflow workflows. 
NextflowParameter(
    type=typing.Any,  # Required for Nextflow
    display_name="Parameter Name",
    description="Description",
    default=None,
    samplesheet=False,
    samplesheet_type='csv',
    samplesheet_constructor=custom_constructor,
    results_paths=[Path("output1"), Path("output2")]
)

​
Parameters

  • type (Type[T], optional): Expected parameter type
  • display_name (str, optional): Parameter display name
  • description (str, optional): Parameter description
  • default (T, optional): Default parameter value
  • samplesheet (bool, optional): Enable samplesheet input
  • samplesheet_type (Literal[“csv”, “tsv”, None]): Samplesheet format
  • samplesheet_constructor (Callable[[T], Path], optional): Custom constructor
  • results_paths (List[Path], optional): Output sub-paths for UI

​
SnakemakeParameter

Parameter class for Snakemake workflows. 
SnakemakeParameter(
    type=typing.Any,  # Required for Snakemake
    display_name="Parameter Name",
    description="Description",
    default=None
)

​
Parameters

  • type (Type[T], optional): Expected parameter type
  • display_name (str, optional): Parameter display name
  • description (str, optional): Parameter description
  • default (T, optional): Default parameter value

​
Organization of Parameters into Sections

By default, all parameters are rendered from top to bottom on the workflow UI, in the order they are defined in the metadata object. This can be overwhelming for end users if workflows have dozens or hundreds of parameters. To make the UI more user-friendly, you can organize parameters into Sections and take advantage of elements like Spoiler or Fork to collapse advanced parameters.

​
Custom Flows

Define custom parameter layouts using flow elements: 
flow=[
    Section(
        "Input Section",
        Text("Configure your input data"),
        Params("input_file", "output_dir")
    ),
    Section(
        "Processing Options",
        Text("Configure processing parameters"),
        Params("threads", "memory")
    ),
    Spoiler(
        "Advanced Options",
        Text("Advanced configuration options"),
        Params("advanced_param1", "advanced_param2")
    )
]

​
Appearance Customization

Customize parameter appearance: 
appearance_type=LatchAppearance(
    type=LatchAppearanceEnum.paragraph,
    placeholder="Enter detailed description...",
    comment="This field supports markdown formatting",
    detail="Additional context information"
)

​
Flow Elements

​
Section

Flow element that displays child flow in a titled card. 
Section(
    "Section Title",
    Text("Description text"),
    Params("param1", "param2"),
    Fork(...)
)

​
Text

Flow element that displays markdown text. 
Text("This is markdown text with **bold** and *italic* formatting")

​
Title

Flow element that displays a markdown title. 
Title("# Main Title")

​
Params

Flow element that displays parameter widgets. 
Params("param1", "param2", "param3")

​
Spoiler

Flow element that displays a collapsible card. 
Spoiler(
    "Advanced Options",
    Text("These are advanced configuration options"),
    Params("advanced_param1", "advanced_param2")
)

​
Fork

Flow element that displays mutually exclusive alternatives. 
Fork(
    "sample_fork",
    "Choose read type",
    paired_end=ForkBranch("Paired-end", Params("paired_end")),
    single_end=ForkBranch("Single-end", Params("single_end"))
)

​
Supporting Classes

​
LatchAuthor

Author information for workflows. 
LatchAuthor(
    name="Author Name",
    email="author@example.com",
    github="https://github.com/username"
)

​
LatchRule

Validation rule for parameter inputs. 
LatchRule(
    regex=r"\.(fastq|fq)$",
    message="Only .fastq or .fq files are allowed"
)

​
LatchAppearance

Parameter appearance configuration. 
# Line input
appearance_type=LatchAppearanceEnum.line

# Paragraph input
appearance_type=LatchAppearanceEnum.paragraph

# Multiselect with custom options
appearance_type=Multiselect(
    options=[
        MultiselectOption("Option 1", "value1"),
        MultiselectOption("Option 2", "value2")
    ],
    allow_custom=True
)

​
SnakemakeFileMetadata

File-specific metadata for Snakemake workflows. 
SnakemakeFileMetadata(
    path=Path('local/path/'),
    config=True,
    download=False
)

​
NextflowRuntimeResources

Resource configuration for Nextflow runtime tasks. 
NextflowRuntimeResources(
    cpus=8,
    memory=16,
    storage_gib=200,
    storage_expiration_hours=168  # 7 days
)

​
DockerMetadata

Credentials for private Docker repositories. 
DockerMetadata(
    username="docker_username",
    secret_name="docker_password_secret"
)

​
EnvironmentConfig

Environment configuration for Snakemake tasks. 
EnvironmentConfig(
    use_conda=True,
    use_container=False,
    container_args=["--gpus", "all"]
)

​
Type System

​
Supported Parameter Types

ParameterType = Union[
    None,
    int,
    float,
    str,
    bool,
    LatchFile,
    LatchDir,
    Enum,
    _IsDataclass,  # Any dataclass
    Collection["ParameterType"],  # Lists, Dicts, etc.
]

​
Type Validation

The SDK automatically validates parameter types based on:
  • Function signature type annotations
  • Metadata parameter definitions
  • Runtime value validation
  • Custom validation rules via LatchRule

​
Samplesheet Support

​
Basic Samplesheet

'samples': NextflowParameter(
    type=List[Sample],
    samplesheet=True,
    samplesheet_type='csv'
)

​
Custom Samplesheet Constructor

def custom_constructor(samples: List[Sample]) -> Path:
    # Custom logic to create samplesheet
    return Path("custom_samplesheet.txt")

'samples': NextflowParameter(
    type=List[Sample],
    samplesheet=True,
    samplesheet_constructor=custom_constructor
)

​
SamplesheetItems

Often when populating a samplesheet parameter using rows from Registry, it is useful to have access to the originating record that created the row. Wrapping a samplesheet type with the SamplesheetItem marker allows downstream code to easily access this underlying record. 
from latch.types.samplesheet_item import SamplesheetItem

@dataclass
class Sample:
    fastq_1: LatchFile
    fastq_2: Optional[LatchFile]

@task
def example(input: list[SamplesheetItem[Sample]]):
    for row in input:
        print(row.data) # `Sample` object, contains the underlying data of the row
        print(row.record) # `Record` object, None if the row wasn't imported from registry

​
Validation and Rules

​
Regex Validation

'filename': LatchParameter(
    display_name="Filename",
    rules=[
        LatchRule(
            regex=r"^[a-zA-Z0-9_-]+$",
            message="Filename must contain only letters, numbers, underscores, and hyphens"
        )
    ]
)

​
Multiple Rules

'email': LatchParameter(
    display_name="Email",
    rules=[
        LatchRule(
            regex=r"^[^@]+@[^@]+\.[^@]+$",
            message="Must be a valid email address"
        ),
        LatchRule(
            regex=r"^.{5,100}$",
            message="Email must be between 5 and 100 characters"
        )
    ]
)
⌘I