Parametervorlagendateien für HealthOmics Workflows

Parametervorlagen definieren die Eingabeparameter für einen Workflow. Sie können Eingabeparameter definieren, um Ihren Workflow flexibler und vielseitiger zu gestalten. Sie können beispielsweise einen Parameter für den Amazon S3 S3-Speicherort der Referenzgenomdateien definieren. Parametervorlagen können über einen Git-basierten Repository-Dienst oder Ihr lokales Laufwerk bereitgestellt werden. Benutzer können den Workflow dann mit verschiedenen Datensätzen ausführen.

Sie können die Parametervorlage für Ihren Workflow oder HealthOmics die Parametervorlage für Sie erstellen.

Die Parametervorlage ist eine JSON-Datei. In der Datei ist jeder Eingabeparameter ein benanntes Objekt, das mit dem Namen der Workflow-Eingabe übereinstimmen muss. Wenn Sie einen Lauf starten und nicht Werte für alle erforderlichen Parameter angeben, schlägt der Lauf fehl.

Das Eingabeparameterobjekt umfasst die folgenden Attribute:

• description— Dieses erforderliche Attribut ist eine Zeichenfolge, die von der Konsole auf der Startrun-Seite angezeigt wird. Diese Beschreibung wird auch als Run-Metadaten gespeichert.

• optional— Dieses optionale Attribut gibt an, ob der Eingabeparameter optional ist. Wenn Sie das optional Feld nicht angeben, ist der Eingabeparameter erforderlich.

Die folgende Beispielparametervorlage zeigt, wie die Eingabeparameter angegeben werden.

{
  "myRequiredParameter1": {
     "description": "this parameter is required",
  },
  "myRequiredParameter2": {
     "description": "this parameter is also required",
     "optional": false
  },
  "myOptionalParameter": {
     "description": "this parameter is optional",
     "optional": true
  }
}   

Generieren von Parametervorlagen

HealthOmics generiert die Parametervorlage, indem die Workflow-Definition analysiert wird, um Eingabeparameter zu ermitteln. Wenn Sie eine Parametervorlagendatei für einen Workflow bereitstellen, überschreiben die Parameter in Ihrer Datei die in der Workflow-Definition erkannten Parameter.

Es gibt geringfügige Unterschiede zwischen der Parsing-Logik der CWL-, WDL- und Nextflow-Engines, wie in den folgenden Abschnitten beschrieben.

Parametererkennung für CWL

In der CWL-Workflow-Engine geht die Parsing-Logik von den folgenden Annahmen aus:

• Alle unterstützten Typen, für die ein Nullwert zulässig ist, sind als optionale Eingabeparameter gekennzeichnet.

• Alle unterstützten Typen, die nicht Null enthalten, werden als erforderliche Eingabeparameter gekennzeichnet.

• Alle Parameter mit Standardwerten sind als optionale Eingabeparameter gekennzeichnet.

• Die Beschreibungen werden aus dem label Abschnitt der main Workflow-Definition extrahiert. Wenn nicht angegeben, label ist die Beschreibung leer (eine leere Zeichenfolge).

Die folgenden Tabellen zeigen Beispiele für die CWL-Interpolation. Für jedes Beispiel lautet der Parametername. x Wenn der Parameter erforderlich ist, müssen Sie einen Wert für den Parameter angeben. Wenn der Parameter optional ist, müssen Sie keinen Wert angeben.

Diese Tabelle zeigt Beispiele für die CWL-Interpolation für primitive Typen.

Eingabe	Beispiel für Eingabe/Ausgabe	Erforderlich
x: type: int	1 oder 2 oder...	Ja
x: type: int default: 2	Der Standardwert ist 2. Gültige Eingabe ist 1 oder 2 oder...	Nein
x: type: int?	Gültige Eingabe ist Keine oder 1 oder 2 oder...	Nein
x: type: int? default: 2	Der Standardwert ist 2. Gültige Eingabe ist Keine oder 1 oder 2 oder...	Nein

Die folgende Tabelle enthält Beispiele für die CWL-Interpolation für komplexe Typen. Ein komplexer Typ ist eine Sammlung primitiver Typen.

Eingabe	Beispiel für Eingabe/Ausgabe	Erforderlich
x: type: array items: int	[] oder [1,2,3]	Ja
x: type: array? items: int	Keiner oder [] oder [1,2,3]	Nein
x: type: array items: int?	[] oder [Keine, 3, Keine]	Ja
x: type: array? items: int?	[Keine] oder Keine oder [1,2,3] oder [Keine, 3] aber nicht []	Nein

Parametererkennung für WDL

In der WDL-Workflow-Engine geht die Parsing-Logik von den folgenden Annahmen aus:

• Alle unterstützten Typen, für die NULL-Werte zulässig sind, sind als optionale Eingabeparameter gekennzeichnet.

• Für unterstützte Typen, die keine NULL-Werte zulassen:

  • Jede Eingabevariable mit der Zuweisung von Literalen oder Ausdrücken ist als optionale Parameter gekennzeichnet. Zum Beispiel:

     Int x = 2 
    Float f0 = 1.0 + f1

  • Wenn den Eingabeparametern keine Werte oder Ausdrücke zugewiesen wurden, werden sie als erforderliche Parameter markiert.

• Beschreibungen werden aus parameter_meta der main Workflow-Definition extrahiert. Wenn nicht angegeben, parameter_meta ist die Beschreibung leer (eine leere Zeichenfolge). Weitere Informationen finden Sie in der WDL-Spezifikation für Parameter-Metadaten.

Die folgenden Tabellen enthalten Beispiele für WDL-Interpolation. Für jedes Beispiel lautet der Parametername. x Wenn der Parameter erforderlich ist, müssen Sie einen Wert für den Parameter angeben. Wenn der Parameter optional ist, müssen Sie keinen Wert angeben.

Diese Tabelle zeigt Beispiele für WDL-Interpolation für primitive Typen.

Eingabe	Beispiel für Eingabe/Ausgabe	Erforderlich
Ganzzahl x	1 oder 2 oder...	Ja
Int x = 2	2	Nein
Ganzzahl x = 1+2	3	Nein
Ganzzahl x = y+z	y+z	Nein
Int? x	Keiner oder 1 oder 2 oder...	Ja
Int? x = 2	Keiner oder 2	Nein
Int? x = 1+2	Keiner oder 3	Nein
Int? x = y+z	Keiner oder y+z	Nein

Die folgende Tabelle zeigt Beispiele für die WDL-Interpolation für komplexe Typen. Ein komplexer Typ ist eine Sammlung primitiver Typen.

Eingabe	Beispiel für Eingabe/Ausgabe	Erforderlich
Array [Int] x	[1,2,3] oder []	Ja
Reihe [Int] + x	[1], aber nicht []	Ja
Array [Int]? x	Keiner oder [] oder [1,2,3]	Nein
Array [Int?] x	[] oder [Keine, 3, Keine]	Ja
Array [Int?] =? x	[Keine] oder Keine oder [1,2,3] oder [Keine, 3] aber nicht []	Nein
Strukturbeispiel {Zeichenfolge a, Int y} später in den Eingaben: Beispiel mySample	String a = mySample.a Int y = mySample.y	Ja
Strukturbeispiel {Zeichenfolge a, Int y} später in den Eingaben: Beispiel? Meine Probe	if (defined(mySample)) { String a = mySample.a Int y = mySample.y }	Nein

Parametererkennung für Nextflow

HealthOmics Generiert für Nextflow die Parametervorlage durch Analysieren der Datei. nextflow_schema.json Wenn die Workflow-Definition keine Schemadatei enthält, wird die Haupt-Workflow-Definitionsdatei HealthOmics analysiert.

Themen

• Analysieren der Schemadatei

• Analysieren der Hauptdatei

• Verschachtelte Parameter

• Beispiele für Nextflow-Interpolation

Analysieren der Schemadatei

Damit das Parsen korrekt funktioniert, stellen Sie sicher, dass die Schemadatei die folgenden Anforderungen erfüllt:

• Die Schemadatei hat einen Namen nextflow_schema.json und befindet sich in demselben Verzeichnis wie die Haupt-Workflow-Datei.

• Die Schemadatei ist gültiges JSON, wie in einem der folgenden Schemas definiert:

  • Json-Schema. org/draft/2020-12/schema.

  • Json-Schema. org/draft-07/schema.

HealthOmics analysiert die nextflow_schema.json Datei, um die Parametervorlage zu generieren:

• Extrahiert allesproperties, was im Schema definiert ist.

• Schließt die Eigenschaft eindescription, sofern sie für die Eigenschaft verfügbar ist.

• Identifiziert, ob jeder Parameter optional oder erforderlich ist, basierend auf dem required Feld der Eigenschaft.

Das folgende Beispiel zeigt eine Definitionsdatei und die generierte Parameterdatei.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "$defs": {
        "input_options": {
            "title": "Input options",
            "type": "object",
            "required": ["input_file"],
            "properties": {
                "input_file": {
                    "type": "string",
                    "format": "file-path",
                    "pattern": "^s3://[a-z0-9.-]{3,63}(?:/\\S*)?$",
                    "description": "description for input_file"
                },
                "input_num": {
                    "type": "integer",
                    "default": 42,
                    "description": "description for input_num"
                }
            }
        },
        "output_options": {
            "title": "Output options",
            "type": "object",
            "required": ["output_dir"],
            "properties": {
                "output_dir": {
                    "type": "string",
                    "format": "file-path",
                    "description": "description for output_dir",
                }
            }
        }
    },
    "properties": {
        "ungrouped_input_bool": {
            "type": "boolean",
            "default": true
        }
    },
    "required": ["ungrouped_input_bool"],
    "allOf": [
        { "$ref": "#/$defs/input_options" },
        { "$ref": "#/$defs/output_options" }
    ]
}       

Die generierte Parametervorlage:

{
    "input_file": {
        "description": "description for input_file",
        "optional": False
    },
    "input_num": {
        "description": "description for input_num",
        "optional": True
    },
    "output_dir": {
        "description": "description for output_dir",
        "optional": False
    },
    "ungrouped_input_bool": {
        "description": None,
        "optional": False
    }
}       

Analysieren der Hauptdatei

Wenn die Workflow-Definition keine nextflow_schema.json Datei enthält, wird die Haupt-Workflow-Definitionsdatei HealthOmics analysiert.

HealthOmics analysiert die params Ausdrücke, die in der Workflow-Definitionsdatei und in der nextflow.config Datei gefunden wurden. Alle params mit Standardwerten sind als optional gekennzeichnet.

Beachten Sie die folgenden Anforderungen, damit das Parsen korrekt funktioniert:

• HealthOmics analysiert nur die Haupt-Workflow-Definitionsdatei. Um sicherzustellen, dass alle Parameter erfasst werden, empfehlen wir, eine Verbindung zu allen params Untermodulen und importierten Workflows herzustellen.

• Die Konfigurationsdatei ist optional. Wenn Sie eine definieren, geben Sie ihr einen Namen nextflow.config und platzieren Sie sie im selben Verzeichnis wie die Haupt-Workflow-Definitionsdatei.

Das folgende Beispiel zeigt eine Definitionsdatei und die generierte Parametervorlage.

params.input_file = "default.txt"
params.threads = 4
params.memory = "8GB"

workflow {
    if (params.version) {
        println "Using version: ${params.version}"
    }
}

Die generierte Parametervorlage:

{
    "input_file": {
        "description": None,
        "optional": True
    },
    "threads": {
        "description": None,
        "optional": True
    },
    "memory": {
        "description": None,
        "optional": True
    },
    "version": {
        "description": None,
        "optional": False
    }
}

HealthOmics Sammelt bei Standardwerten, die in nextflow.config definiert sind, params Zuweisungen und Parameter, die darin deklariert sindparams {}, wie im folgenden Beispiel gezeigt. paramsMuss in Zuweisungsanweisungen auf der linken Seite der Anweisung stehen.

params.alpha = "alpha"
params.beta = "beta"

params {
    gamma = "gamma"
    delta = "delta"
}

env {
   // ignored, as this assignment isn't in the params block
   VERSION = "TEST"  
}

// ignored, as params is not on the left side
interpolated_image = "${params.cli_image}" 

Die generierte Parametervorlage:

{
    // other params in your main workflow defintion
    "alpha": {
        "description": None,
        "optional": True
    },
    "beta": {
        "description": None,
        "optional": True
    },
    "gamma": {
        "description": None,
        "optional": True
    },
    "delta": {
        "description": None,
        "optional": True
    }
}

Verschachtelte Parameter

Beides nextflow_schema.json und nextflow.config erlaubt verschachtelte Parameter. Für die HealthOmics Parametervorlage sind jedoch nur die Parameter der obersten Ebene erforderlich. Wenn Ihr Workflow einen verschachtelten Parameter verwendet, müssen Sie ein JSON-Objekt als Eingabe für diesen Parameter angeben.

Verschachtelte Parameter in Schemadateien

HealthOmics überspringt verschachtelte Elemente params beim Parsen einer Datei. nextflow_schema.json Wenn Sie beispielsweise die folgende Datei definieren: nextflow_schema.json

{
    "properties": {
        "input": {
            "properties": {
                "input_file": { ... },
                "input_num": { ... }
            }
        },
        "input_bool": { ... }
    }
}

HealthOmics ignoriert input_file und input_num wenn es die Parametervorlage generiert:

{
    "input": {
        "description": None,
        "optional": True
    },
    "input_bool": {
        "description": None,
        "optional": True
    }
}

Wenn Sie diesen Workflow ausführen, HealthOmics erwartet eine input.json Datei, die der folgenden ähnelt:

{
   "input": {
       "input_file": "s3://bucket/obj",
       "input_num": 2
   },
   "input_bool": false
}

Verschachtelte Parameter in Konfigurationsdateien

HealthOmics sammelt keine params in einer nextflow.config Datei verschachtelten Dateien und überspringt sie beim Parsen. Wenn Sie beispielsweise die folgende Datei definieren: nextflow.config

params.alpha = "alpha"
  params.nested.beta = "beta"
  
  params {
      gamma = "gamma"
      group {
          delta = "delta"
      }
  }        

HealthOmics ignoriert params.nested.beta und params.group.delta wenn es die Parametervorlage generiert:

{
    "alpha": {
        "description": None,
        "optional": True
    },
    "gamma": {
        "description": None,
        "optional": True
    }
}

Beispiele für Nextflow-Interpolation

Die folgende Tabelle zeigt Beispiele für die Nextflow-Interpolation für Parameter in der Hauptdatei.

Parameter	Erforderlich
params.input_file	Ja
params.input_file = "s3://bucket/data.json“	Nein
params.nested.input_file	N/A
params.nested.input_file = "s3://bucket/data.json“	N/A

Die folgende Tabelle zeigt Beispiele für die Nextflow-Interpolation für Parameter in der Datei. nextflow.config

Parameter	Erforderlich
params.input_file = "s3://bucket/data.json"	Nein
params { input_file = "s3://bucket/data.json" }	Nein
params { nested { input_file = "s3://bucket/data.json" } }	N/A
input_file = params.input_file	N/A