Arquivos de modelo de parâmetros para HealthOmics fluxos de trabalho

Os modelos de parâmetros definem os parâmetros de entrada para um fluxo de trabalho. Você pode definir parâmetros de entrada para tornar seu fluxo de trabalho mais flexível e versátil. Por exemplo, você pode definir um parâmetro para a localização dos arquivos do genoma de referência no Amazon S3. Os modelos de parâmetros podem ser fornecidos por meio de um serviço de repositório baseado em Git ou de sua unidade local. Os usuários podem então executar o fluxo de trabalho usando vários conjuntos de dados.

Você pode criar o modelo de parâmetro para seu fluxo de trabalho ou HealthOmics gerar o modelo de parâmetro para você.

O modelo de parâmetro é um arquivo JSON. No arquivo, cada parâmetro de entrada é um objeto nomeado que deve corresponder ao nome da entrada do fluxo de trabalho. Ao iniciar uma execução, se você não fornecer valores para todos os parâmetros necessários, a execução falhará.

O objeto do parâmetro de entrada inclui os seguintes atributos:

• description— Esse atributo obrigatório é uma string que o console exibe na página Iniciar execução. Essa descrição também é mantida como metadados de execução.

• optional— Esse atributo opcional indica se o parâmetro de entrada é opcional. Se você não especificar o optional campo, o parâmetro de entrada será obrigatório.

O exemplo de modelo de parâmetro a seguir mostra como especificar os parâmetros de entrada.

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

Geração de modelos de parâmetros

HealthOmics gera o modelo de parâmetros analisando a definição do fluxo de trabalho para detectar os parâmetros de entrada. Se você fornecer um arquivo de modelo de parâmetros para um fluxo de trabalho, os parâmetros em seu arquivo substituirão os parâmetros detectados na definição do fluxo de trabalho.

Há pequenas diferenças entre a lógica de análise dos mecanismos CWL, WDL e Nextflow, conforme descrito nas seções a seguir.

Detecção de parâmetros para CWL

No mecanismo de fluxo de trabalho da CWL, a lógica de análise faz as seguintes suposições:

• Todos os tipos anuláveis suportados são marcados como parâmetros de entrada opcionais.

• Todos os tipos não nulos suportados são marcados como parâmetros de entrada obrigatórios.

• Todos os parâmetros com valores padrão são marcados como parâmetros de entrada opcionais.

• As descrições são extraídas da label seção da definição do main fluxo de trabalho. Se não label for especificado, a descrição ficará em branco (uma string vazia).

As tabelas a seguir mostram exemplos de interpolação de CWL. Para cada exemplo, o nome do parâmetro éx. Se o parâmetro for necessário, você deverá fornecer um valor para o parâmetro. Se o parâmetro for opcional, você não precisará fornecer um valor.

Esta tabela mostra exemplos de interpolação CWL para tipos primitivos.

Entrada	Exemplo de entrada/saída	Obrigatório
x: type: int	1 ou 2 ou...	Sim
x: type: int default: 2	O valor padrão é 2. A entrada válida é 1 ou 2 ou...	Não
x: type: int?	A entrada válida é Nenhuma ou 1 ou 2 ou...	Não
x: type: int? default: 2	O valor padrão é 2. A entrada válida é Nenhuma ou 1 ou 2 ou...	Não

A tabela a seguir mostra exemplos de interpolação CWL para tipos complexos. Um tipo complexo é uma coleção de tipos primitivos.

Entrada	Exemplo de entrada/saída	Obrigatório
x: type: array items: int	[] ou [1,2,3]	Sim
x: type: array? items: int	Nenhum ou [] ou [1,2,3]	Não
x: type: array items: int?	[] ou [Nenhum, 3, Nenhum]	Sim
x: type: array? items: int?	[Nenhum] ou Nenhum ou [1,2,3] ou [Nenhum, 3] mas não []	Não

Detecção de parâmetros para WDL

No mecanismo de fluxo de trabalho da WDL, a lógica de análise faz as seguintes suposições:

• Todos os tipos anuláveis suportados são marcados como parâmetros de entrada opcionais.

• Para tipos suportados não anuláveis:

  • Qualquer variável de entrada com atribuição de literais ou expressão é marcada como parâmetros opcionais. Por exemplo:

     Int x = 2 
    Float f0 = 1.0 + f1

  • Se nenhum valor ou expressão tiver sido atribuído aos parâmetros de entrada, eles serão marcados como parâmetros obrigatórios.

• As descrições são extraídas da definição parameter_meta do main fluxo de trabalho. Se não parameter_meta for especificado, a descrição ficará em branco (uma string vazia). Para obter mais informações, consulte a especificação WDL para metadados de parâmetros.

As tabelas a seguir mostram exemplos de interpolação de WDL. Para cada exemplo, o nome do parâmetro éx. Se o parâmetro for necessário, você deverá fornecer um valor para o parâmetro. Se o parâmetro for opcional, você não precisará fornecer um valor.

Esta tabela mostra exemplos de interpolação de WDL para tipos primitivos.

Entrada	Exemplo de entrada/saída	Obrigatório
Int x	1 ou 2 ou...	Sim
Int x = 2	2	Não
Int x = 1+2	3	Não
Int x = y+z	y+z	Não
Int? x	Nenhum ou 1 ou 2 ou...	Sim
Int? x = 2	Nenhum ou 2	Não
Int? x = 1+2	Nenhum ou 3	Não
Int? x = y+z	Nenhum ou y+z	Não

A tabela a seguir mostra exemplos de interpolação de WDL para tipos complexos. Um tipo complexo é uma coleção de tipos primitivos.

Entrada	Exemplo de entrada/saída	Obrigatório
Matriz [Int] x	[1,2,3] ou []	Sim
Matriz [Int] + x	[1], mas não []	Sim
Matriz [Int]? x	Nenhum ou [] ou [1,2,3]	Não
Matriz [Int?] x	[] ou [Nenhum, 3, Nenhum]	Sim
Matriz [Int?] =? x	[Nenhum] ou Nenhum ou [1,2,3] ou [Nenhum, 3] mas não []	Não
Amostra de estrutura {String a, Int y} posteriormente nas entradas: Sample MySample	String a = mySample.a Int y = mySample.y	Sim
Amostra de estrutura {String a, Int y} posteriormente nas entradas: Amostra? Minha amostra	if (defined(mySample)) { String a = mySample.a Int y = mySample.y }	Não

Detecção de parâmetros para Nextflow

Para o Nextflow, HealthOmics gera o modelo de parâmetro analisando o arquivo. nextflow_schema.json Se a definição do fluxo de trabalho não incluir um arquivo de esquema, HealthOmics analisará o arquivo principal de definição do fluxo de trabalho.

Tópicos

• Analisando o arquivo do esquema

• Analisando o arquivo principal

• Parâmetros aninhados

• Exemplos de interpolação Nextflow

Analisando o arquivo do esquema

Para que a análise funcione corretamente, verifique se o arquivo do esquema atende aos seguintes requisitos:

• O arquivo do esquema tem um nome nextflow_schema.json e está localizado no mesmo diretório do arquivo do fluxo de trabalho principal.

• O arquivo do esquema é um JSON válido, conforme definido em um dos seguintes esquemas:

  • esquema json. org/draft/2020-12/schema.

  • esquema json. org/draft-07/schema.

HealthOmics analisa o nextflow_schema.json arquivo para gerar o modelo de parâmetro:

• Extrai tudo properties o que está definido no esquema.

• Inclui a propriedade, description se disponível para a propriedade.

• Identifica se cada parâmetro é opcional ou obrigatório, com base no required campo da propriedade.

O exemplo a seguir mostra um arquivo de definição e o arquivo de parâmetros gerado.

{
    "$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" }
    ]
}       

O modelo de parâmetro gerado:

{
    "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
    }
}       

Analisando o arquivo principal

Se a definição do fluxo de trabalho não incluir um nextflow_schema.json arquivo, HealthOmics analisará o arquivo principal de definição do fluxo de trabalho.

HealthOmics analisa as params expressões encontradas no arquivo principal de definição do fluxo de trabalho e no nextflow.config arquivo. Todos params com valores padrão são marcados como opcionais.

Para que a análise funcione corretamente, observe os seguintes requisitos:

• HealthOmics analisa somente o arquivo de definição do fluxo de trabalho principal. Para garantir que todos os parâmetros sejam capturados, recomendamos que você conecte tudo a todos params os submódulos e fluxos de trabalho importados.

• O arquivo de configuração é opcional. Se você definir um, nomeie-o nextflow.config e coloque-o no mesmo diretório do arquivo principal de definição do fluxo de trabalho.

O exemplo a seguir mostra um arquivo de definição e o modelo de parâmetro gerado.

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

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

O modelo de parâmetro gerado:

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

Para valores padrão definidos em nextflow.config, HealthOmics coleta params atribuições e parâmetros declarados em, conforme mostrado no params {} exemplo a seguir. Nas declarações de atribuição, params devem aparecer no lado esquerdo da declaração.

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}" 

O modelo de parâmetro gerado:

{
    // 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
    }
}

Parâmetros aninhados

Ambos nextflow_schema.json e nextflow.config permitem parâmetros aninhados. No entanto, o modelo de HealthOmics parâmetros requer somente os parâmetros de nível superior. Se seu fluxo de trabalho usa um parâmetro aninhado, você deve fornecer um objeto JSON como entrada para esse parâmetro.

Parâmetros aninhados em arquivos de esquema

HealthOmics pula aninhado params ao analisar um arquivo. nextflow_schema.json Por exemplo, se você definir o seguinte nextflow_schema.json arquivo:

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

HealthOmics ignora input_file e input_num quando gera o modelo de parâmetro:

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

Quando você executa esse fluxo de trabalho, HealthOmics espera um input.json arquivo semelhante ao seguinte:

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

Parâmetros aninhados em arquivos de configuração

HealthOmics não coleta aninhados params em um nextflow.config arquivo e os ignora durante a análise. Por exemplo, se você definir o seguinte nextflow.config arquivo:

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

HealthOmics ignora params.nested.beta e params.group.delta quando gera o modelo de parâmetro:

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

Exemplos de interpolação Nextflow

A tabela a seguir mostra exemplos de interpolação do Nextflow para parâmetros no arquivo principal.

Parâmetros	Obrigatório
params.input_file	Sim
params.input_file = "s3://bucket/data.json”	Não
params.nested.input_file	N/D
params.nested.input_file = "s3://bucket/data.json”	N/D

A tabela a seguir mostra exemplos de interpolação do Nextflow para parâmetros no arquivo. nextflow.config

Parâmetros	Obrigatório
params.input_file = "s3://bucket/data.json"	Não
params { input_file = "s3://bucket/data.json" }	Não
params { nested { input_file = "s3://bucket/data.json" } }	N/D
input_file = params.input_file	N/D