### Pipeline Configuration Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of a Nextflow configuration file used with paramsSummaryLog.

```groovy
--8<-- "examples/paramsSummaryLog/pipeline/nextflow.config"
```

--------------------------------

### Pipeline Configuration Example for Map

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of a Nextflow configuration file used with paramsSummaryMap.

```groovy
--8<-- "examples/paramsSummaryMap/pipeline/nextflow.config"
```

--------------------------------

### Nextflow Configuration for Basic Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The Nextflow configuration file used in the basic samplesheetToList() example.

```groovy
--8<-- "examples/samplesheetToListBasic/pipeline/nextflow.config"
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Install the necessary Python packages for building and serving the project documentation using MkDocs.

```bash
pip install mkdocs-material pymdown-extensions pillow cairosvg
```

--------------------------------

### Summary Map Output Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of the output generated by paramsSummaryMap, returned as a Groovy Map.

```text
--8<-- "examples/paramsSummaryMap/log.txt"
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Build and serve the project documentation locally for previewing changes. Requires MkDocs and its dependencies to be installed.

```bash
mkdocs serve
```

--------------------------------

### Summary Log Output Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of the terminal output generated by paramsSummaryLog.

```text
--8<-- "examples/paramsSummaryLog/log.txt"
```

--------------------------------

### Pipeline Main Script Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of how to include the paramsSummaryLog function in your main Nextflow script.

```groovy
--8<-- "examples/paramsSummaryLog/pipeline/main.nf"
```

--------------------------------

### Nextflow Configuration for Meta Map Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The Nextflow configuration file for the example demonstrating a channel with a meta map.

```groovy
--8<-- "examples/samplesheetToListMeta/pipeline/nextflow.config"
```

--------------------------------

### Full Help Output Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

This shows the complete help message generated by `paramsHelp()` when run with the `--help` flag, including all available parameters.

```text
--8<-- "examples/paramsHelp/log.txt"
```

--------------------------------

### Add Example Command to Help

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Include an example command in the help message, displayed after beforeText. This does not affect the paramsHelp() function output. Defaults to an empty string.

```groovy
validation.help.command = "nextflow run main.nf --input samplesheet.csv --outdir output" // default: ""
```

--------------------------------

### Pipeline Main Script Example for Map

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example of how to include the paramsSummaryMap function in your main Nextflow script.

```groovy
--8<-- "examples/paramsSummaryMap/pipeline/main.nf"
```

--------------------------------

### Pipeline Schema Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example JSON schema file used by paramsSummaryLog for parameter validation.

```json
--8<-- "examples/paramsSummaryLog/pipeline/nextflow_schema.json"
```

--------------------------------

### Channel with meta map using samplesheetToList()

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

This example shows how to use the schema to mark columns as meta fields, resulting in a channel that includes a meta map.

```groovy
--8<-- "examples/samplesheetToListMeta/pipeline/main.nf"
```

--------------------------------

### Specific Parameter Help Output Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

This demonstrates the help message for a specific parameter, 'outdir', generated by `paramsHelp()` when invoked with `--help outdir`.

```text
--8<-- "examples/paramsHelp/log_outdir.txt"
```

--------------------------------

### Install Development Plugin

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Install the current development version of the nf-schema plugin into the local Nextflow plugins directory.

```bash
make install
```

--------------------------------

### Pipeline Schema Example for Map

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/summary_log.md

Example JSON schema file used by paramsSummaryMap for parameter validation.

```json
--8<-- "examples/paramsSummaryMap/pipeline/nextflow_schema.json"
```

--------------------------------

### Install nf-core Tools

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/create_schema.md

Install the nf-core command-line tools package using pip or conda. Ensure bioconda channels are configured if using conda.

```bash
pip install nf-core
```

```bash
conda install nf-core # (1)!
```

--------------------------------

### CSV Sample Sheet for Meta Map Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The CSV sample sheet content used in the example demonstrating a channel with a meta map.

```csv
--8<-- "examples/samplesheetToListMeta/samplesheet.csv"
```

--------------------------------

### Order of fields demonstration with samplesheetToList()

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

This example demonstrates that the order of columns in the sample sheet file does not affect the output. The order is determined by the sample sheet JSON schema.

```groovy
--8<-- "examples/samplesheetToListOrder/pipeline/main.nf"
```

--------------------------------

### Basic samplesheetToList() usage with CSV

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

This example demonstrates the basic usage of samplesheetToList() with a CSV sample sheet. It shows how to create a simple channel from the processed data.

```groovy
--8<-- "examples/samplesheetToListBasic/pipeline/main.nf"
```

--------------------------------

### Example Nextflow Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_examples.md

This snippet displays an example JSON Schema for a Nextflow pipeline configuration file. It is used as a test fixture in the nf-schema package.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Nextflow Pipeline Schema Example",
  "description": "A sample JSON schema for a Nextflow pipeline configuration.",
  "type": "object",
  "properties": {
    "input": {
      "type": "string",
      "description": "Path to the input data file or directory.",
      "pattern": "^s3://.*|^gs://.*|^file://.*|^/.*|.*\\.txt|.*\\.csv"
    },
    "output": {
      "type": "string",
      "description": "Path for the output results.",
      "pattern": "^s3://.*|^gs://.*|^file://.*|^/.*"
    },
    "threads": {
      "type": "integer",
      "description": "Number of threads to use for the pipeline.",
      "minimum": 1,
      "default": 4
    },
    "email": {
      "type": "string",
      "description": "Email address for notifications.",
      "format": "email"
    },
    "validate": {
      "type": "boolean",
      "description": "Whether to perform validation on the output.",
      "default": true
    },
    "params": {
      "type": "object",
      "description": "Additional parameters for the pipeline.",
      "properties": {
        "genome": {
          "type": "string",
          "description": "Reference genome assembly ID.",
          "enum": ["hg19", "hg38", "mm10", "mm39"]
        },
        "aligner": {
          "type": "string",
          "description": "Sequence alignment tool.",
          "default": "bwa"
        }
      },
      "required": ["genome"]
    }
  },
  "required": [
    "input",
    "output",
    "params"
  ]
}
```

--------------------------------

### JSON Schema for Basic Example

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The JSON schema file used to validate and process the CSV sample sheet in the basic example.

```json
--8<-- "examples/samplesheetToListBasic/pipeline/assets/schema_input.json"
```

--------------------------------

### Example of parameter validation failure

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/validation.md

This example shows a deliberate typo in `params.input` which is caught by the validation function, causing Nextflow to exit with an error. It includes the pipeline script, configuration, schema, and expected output log.

```text
--8<-- "examples/validateParameters/log.txt"
```

```groovy
--8<-- "examples/validateParameters/pipeline/main.nf"
```

```groovy
--8<-- "examples/validateParameters/pipeline/nextflow.config"
```

```json
--8<-- "examples/validateParameters/pipeline/nextflow_schema.json"
```

--------------------------------

### Meta Field Configuration in Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/sample_sheet_schema_specification.md

Configures a field in the sample sheet schema to be treated as a meta value. This example assigns the 'field' value to a meta field named 'id'.

```json
{
  "meta": "id"
}
```

--------------------------------

### Full Help Message (`--helpFull`)

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Prints all parameters, including deeply nested ones, along with their descriptions. This provides a comprehensive view of all available configuration options.

```bash
--reference.fasta           [string]          The FASTA file
--reference.fai             [string]          The FAI file
--reference.aligners.bwa    [string]          The BWA index
--reference.aligners.bowtie [string]          The BOWTIE index
--type                      [string]          The analysis type (accepted: WES, WGS)
--help                      [boolean, string] Show the help message for all top level parameters. When a parameter is given to `--help`, the full help message of that parameter will be printed.

```

--------------------------------

### Basic Configuration Syntax

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Illustrates the two primary syntaxes for setting nf-schema configuration options.

```groovy
validation.<option> = <value>
```

```groovy
validation {
    <option1> = <value1>
    <option2> = <value2>
}
```

--------------------------------

### Run Tests

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Execute all tests for the project using the make command.

```bash
make test
```

--------------------------------

### Nextflow Configuration for Order Demonstration

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The Nextflow configuration file for the order of fields demonstration.

```groovy
--8<-- "examples/samplesheetToListOrder/pipeline/nextflow.config"
```

--------------------------------

### Top-Level Help Message (`--help`)

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Displays help for top-level parameters, including their types, descriptions, options, and defaults if available in the schema. It also shows grouped parameters.

```bash
--reference  [object]          A group of parameters to configure the reference sets
--type       [string]          The analysis type (accepted: WES, WGS)
--help       [boolean, string] Show the help message for all top level parameters. When a parameter is given to `--help`, the full help message of that parameter will be printed.
--helpFull   [boolean]         Show the help message for all non-hidden parameters.
--showHidden [boolean]         Show all hidden parameters in the help message. This needs to be used in combination with `--help` or `--helpFull`.

Input parameters
    --input  [string] The input samplesheet
    --outdir [string] The output directory [default: results]

```

--------------------------------

### Remove nf-schema Plugin Versions

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Clean up all installed versions of the nf-schema plugin from the Nextflow plugins directory. Use with caution.

```bash
rm -rf ~/.nextflow/plugins/nf-schema*
```

--------------------------------

### Setting Default Parameter Values

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Illustrates how to define a default value for a parameter. If no default is needed, omit the 'default' key entirely.

```json
{
  "default": "some_default_value"
}
```

--------------------------------

### Typical Nextflow Pipeline Command

Source: https://github.com/nextflow-io/nf-schema/blob/master/examples/helpMessage/log_outdir.txt

Illustrates a common command structure for running a Nextflow pipeline with input and output parameters.

```bash
nextflow run my_pipeline --input input_file.csv
```

--------------------------------

### Providing Extended Help Text for Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Demonstrates the use of the non-standard 'help_text' key for providing longer, more detailed usage instructions for a parameter, potentially including markdown.

```json
!!! example "Non-standard key"

A longer text with usage help for the parameter, written in markdown.
Can include newlines with multiple paragraphs and more complex markdown structures.

Typically hidden by default in documentation and interfaces, unless explicitly clicked / requested.
```

--------------------------------

### JSON Schema for Order Demonstration

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The JSON schema file used in the order of fields demonstration. Note the highlighted lines indicating the field order.

```json
--8<-- "examples/samplesheetToListOrder/pipeline/assets/schema_input.json"
```

--------------------------------

### Create a queue channel from a sample sheet list

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

Use samplesheetToList() with the Channel.fromList() factory to create a queue channel. This mimics the functionality of the previous nf-validation's fromSamplesheet factory.

```groovy
Channel.fromList(samplesheetToList("path/to/samplesheet", "path/to/json/schema"))
```

--------------------------------

### Help Text for a Single Parameter

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Displays detailed help information for a specific parameter, including its type, description, format, pattern, help text, and existence requirement.

```bash
--input
    type       : string
    description: The input samplesheet
    format     : file-path
    pattern    : ^.$\\.csv$
    help_text  : This file needs to contain all input samples
    exists     : true
```

--------------------------------

### Configure Logging for Unrecognized Sample Sheet Headers

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Set the logging level for unrecognized headers in sample sheets. Options include skip, debug, info, warn, and error. Defaults to 'warn'.

```groovy
validation.logging.unrecognisedHeaders = "warn" // default: "warn"
```

--------------------------------

### Release and Publish Plugin

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Build and publish the nf-schema plugin. This involves updating version information, configuring Gradle properties, and executing the release process.

```bash
make release
```

--------------------------------

### Adding Parameter Descriptions

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Shows how to include a concise markdown description for a parameter, which will be displayed in documentation and help text.

```json
{
  "description": "A short description of what the parameter does."
}
```

--------------------------------

### CSV Sample Sheet for Order Demonstration

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The CSV sample sheet content used to demonstrate the order of fields in samplesheetToList().

```csv
--8<-- "examples/samplesheetToListOrder/samplesheet.csv"
```

--------------------------------

### Create a channel from sample sheet paths using flatMap

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

Use samplesheetToList() with the Channel.flatMap() operator to create a channel from sample sheet paths that are already in a channel. This is useful for processing multiple sample sheets.

```groovy
Channel.of("path/to/samplesheet").flatMap { samplesheetToList(it, "path/to/json/schema") }
```

--------------------------------

### Help Text for a Grouped Parameter

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Shows help information for a group of related parameters, including a description of the group and individual options within it.

```bash
--reference.aligners
    type       : object
    description: A group of parameters specifying the aligner indices
    options    :
        --reference.aligners.bwa    [string] The BWA index
        --reference.aligners.bowtie [string] The BOWTIE index
```

--------------------------------

### Default behavior for unrecognized parameters (Warning)

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/validation.md

Shows the default behavior where unrecognized parameters trigger a WARNING. Includes the configuration, pipeline script, and output log.

```text
--8<-- "examples/validationWarnUnrecognisedParams/log.txt"
```

```groovy
--8<-- "examples/validationWarnUnrecognisedParams/pipeline/nextflow.config"
```

```groovy
--8<-- "examples/validationWarnUnrecognisedParams/pipeline/main.nf"
```

--------------------------------

### Mapping Schema Properties to Nextflow Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Demonstrates how the keys within the 'properties' object in the schema correspond to parameter variable names in Nextflow configuration.

```json
// ..
"type": "object",
"properties": {
    "foo": {
        "type": "string",
        // ..
    }
}
// ..
```

--------------------------------

### Customize Full Help Parameter

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Changes the parameter used to display the expanded help message. Defaults to '--helpFull'.

```groovy
validation.help.shortParameter = "giveMeHelpFull" // default: "helpFull"
```

--------------------------------

### Generate Pipeline Help Message

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

The `paramsHelp()` function generates a help message for pipeline execution and its parameters. Pass it to `log.info` to display it in the terminal. It accepts options to customize the output, such as specifying a schema file, adding custom text, or controlling the display of hidden and full help details.

```groovy
--8<-- "examples/paramsHelp/pipeline/main.nf"
```

```groovy
--8<-- "examples/paramsHelp/pipeline/nextflow.config"
```

```json
--8<-- "examples/paramsHelp/pipeline/nextflow_schema.json"
```

--------------------------------

### Default Channel Item Structure

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Illustrates the default tuple structure emitted by `samplesheetToList()` for a sample sheet with headers, including meta values and file paths. Missing values result in an empty list.

```groovy
// Columns:
[ val([ sample: sample ]), file(fastq1), file(fastq2), file(bed) ]

// Resulting in:
[ [ id: "sample" ], fastq1.R1.fq.gz, fastq1.R2.fq.gz, sample1.bed]
[ [ id: "sample2" ], fastq2.R1.fq.gz, fastq2.R2.fq.gz, [] ] // A missing value from the sample sheet is an empty list
```

--------------------------------

### Enabling Help Message Generation (nf-schema)

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

This configuration snippet demonstrates how to enable the help message generation in nf-schema by setting 'enabled = true' and specifying the command. This change requires updating the nextflow.config file.

```groovy
validation {
    help {
        enabled = true
        command = "nextflow run my_pipeline --input input_file.csv"
    }
}
```

--------------------------------

### Fail behavior for unrecognized parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/validation.md

Demonstrates how to configure Nextflow to FAIL when unrecognized parameters are provided. Includes the configuration, pipeline script, and output log.

```text
--8<-- "examples/validationFailUnrecognisedParams/log.txt"
```

```groovy
--8<-- "examples/validationFailUnrecognisedParams/pipeline/nextflow.config"
```

```groovy
--8<-- "examples/validationFailUnrecognisedParams/pipeline/main.nf"
```

--------------------------------

### Join FASTQ and BED channels using meta

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Rejoin previously separated channels based on a common identifier, typically the 'meta' field. This ensures that related data from different channels are processed together.

```groovy
input.fastq
    .join( input.bed )
    .set { input_joined }

input_joined.view() // Channel has 4 elements: meta, fastq_1, fastq_2, bed
```

--------------------------------

### Call validateParameters() with custom options

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/validation.md

Demonstrates how to call the `validateParameters()` function with custom schema file, monochrome logs, and type casting options.

```nextflow
validateParameters(parameters_schema: 'custom_nextflow_parameters.json', monochrome_logs: true, cast_cli_params: true)
```

--------------------------------

### Enable Help Message Generation

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Add this configuration to your `nextflow.config` file to enable the creation of help messages. This will generate help messages when the pipeline user passes the `--help` and `--helpFull` parameters.

```groovy
validation {
    help {
        enabled = true
    }
}
```

--------------------------------

### Add Text Before Help Message

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Specify a string to be printed before the help message. This does not affect the paramsHelp() function output. Defaults to an empty string.

```groovy
validation.help.beforeText = "Running pipeline version 1.0" // default: ""
```

--------------------------------

### Configure Logging for Unrecognized Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Set the logging level for unrecognized parameters. Options include skip, debug, info, warn, and error. Defaults to 'warn'.

```groovy
validation.logging.unrecognisedParams = "warn" // default: "warn"
```

--------------------------------

### Customize Short Help Parameter

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Changes the parameter used to display the help message with top-level parameters. Defaults to '--help'.

```groovy
validation.help.shortParameter = "giveMeHelp" // default: "help"
```

--------------------------------

### Show Hidden Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

Hidden parameters defined in the JSON schema are not displayed in the default help message. Use the `--showHidden` flag to include them.

```bash
nextflow run your_pipeline --showHidden
```

--------------------------------

### Build Pipeline Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/create_schema.md

Run the `nf-core schema build` command in your pipeline's root directory to generate or update the `nextflow_schema.json` file. This tool helps extract configuration and prompts for schema updates.

```bash
nf-core schema build
```

--------------------------------

### Validate and convert sample sheet to Groovy list

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

Use samplesheetToList() to validate and convert a sample sheet to a Groovy list. Provide the path to the samplesheet and its corresponding JSON schema.

```groovy
samplesheetToList("path/to/samplesheet", "path/to/json/schema")
```

--------------------------------

### Transforming Channel Items with .map()

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Uses the `.map()` operator to transform a flat tuple of meta and file paths into a tuple containing meta and a list of FASTQ files, suitable for processes expecting a list of files.

```groovy
Channel.fromList(samplesheetToList(params.input, "path/to/json/schema"))
    .map { meta, fastq_1, fastq_2 -> tuple(meta, [ fastq_1, fastq_2 ]) }
    .set { input }

input.view() // Channel has 2 elements: meta, fastqs
```

--------------------------------

### Automated script to update plugin includes

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

Use this bash command to find and replace 'nf-validation' with 'nf-schema' in all .nf files.

```bash
find . -type f -name "*.nf" -exec sed -i -e "s/from 'plugin\/nf-validation'/from 'plugin\/nf-schema'/g" -e 's/from "plugin\/nf-validation"/from "plugin\/nf-schema"/g' {} + 
```

--------------------------------

### Enable Help Message in nextflow.config

Source: https://github.com/nextflow-io/nf-schema/blob/master/README.md

Enable the creation of a help message that can be displayed using the --help flag. This is configured within the validation section of the nextflow.config file.

```groovy
validation {
  help {
    enabled = true
  }
}
```

--------------------------------

### --outdir Parameter Definition

Source: https://github.com/nextflow-io/nf-schema/blob/master/examples/helpMessage/log_outdir.txt

Defines the --outdir parameter, specifying its type as a string representing a directory path. Emphasizes the requirement for absolute paths on cloud infrastructure.

```plaintext
--outdir
    type       : string
    format     : directory-path
    description: The output directory where the results will be saved. You have to use absolute paths to storage on Cloud infrastructure.
```

--------------------------------

### Add Text Before Summary Log

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Specify a string to be printed before the parameters log message. Defaults to an empty string.

```groovy
validation.summary.beforeText = "Running pipeline version 1.0" // default: ""
```

--------------------------------

### Lint Groovy Code

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Run pre-commit hooks to lint the Groovy code in the project.

```bash
pre-commit run
```

--------------------------------

### Defining Enumerated Values for Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Illustrates how to use the 'enum' key to restrict a parameter's value to a specific list of allowed options, applicable to string, number, and integer types.

```json
{
  "enum": ["red", "amber", "green"]
}
```

--------------------------------

### Enable Help Message Generation

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Enables the creation of a help message when help-related parameters are used in the Nextflow command.

```groovy
validation.help.enabled = true // default: false
```

--------------------------------

### Specify File MIME Type

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Use 'mimetype' when 'format' is 'file-path' to indicate the expected MIME type of the file, aiding downstream tools.

```json
{
  "type": "string",
  "format": "file-path",
  "mimetype": "text/csv"
}
```

--------------------------------

### Specifying Nested Parameters in Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Illustrates how to define nested parameters within the schema using the 'properties' keyword, allowing for hierarchical parameter structures.

```json
{
  "type": "object",
  "properties": {
    "thisIsNested": {
      "type": "object",
      "properties": {
        "deep": {
          "type": "string"
        }
      }
    }
  }
}
```

--------------------------------

### Set Parameters Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Configures the JSON schema file used for parameter validation and help message generation. Defaults to 'nextflow_schema.json'.

```groovy
validation.parametersSchema = "path/to/schema.json" // default "nextflow_schema.json"
```

--------------------------------

### Nextflow Schema with $defs Grouping

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Demonstrates how to use the $defs section to group parameters for organizational purposes in documentation and logging, while the allOf section ensures they are brought to the top level for validation.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "$defs": {
    "my_group_of_params": {
      "title": "A virtual grouping used for docs and pretty-printing",
      "type": "object",
      "required": ["foo", "bar"],
      "properties": {
        "foo": {
          "type": "string"
        },
        "bar": {
          "type": "string"
        }
      }
    }
  },
  "allOf": [
    { "$ref": "#/$defs/my_group_of_params" }
  ]
}
```

--------------------------------

### Include and Use Validate Function

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/validate/validate.md

Include the `validate` function from the `nf-schema` plugin and call it with input data and a schema.

```groovy
include {
    validate
} from 'plugin/nf-schema'

validate(<input>, <schema>)
```

--------------------------------

### View separated FASTQ and BED channels

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Access and view the contents of channels created by multiMap. Note the differing number of elements in the original channel versus the separated channels.

```groovy
input.fastq.view() // Channel has 3 elements: meta, fastq_1, fastq_2
input.bed.view()   // Channel has 2 elements: meta, bed
```

--------------------------------

### Add Text After Help Message

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Specify a string to be printed after the help message. This does not affect the paramsHelp() function output. Defaults to an empty string.

```groovy
validation.help.afterText = "Please cite the pipeline owners when using this pipeline" // default: ""
```

--------------------------------

### Defining Required Parameters in Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Specifies which parameters must be provided by the user. Ensure 'null' is the default if a parameter should be optional but can be explicitly set to null.

```json
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" },
    "address": { "type": "string" },
    "telephone": { "type": "string" }
  },
  "required": ["name", "email"]
}
```

--------------------------------

### Update Schema Draft Compatibility

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/create_schema.md

Convert the schema to the correct draft version and update definitions syntax using `sed`. This is a workaround for older `nf-core` tools versions.

```bash
sed -i -e 's/http:\/\/json-schema.org\/draft-07\/schema/https:\/\/json-schema.org\/draft\/2020-12\/schema/g' -e 's/definitions/$defs/g' nextflow_schema.json
```

--------------------------------

### Update samplesheet conversion from nf-validation to nf-schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

Replace the 'fromSamplesheet' channel factory with the 'samplesheetToList' function for processing samplesheets.

```groovy
include { fromSamplesheet } from 'plugin/nf-validation'
Channel.fromSamplesheet("input")
```

```groovy
include { samplesheetToList } from 'plugin/nf-schema'
Channel.fromList(samplesheetToList(params.input, "path/to/samplesheet/schema"))
```

--------------------------------

### Sample Sheet Parameter Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/validate_sample_sheet.md

This JSON schema defines a parameter 'input' that expects a file path ending in '.csv'. It specifies a 'schema' field pointing to 'src/testResources/samplesheet_schema.json' for validation.

```json
{
  "properties": {
    "input": {
      "type": "string",
      "format": "file-path",
      "pattern": "^\\S+\\.csv$",
      "schema": "src/testResources/samplesheet_schema.json",
      "description": "Path to comma-separated file containing information about the samples in the experiment."
    }
  }
}
```

--------------------------------

### Update default samplesheet schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

Apply the schema update command to the default samplesheet schema file in nf-core pipelines.

```bash
bash sed -i -e 's/https?::\/\/json-schema.org\/draft-07\/schema/https:\/\/json-schema.org\/draft\/2020-12\/schema/g' -e 's/definitions/\$defs/g' assets/schema_input.json
```

--------------------------------

### Add Text After Summary Log

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Specify a string to be printed after the parameters log message. Defaults to an empty string.

```groovy
validation.summary.afterText = "Please cite the pipeline owners when using this pipeline" // default: ""
```

--------------------------------

### Marking Parameters as Deprecated

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Shows how to use the 'deprecated' boolean flag to indicate that a parameter is no longer recommended for use, potentially with an 'errorMessage' for guidance.

```json
!!! example "Extended key"

A boolean JSON flag that instructs anything using the schema that this parameter/field is deprecated and should not be used. This can be useful to generate messages telling the user that a parameter has changed between versions.

JSON schema states that this is an informative key only, but in `nf-schema` this will cause a validation error if the parameter/field is used.

!!! tip

    Using the [`errorMessage`](#errormessage) keyword can be useful to provide more information about the deprecation and what to use instead.
```

--------------------------------

### Validate File Content with Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Use 'schema' with 'format' as 'file-path' to specify a JSON schema for validating the content of the provided file.

```json
{
  "type": "string",
  "format": "file-path",
  "schema": "assets/foo_schema.json"
}
```

--------------------------------

### Validate File Path Format

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Use the 'format' key with 'file-path' to validate that a string represents a file path, ensuring it's not a directory.

```json
{
  "type": "string",
  "format": "file-path"
}
```

--------------------------------

### Separate FASTQs and BEDs using multiMap

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Use multiMap to split a channel into multiple output channels based on defined attributes. Each input item is mapped to corresponding output channels.

```groovy
Channel.fromList(samplesheetToList(params.input, "path/to/json/schema"))
    .multiMap { meta, fastq_1, fastq_2, bed ->
        fastq: tuple(meta, fastq_1, fastq_2)
        bed:   tuple(meta, bed)
    }
    .set { input }
```

--------------------------------

### Customize Show Hidden Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Changes the parameter used to include hidden parameters in the help message. Defaults to '--showHidden'.

```groovy
validation.help.showHiddenParameter = "showMeThoseHiddenParams" // default: "showHidden"
```

--------------------------------

### Update JSON schema draft and definitions keyword

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

Replace the old JSON schema draft-07 with draft-2020-12 and 'definitions' with '$defs' in your schema files.

```bash
sed -i -e 's/https?::\/\/json-schema.org\/draft-07\/schema/https:\/\/json-schema.org\/draft\/2020-12\/schema/g' -e 's/definitions/\$defs/g' nextflow_schema.json
```

--------------------------------

### Set Default Ignored Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Allows pipeline developers to define a default list of parameters to be ignored, simplifying usage for pipeline users.

```groovy
validation.defaultIgnoreParams = ["param1", "param2"] // default: []
```

--------------------------------

### Customizing Validation Error Messages

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Explains how to use the 'errorMessage' key to provide clearer, user-friendly messages when parameter validation fails, improving the user experience.

```json
"input": {
  "type": "string",
  "pattern": "^\S+\.csv$",
  "errorMessage": "File name must end in '.csv' cannot contain spaces"
}
```

--------------------------------

### View branched WGS and WES channels

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Inspect the channels created by the branch operator. Observe that the WGS and WES channels may contain a different number of items compared to the original channel.

```groovy
input.WGS.view() // Channel has 3 elements: meta, fastq_1, fastq_2
input.WES.view() // Channel has 4 elements: meta, fastq_1, fastq_2, bed
```

--------------------------------

### Show Hidden Parameters in Help

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Enable this option to display parameters annotated with "hidden": true in the help message. Defaults to false.

```groovy
validation.help.showHidden = <true|false> // default: false
```

--------------------------------

### Validate Path Existence

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Use the 'exists' key in conjunction with a 'format' to validate whether a provided path exists on the filesystem (true) or not (false). This is ignored for cloud URIs.

```json
{
  "type": "string",
  "format": "file-path",
  "exists": true
}
```

--------------------------------

### nf-core/rnaseq Sample Sheet Schema

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/sample_sheet_schema_examples.md

Schema for validating sample sheets used with the `--input` parameter in the nf-core/rnaseq pipeline. It defines the structure for an array of sample objects, each requiring a sample name, FASTQ files, and strandedness.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/nf-core/rnaseq/master/assets/schema_input.json",
  "title": "nf-core/rnaseq pipeline - params.input schema",
  "description": "Schema for the file provided with params.input",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "sample": {
        "type": "string",
        "pattern": "^\\S+$",
        "errorMessage": "Sample name must be provided and cannot contain spaces",
        "meta": ["my_sample"]
      },
      "fastq_1": {
        "type": "string",
        "pattern": "^\\S+\\.f(ast)?q\\.gz$",
        "format": "file-path",
        "errorMessage": "FastQ file for reads 1 must be provided, cannot contain spaces and must have extension '.fq.gz' or '.fastq.gz'"
      },
      "fastq_2": {
        "errorMessage": "FastQ file for reads 2 cannot contain spaces and must have extension '.fq.gz' or '.fastq.gz'",
        "type": "string",
        "pattern": "^\\S+\\.f(ast)?q\\.gz$",
        "format": "file-path"
      },
      "strandedness": {
        "type": "string",
        "errorMessage": "Strandedness must be provided and be one of 'forward', 'reverse' or 'unstranded'",
        "enum": ["forward", "reverse", "unstranded"],
        "meta": ["my_strandedness"]
      }
    },
    "required": ["sample", "fastq_1", "strandedness"]
  }
}
```

--------------------------------

### Include and Use nf-schema Functions in main.nf

Source: https://github.com/nextflow-io/nf-schema/blob/master/README.md

Include helper functions from the nf-schema plugin in your Nextflow pipeline. These functions can be used to validate parameters, log parameter summaries, and convert sample sheets to a list of metadata.

```groovy
include { validateParameters; paramsSummaryLog; samplesheetToList } from 'plugin/nf-schema'

// Validate input parameters
validateParameters()

// Print summary of supplied parameters
log.info paramsSummaryLog(workflow)

// Create a new channel of metadata from a sample sheet passed to the pipeline through the --input parameter
ch_input = Channel.fromList(samplesheetToList(params.input, "assets/schema_input.json"))
```

--------------------------------

### Count channel entries by family and add to meta

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Count items in a channel that share a common value (e.g., family ID) and append this count to the meta information of each item. This is useful for subsequent grouping operations.

```groovy
// channel created with samplesheetToList() previous to modification:
// [[id:example1, family:family1], example1.txt]
// [[id:example2, family:family1], example2.txt]
// [[id:example3, family:family2], example3.txt]

params.input = "sample sheet.csv"

Channel.fromList(samplesheetToList(params.input, "path/to/json/schema"))
    .tap { ch_raw }                       // Create a copy of the original channel
    .map { meta, txt -> [ meta.family ] } // Isolate the value to count on
    .reduce([:]) { counts, family ->      // Creates a map like this: [family1:2, family2:1]
        counts[family] = (counts[family] ?: 0) + 1
        counts
    }
    .combine(ch_raw)                     // Add the count map to the original channel
    .map { counts, meta, txt ->          // Add the counts of the current family to the meta
        new_meta = meta + [count:counts[meta.family]]
        [ new_meta, txt ]
    }
    .set { input }

input.view()
// [[id:example1, family:family1, count:2], example1.txt]
// [[id:example2, family:family1, count:2], example2.txt]
// [[id:example3, family:family2, count:1], example3.txt]
```

--------------------------------

### JSON Schema for Samplesheet without Headers

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/examples.md

Defines a JSON schema for a samplesheet that lacks headers, expecting an array of strings. This is used when only one input type is present in the pipeline.

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "description": "Schema for the file provided with params.input",
  "type": "array",
  "items": {
    "type": "string"
  }
}
```

--------------------------------

### Configure Nextflow Plugin Version

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/contributing/setup.md

Specify the nf-schema plugin version to be used in a Nextflow pipeline configuration.

```groovy
plugins {
    id 'nf-schema@x.y.z'
}
```

--------------------------------

### Enable Monochrome Logs

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Disables colored logging output. Automatically set to true if Nextflow's ANSI logging is disabled.

```groovy
validation.monochromeLogs = <true|false> // default: false
```

--------------------------------

### Specify Minimum and Maximum for Numbers

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/nextflow_schema_specification.md

Use 'minimum' and 'maximum' to define the valid range for integer or float numbers. The value must be greater than or equal to 'minimum' and less than or equal to 'maximum'.

```json
{
  "type": "number",
  "minimum": 0,
  "maximum": 100
}
```

--------------------------------

### Ignore Specific Parameters

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/configuration/configuration.md

Specifies a list of parameter names for which validation should be skipped. 'nf_test_output' is ignored by default.

```groovy
validation.ignoreParams = ["param1", "param2"] // default: []
```

--------------------------------

### Feature-Complete Sample Sheet Schema Test Fixture

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/nextflow_schema/sample_sheet_schema_examples.md

A comprehensive JSON Schema used as a test fixture for sample sheet validation within the nf-schema package. It demonstrates a wide range of schema features for validating sample sheet inputs.

```json
--8<-- "src/testResources/schema_input.json"
```

--------------------------------

### Conditional Help Message Display (nf-validation)

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/migration_guide.md

This snippet shows how to conditionally display the help message based on a pipeline parameter in nf-validation. It logs the help message and exits if the 'help' parameter is set.

```groovy
if (params.help) {
    log.info paramsHelp("nextflow run my_pipeline --input input_file.csv")
    exit 0
}
```

--------------------------------

### CSV Sample Sheet Data

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/samplesheets/samplesheetToList.md

The content of a sample CSV file used with samplesheetToList().

```csv
--8<-- "examples/samplesheetToListBasic/samplesheet.csv"
```

--------------------------------

### Disable Monochrome Logs

Source: https://github.com/nextflow-io/nf-schema/blob/master/docs/parameters/help_text.md

By default, help output uses ANSI escape codes for color. To disable this, set `validation.monochromeLogs` to `true` in your Nextflow configuration.

```groovy
validation.monochromeLogs = true
```