nextflow_schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/cellgeni/nf-autoannotate/nextflow_schema.json",
  "title": "nf-autoannotate pipeline parameters",
  "description": "Parameter schema for nf-autoannotate. Use with Nextflow -params-file YAML files.",
  "type": "object",
  "allOf": [
    {
      "$ref": "#/$defs/tool_selection_options"
    },
    {
      "$ref": "#/$defs/input_output_options"
    },
    {
      "$ref": "#/$defs/reference_filtering_options"
    },
    {
      "$ref": "#/$defs/model_reuse_options"
    },
    {
      "$ref": "#/$defs/scanvi_options"
    },
    {
      "$ref": "#/$defs/celltypist_options"
    },
    {
      "$ref": "#/$defs/panhumanpy_options"
    },
    {
      "$ref": "#/$defs/merge_output_options"
    }
  ],
  "$defs": {
    "tool_selection_options": {
      "title": "Tool selection options",
      "type": "object",
      "fa_icon": "fas fa-list-check",
      "required": [
        "tools"
      ],
      "properties": {
        "tools": {
          "type": [
            "string",
            "array"
          ],
          "description": "Annotation tools to run, as a comma-separated string or a YAML list. Any subset of celltypist, scanvi, panhumanpy.",
          "pattern": "^\\s*(celltypist|scanvi|panhumanpy)\\s*(,\\s*(celltypist|scanvi|panhumanpy)\\s*)*$",
          "items": {
            "type": "string",
            "enum": [
              "celltypist",
              "scanvi",
              "panhumanpy"
            ]
          },
          "minItems": 1
        }
      }
    },
    "input_output_options": {
      "title": "Input and output options",
      "type": "object",
      "fa_icon": "fas fa-file",
      "required": [
        "project_tag"
      ],
      "properties": {
        "ref_h5ad": {
          "type": [
            "string",
            "null"
          ],
          "description": "Reference AnnData .h5ad file. Required when tools includes celltypist or scanvi.",
          "format": "file-path",
          "exists": true
        },
        "query_h5ad": {
          "type": [
            "string",
            "array"
          ],
          "description": "Query AnnData .h5ad file(s) to annotate. Accepts a path, a glob, or a list of either. Each file is annotated separately, with the sample ID taken from the filename without its extension. Existence is checked when the workflow starts rather than during schema validation, because a glob has no single path to check.",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1,
          "minLength": 1
        },
        "project_tag": {
          "type": "string",
          "description": "Short tag used in output filenames and report directory names.",
          "minLength": 1,
          "pattern": "^[A-Za-z0-9._-]+$"
        },
        "outdir": {
          "type": [
            "string",
            "null"
          ],
          "description": "Output directory. If unset, autoannotate-results-<project_tag> is used.",
          "format": "directory-path"
        },
        "ref_label_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "Reference obs column containing cell type labels. Required when tools includes celltypist or scanvi."
        },
        "model_sheet": {
          "type": [
            "string",
            "null"
          ],
          "description": "CSV or TSV with one (model, query) pair per row, read only by the ANNOTATE_WITH_MODELS entry point. Columns: tool, model, query_h5ad, and optionally model_id. A tab in the header selects TSV parsing.",
          "format": "file-path",
          "exists": true
        }
      }
    },
    "reference_filtering_options": {
      "title": "Reference filtering options",
      "type": "object",
      "fa_icon": "fas fa-filter",
      "properties": {
        "ref_filter_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "Reference obs column used to filter reference cells before training."
        },
        "ref_filter_values": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated values to keep from ref_filter_col."
        }
      }
    },
    "model_reuse_options": {
      "title": "Model reuse options",
      "type": "object",
      "fa_icon": "fas fa-box-archive",
      "properties": {
        "celltypist_model": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional pretrained CellTypist model path.",
          "format": "file-path",
          "exists": true
        },
        "scanvi_model_dir": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional pretrained scANVI model directory.",
          "format": "directory-path",
          "exists": true
        },
        "scvi_reference_model_dir": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional pretrained scVI reference model directory used to initialize scANVI.",
          "format": "directory-path",
          "exists": true
        }
      }
    },
    "scanvi_options": {
      "title": "scVI/scANVI options",
      "type": "object",
      "fa_icon": "fas fa-network-wired",
      "properties": {
        "batch_key": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional obs column for scVI batch correction."
        },
        "scvi_layer": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional AnnData layer passed to SCVI.setup_anndata."
        },
        "scanvi_categorical_covariate_keys": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated categorical covariate obs columns."
        },
        "scanvi_continuous_covariate_keys": {
          "type": [
            "string",
            "null"
          ],
          "description": "Comma-separated continuous covariate obs columns."
        },
        "scanvi_hvg_n_top_genes": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of HVGs for scVI/scANVI training. Use 0 to keep all shared genes.",
          "minimum": 0,
          "default": 2500
        },
        "nf_scvi_metrics_config": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional nf-scVI-metrics-style Python config.py. Use this as a compatibility mode instead of adding the Python file path to the YAML params file. Takes precedence over individual scVI/scANVI params.",
          "format": "file-path",
          "exists": true
        },
        "unknown_label": {
          "type": [
            "string",
            "null"
          ],
          "description": "Unlabeled category used by scANVI.",
          "minLength": 1,
          "default": "Unknown"
        },
        "scvi_n_hidden": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI n_hidden model parameter.",
          "minimum": 1
        },
        "scvi_n_latent": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI n_latent model parameter.",
          "minimum": 1
        },
        "scvi_n_layers": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI n_layers model parameter.",
          "minimum": 1
        },
        "scvi_dropout_rate": {
          "type": [
            "number",
            "null"
          ],
          "description": "SCVI dropout_rate model parameter.",
          "minimum": 0,
          "maximum": 1
        },
        "scvi_dispersion": {
          "type": [
            "string",
            "null"
          ],
          "description": "SCVI dispersion model parameter."
        },
        "scvi_gene_likelihood": {
          "type": [
            "string",
            "null"
          ],
          "description": "SCVI gene_likelihood model parameter."
        },
        "scvi_latent_distribution": {
          "type": [
            "string",
            "null"
          ],
          "description": "SCVI latent_distribution model parameter."
        },
        "scvi_train_max_epochs": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI.train max_epochs.",
          "minimum": 1
        },
        "scvi_train_batch_size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI.train batch_size.",
          "minimum": 1
        },
        "scvi_train_train_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "SCVI.train train_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scvi_train_validation_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "SCVI.train validation_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scvi_train_early_stopping": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "SCVI.train early_stopping."
        },
        "scvi_train_early_stopping_patience": {
          "type": [
            "integer",
            "null"
          ],
          "description": "SCVI.train early_stopping_patience.",
          "minimum": 1
        },
        "scanvi_train_max_epochs": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Reference SCANVI.train max_epochs.",
          "minimum": 1
        },
        "scanvi_train_batch_size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Reference SCANVI.train batch_size.",
          "minimum": 1
        },
        "scanvi_train_train_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "Reference SCANVI.train train_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scanvi_train_validation_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "Reference SCANVI.train validation_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scanvi_train_early_stopping": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Reference SCANVI.train early_stopping."
        },
        "scanvi_train_early_stopping_patience": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Reference SCANVI.train early_stopping_patience.",
          "minimum": 1
        },
        "scanvi_query_max_epochs": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Query-mapping SCANVI.train max_epochs.",
          "minimum": 1,
          "default": 100
        },
        "scanvi_query_batch_size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Query-mapping SCANVI.train batch_size.",
          "minimum": 1
        },
        "scanvi_query_train_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "Query-mapping SCANVI.train train_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scanvi_query_validation_size": {
          "type": [
            "number",
            "null"
          ],
          "description": "Query-mapping SCANVI.train validation_size.",
          "minimum": 0,
          "maximum": 1
        },
        "scanvi_query_early_stopping": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Query-mapping SCANVI.train early_stopping."
        },
        "scanvi_query_early_stopping_patience": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Query-mapping SCANVI.train early_stopping_patience.",
          "minimum": 1
        },
        "scanvi_query_check_val_every_n_epoch": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Query-mapping SCANVI.train check_val_every_n_epoch.",
          "minimum": 1,
          "default": 10
        },
        "scanvi_query_plan_weight_decay": {
          "type": [
            "number",
            "null"
          ],
          "description": "Query-mapping SCANVI.train plan weight decay.",
          "minimum": 0,
          "default": 0.0
        }
      }
    },
    "celltypist_options": {
      "title": "CellTypist options",
      "type": "object",
      "fa_icon": "fas fa-tags",
      "properties": {
        "celltypist_training_mode": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "standard",
            "detailed",
            null
          ],
          "default": "detailed",
          "description": "CellTypist training mode."
        },
        "celltypist_balance_cells_per_label": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Maximum reference cells per label in detailed mode.",
          "minimum": 1,
          "default": 500
        },
        "celltypist_feature_selection": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Run feature selection before final CellTypist fitting.",
          "default": true
        },
        "celltypist_feature_selection_top_genes": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Top genes per label during CellTypist feature selection.",
          "minimum": 1,
          "default": 100
        },
        "celltypist_feature_selection_max_iter": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Quick SGD iterations for feature selection.",
          "minimum": 1,
          "default": 5
        },
        "celltypist_max_iter": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Final CellTypist model fitting iterations.",
          "minimum": 1,
          "default": 100
        },
        "celltypist_use_gpu": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Train CellTypist models on a GPU. Set false to train on CPU. Annotation always runs on CPU.",
          "default": true
        },
        "celltypist_min_model_gene_overlap": {
          "type": [
            "number",
            "null"
          ],
          "description": "Minimum fraction of the CellTypist model's genes that must be present in the query. Below it, annotation fails. Missing genes are zero-filled, so lowering it trades prediction quality for being able to annotate at all.",
          "minimum": 0,
          "maximum": 1,
          "default": 0.8
        }
      }
    },
    "panhumanpy_options": {
      "title": "PanHumanPy options",
      "type": "object",
      "fa_icon": "fas fa-dna",
      "properties": {
        "panhumanpy_feature_names_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "Optional query var column containing gene symbols for PanHumanPy."
        }
      }
    },
    "merge_output_options": {
      "title": "Merge and output options",
      "type": "object",
      "fa_icon": "fas fa-table",
      "properties": {
        "scanvi_obs_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "scANVI label column name written to output obs.",
          "default": "scanvi_label"
        },
        "scanvi_score_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "scANVI confidence column name written to output obs.",
          "default": "scanvi_confidence"
        },
        "query_cluster_col": {
          "type": [
            "string",
            "null"
          ],
          "description": "Query obs cluster column used for summaries and marker genes.",
          "default": "leiden"
        },
        "compute_missing_clusters": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Compute Leiden clusters if query_cluster_col is absent.",
          "default": false
        },
        "merge_annotations": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Merge per-tool predictions into the query h5ad and write the cluster summary and marker genes. Unset defaults to true for the default workflow and false for ANNOTATE_WITH_MODELS, where each pair runs a single tool. Set false to publish the per-tool prediction tables alone, which skips the most expensive step of a run."
        },
        "marker_genes_n_top": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of marker genes to report per cluster.",
          "minimum": 1,
          "default": 50
        },
        "marker_genes_method": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "wilcoxon",
            "t-test",
            null
          ],
          "default": "wilcoxon",
          "description": "Differential expression test for marker ranking."
        },
        "marker_dotplot": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Write a marker-gene dotplot PNG.",
          "default": true
        },
        "marker_dotplot_n_top": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Number of ranked marker genes per cluster in the dotplot.",
          "minimum": 1,
          "default": 5
        }
      }
    }
  }
}