name: "samtools_view"
namespace: "samtools"
version: "main"
authors:
- name: "Emma Rousseau"
  roles:
  - "author"
  - "maintainer"
  info:
    links:
      github: "emmarousseau"
      linkedin: "emmarousseau1"
argument_groups:
- name: "Inputs"
  arguments:
  - type: "file"
    name: "--input"
    description: "Input SAM, BAM, or CRAM file."
    info: null
    must_exist: true
    create_parent: true
    required: true
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--fai_reference"
    alternatives:
    - "-t"
    description: "A tab-delimited FILE. Each line must contain the reference name\
      \ in the first column\nand the length of the reference in the second column,\
      \ with one line for each distinct\nreference. Any additional fields beyond the\
      \ second column are ignored. This file also\ndefines the order of the reference\
      \ sequences in sorting. If you run: `samtools faidx <ref.fa>',\nthe resulting\
      \ index file <ref.fa>.fai can be used as this FILE.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--reference"
    alternatives:
    - "-T"
    description: "A FASTA format reference FILE, optionally compressed by bgzip and\
      \ ideally indexed by samtools faidx.\nIf an index is not present one will be\
      \ generated for you, if the reference file is local.\nIf the reference file\
      \ is not local, but is accessed instead via an https://, s3:// or other URL,\n\
      the index file will need to be supplied by the server alongside the reference.\
      \ It is possible to\nhave the reference and index files in different locations\
      \ by supplying both to this option separated\nby the string \"##idx##\", for\
      \ example:\n--reference ftp://x.com/ref.fa##idx##ftp://y.com/index.fa.fai\n\
      However, note that only the location of the reference will be stored in the\
      \ output file header.\nIf this method is used to make CRAM files, the cram reader\
      \ may not be able to find the index,\nand may not be able to decode the file\
      \ unless it can get the references it needs using a different\nmethod.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--target_file"
    alternatives:
    - "-L"
    description: "Only output alignments overlapping the input BED FILE [null].\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--region_file"
    description: "Use an index and multi-region iterator to only output alignments\
      \ overlapping the input BED FILE.\nEquivalent to --use_index --target_file FILE.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--qname_file"
    alternatives:
    - "-N"
    description: "Output only alignments with read names listed in FILE. If FILE starts\
      \ with ^ then the operation is\nnegated and only outputs alignment with read\
      \ groups not listed in FILE. It is not permissible to mix\nboth the filter-in\
      \ and filter-out style syntax in the same command.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--read_group_file"
    alternatives:
    - "-R"
    description: "Output alignments in read groups listed in FILE [null]. If FILE\
      \ starts with ^ then the operation is\nnegated and only outputs alignment with\
      \ read names not listed in FILE. It is not permissible to mix\nboth the filter-in\
      \ and filter-out style syntax in the same command. Note that records with no\
      \ RG tag\nwill also be output when using this option. This behaviour may change\
      \ in a future release.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--use_index"
    alternatives:
    - "-M"
    description: "Use the multi-region iterator on the union of a BED file and command-line\
      \ region arguments.\nThis avoids re-reading the same regions of files so can\
      \ sometimes be much faster. Note this also\nremoves duplicate sequences. Without\
      \ this a sequence that overlaps multiple regions specified on\nthe command line\
      \ will be reported multiple times. The usage of a BED file is optional and its\
      \ path\nhas to be preceded by --target_file option.\n"
    info: null
    direction: "input"
- name: "Outputs"
  arguments:
  - type: "file"
    name: "--output"
    alternatives:
    - "-o"
    description: "Output to FILE instead of [stdout]."
    info: null
    example:
    - "output.bam"
    must_exist: true
    create_parent: true
    required: true
    direction: "output"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--bam"
    alternatives:
    - "-b"
    description: "Output in the BAM format."
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--cram"
    alternatives:
    - "-C"
    description: "Output in the CRAM format (requires --reference).\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--fast"
    description: "Enable fast compression. This also changes the default output format\
      \ to BAM,\nbut this can be overridden by the explicit format options or using\
      \ a filename\nwith a known suffix.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--uncompressed"
    alternatives:
    - "-u"
    description: "Output uncompressed data. This also changes the default output format\
      \ to BAM,\nbut this can be overridden by the explicit format options or using\
      \ a filename\nwith a known suffix.\nThis option saves time spent on compression/decompression\
      \ and is thus preferred\nwhen the output is piped to another samtools command.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--with_header"
    description: "Include the header in the output.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--header_only"
    alternatives:
    - "-H"
    description: "Output the header only.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--no_header"
    description: "When producing SAM format, output alignment records but not headers.\n\
      This is the default; the option can be used to reset the effect of \n--with_header/--header_only.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--count"
    alternatives:
    - "-c"
    description: "Instead of printing the alignments, only count them and print the\
      \ total number.\nAll filter options, such as --require_flags, --excl_flags,\
      \ and --min_MQ, are taken\ninto account. The --unmap option is ignored in this\
      \ mode.\n"
    info: null
    direction: "input"
  - type: "file"
    name: "--output_unselected"
    alternatives:
    - "-U"
    description: "Write alignments that are not selected by the various filter options\
      \ to FILE.\nWhen this option is used, all alignments (or all alignments intersecting\
      \ the regions\nspecified) are written to either the output file or this file,\
      \ but never both.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--unmap"
    alternatives:
    - "-p"
    description: "Set the UNMAP flag on alignments that are not selected by the filter\
      \ options.\nThese alignments are then written to the normal output. This is\
      \ not compatible\nwith --output_unselected.\n"
    info: null
    direction: "input"
  - type: "string"
    name: "--read_group"
    alternatives:
    - "-r"
    description: "Output alignments in read group STR [null]. Note that records with\
      \ no RG tag will also be output\nwhen using this option. This behaviour may\
      \ change in a future release.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--tag"
    alternatives:
    - "-d"
    description: "Only output alignments with tag STR1 and associated value STR2,\
      \ which can be a string or an integer\n[null].\nThe value can be omitted, in\
      \ which case only the tag is considered.\nNote that this option does not specify\
      \ a tag type. For example, use --tag XX:42 to select alignments\nwith an XX:i:42\
      \ field, not --tag XX:i:42.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "file"
    name: "--tag_file"
    alternatives:
    - "-D"
    description: "Only output alignments with tag STR and associated values listed\
      \ in FILE.\n"
    info: null
    must_exist: true
    create_parent: true
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "integer"
    name: "--min_MQ"
    alternatives:
    - "-q"
    description: "Skip alignments with MAPQ smaller than INT.\n"
    info: null
    default:
    - 0
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--library"
    alternatives:
    - "-l"
    description: "Only output alignments in library STR.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "integer"
    name: "--min_qlen"
    alternatives:
    - "-m"
    description: "Only output alignments with number of CIGAR bases consuming query\
      \ sequence >= INT.\n"
    info: null
    default:
    - 0
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--expr"
    alternatives:
    - "-e"
    description: "Only include alignments that match the filter expression STR. The\
      \ syntax for these expressions is\ndescribed in the main samtools.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--require_flags"
    alternatives:
    - "-f"
    description: "Only output alignments with all bits set in FLAG present in the\
      \ FLAG field. FLAG can be specified\nin hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/),\
      \ in octal by beginning with `0' (i.e. /^0[0-7]+/),\nas a decimal number not\
      \ beginning with '0' or as a comma-separated list of flag names.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--excl_flags"
    alternatives:
    - "-F"
    description: "Do not output alignments with any bits set in FLAG present in the\
      \ FLAG field. FLAG can be specified\nin hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/),\
      \ in octal by beginning with `0' (i.e. /^0[0-7]+/),\nas a decimal number not\
      \ beginning with '0' or as a comma-separated list of flag names.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "integer"
    name: "--excl_all_flags"
    alternatives:
    - "-G"
    description: "Do not output alignments with all bits set in INT present in the\
      \ FLAG field. This is the opposite of\n--require_flags such that --require_flags\
      \ 12 --exclude_all_flags 12 is the same as no filtering at all.\nFLAG can be\
      \ specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal by\
      \ beginning with `0'\n(i.e. /^0[0-7]+/), as a decimal number not beginning with\
      \ '0' or as a comma-separated list of flag names.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--incl_flags"
    alternatives:
    - "--rf"
    description: "Only output alignments with any bit set in FLAG present in the FLAG\
      \ field. FLAG can be specified in hex\nby beginning with `0x' (i.e. /^0x[0-9A-F]+/),\
      \ in octal by beginning with `0' (i.e. /^0[0-7]+/), as a decimal\nnumber not\
      \ beginning with '0' or as a comma-separated list of flag names.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--remove_tag"
    alternatives:
    - "-x"
    description: "Read tag(s) to exclude from output (repeatable) [null]. This can\
      \ be a single tag or a comma separated list.\nAlternatively the option itself\
      \ can be repeated multiple times.\nIf the list starts with a `^' then it is\
      \ negated and treated as a request to remove all tags except those in STR.\n\
      The list may be empty, so --remove_tag ^ will remove all tags.\nNote that tags\
      \ will only be removed from reads that pass filtering.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--keep_tag"
    description: "This keeps only tags listed in STR and is directly equivalent to\
      \ --remove_tag ^STR. Specifying an empty list\nwill remove all tags. If both\
      \ --keep_tag and --remove_tag are specified then --keep_tag has precedence.\n\
      Note that tags will only be removed from reads that pass filtering.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--remove_B"
    alternatives:
    - "-B"
    description: "Collapse the backward CIGAR operation.\n"
    info: null
    direction: "input"
  - type: "string"
    name: "--add_flags"
    description: "Adds flag(s) to read. FLAG can be specified in hex by beginning\
      \ with `0x' (i.e. /^0x[0-9A-F]+/), in octal\nby beginning with `0' (i.e. /^0[0-7]+/),\
      \ as a decimal number not beginning with '0' or as a comma-separated\nlist of\
      \ flag names.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--remove_flags"
    description: "Remove flag(s) from read. FLAG is specified in the same way as with\
      \ the --add_flags option.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "double"
    name: "--subsample"
    description: "Output only a proportion of the input alignments, as specified by\
      \ 0.0 <= FLOAT <= 1.0, which gives the fraction\nof templates/pairs to be kept.\
      \ This subsampling acts in the same way on all of the alignment records in the\
      \ same\ntemplate or read pair, so it never keeps a read but not its mate.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "integer"
    name: "--subsample_seed"
    description: "Subsampling seed used to influence which subset of reads is kept.\
      \ When subsampling data that has previously\nbeen subsampled, be sure to use\
      \ a different seed value from those used previously; otherwise more reads will\n\
      be retained than expected.\n"
    info: null
    default:
    - 0
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--fetch_pairs"
    alternatives:
    - "-P"
    description: "Retrieve pairs even when the mate is outside of the requested region.\
      \ Enabling this option also turns on the\nmulti-region iterator (-M). A region\
      \ to search must be specified, either on the command-line, or using the\n--target_file\
      \ option. The input file must be an indexed regular file.\nThis option first\
      \ scans the requested region, using the RNEXT and PNEXT fields of the records\
      \ that have the\nPAIRED flag set and pass other filtering options to find where\
      \ paired reads are located. These locations are\nused to build an expanded region\
      \ list, and a set of QNAMEs to allow from the new regions. It will then make\n\
      a second pass, collecting all reads from the originally-specified region list\
      \ together with reads from additional\nlocations that match the allowed set\
      \ of QNAMEs. Any other filtering options used will be applied to all reads\n\
      found during this second pass.\nAs this option links reads using RNEXT and PNEXT,\
      \ it is important that these fields are set accurately. Use\n'samtools fixmate'\
      \ to correct them if necessary.\nNote that this option does not work with the\
      \ --count, --output-unselected or --unmap options.\n"
    info: null
    direction: "input"
  - type: "boolean_true"
    name: "--customized_index"
    alternatives:
    - "-X"
    description: "Include customized index file as a part of arguments. See EXAMPLES\
      \ section for sample of usage.\n"
    info: null
    direction: "input"
  - type: "string"
    name: "--sanitize"
    alternatives:
    - "-z"
    description: "Perform some sanity checks on the state of SAM record fields, fixing\
      \ up common mistakes made by aligners.\nThese include soft-clipping alignments\
      \ when they extend beyond the end of the reference, marking records as\nunmapped\
      \ when they have reference * or position 0, and ensuring unmapped alignments\
      \ have no CIGAR or mapping\nquality for unmapped alignments and no MD, NM, CG\
      \ or SM tags.\nFLAGs is a comma-separated list of keywords chosen from the following\
      \ list.\n\nunmap: The UNMAPPED BAM flag. This is set for reads with position\
      \ <= 0, reference name \"*\" or reads starting\nbeyond the end of the reference.\
      \ Note CIGAR \"*\" is permitted for mapped data so does not trigger this.\n\n\
      pos: Position and reference name fields. These may be cleared when a sequence\
      \ is unmapped due to the\ncoordinates being beyond the end of the reference.\
      \ Selecting this may change the sort order of the file,\nso it is not a part\
      \ of the on compound argument.\nmqual: Mapping quality. This is set to zero\
      \ for unmapped reads.\ncigar: Modifies CIGAR fields, either by adding soft-clips\
      \ for reads that overlap the end of the reference or\n       by clearing it\
      \ for unmapped reads.\naux: For unmapped data, some auxiliary fields are meaningless\
      \ and will be removed. These include NM, MD, CG and SM.\noff: Perform no sanity\
      \ fixing. This is the default\non: Sanitize data in a way that guarantees the\
      \ same sort order. This is everything except for pos.\nall: All sanitizing options,\
      \ including pos.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--no_PG"
    description: "Do not add a @PG line to the header of the output file.\n"
    info: null
    direction: "input"
  - type: "string"
    name: "--input_fmt_option"
    description: "Specify a single input file format option in the form of OPTION\
      \ or OPTION=VALUE.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--output_fmt"
    alternatives:
    - "-O"
    description: "Specify output format (SAM, BAM, CRAM).\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "string"
    name: "--output_fmt_option"
    description: "Specify a single output file format option in the form of OPTION\
      \ or OPTION=VALUE.\n"
    info: null
    required: false
    direction: "input"
    multiple: false
    multiple_sep: ";"
  - type: "boolean_true"
    name: "--write_index"
    description: "Automatically index the output files.\n"
    info: null
    direction: "input"
resources:
- type: "bash_script"
  path: "script.sh"
  is_executable: true
description: "Views and converts SAM/BAM/CRAM files."
test_resources:
- type: "bash_script"
  path: "test.sh"
  is_executable: true
- type: "file"
  path: "test_data"
info: null
status: "enabled"
scope:
  image: "public"
  target: "public"
requirements:
  commands:
  - "ps"
keywords:
- "view"
- "convert"
- "bam"
- "sam"
- "cram"
license: "MIT/Expat"
references:
  doi:
  - "10.1093/bioinformatics/btp352"
  - "10.1093/gigascience/giab008"
links:
  repository: "https://github.com/samtools/samtools"
  homepage: "https://www.htslib.org/"
  documentation: "https://www.htslib.org/doc/samtools-view.html"
runners:
- type: "executable"
  id: "executable"
  docker_setup_strategy: "ifneedbepullelsecachedbuild"
- type: "nextflow"
  id: "nextflow"
  directives:
    tag: "$id"
  auto:
    simplifyInput: true
    simplifyOutput: false
    transcript: false
    publish: false
  config:
    labels:
      mem1gb: "memory = 1000000000.B"
      mem2gb: "memory = 2000000000.B"
      mem5gb: "memory = 5000000000.B"
      mem10gb: "memory = 10000000000.B"
      mem20gb: "memory = 20000000000.B"
      mem50gb: "memory = 50000000000.B"
      mem100gb: "memory = 100000000000.B"
      mem200gb: "memory = 200000000000.B"
      mem500gb: "memory = 500000000000.B"
      mem1tb: "memory = 1000000000000.B"
      mem2tb: "memory = 2000000000000.B"
      mem5tb: "memory = 5000000000000.B"
      mem10tb: "memory = 10000000000000.B"
      mem20tb: "memory = 20000000000000.B"
      mem50tb: "memory = 50000000000000.B"
      mem100tb: "memory = 100000000000000.B"
      mem200tb: "memory = 200000000000000.B"
      mem500tb: "memory = 500000000000000.B"
      mem1gib: "memory = 1073741824.B"
      mem2gib: "memory = 2147483648.B"
      mem4gib: "memory = 4294967296.B"
      mem8gib: "memory = 8589934592.B"
      mem16gib: "memory = 17179869184.B"
      mem32gib: "memory = 34359738368.B"
      mem64gib: "memory = 68719476736.B"
      mem128gib: "memory = 137438953472.B"
      mem256gib: "memory = 274877906944.B"
      mem512gib: "memory = 549755813888.B"
      mem1tib: "memory = 1099511627776.B"
      mem2tib: "memory = 2199023255552.B"
      mem4tib: "memory = 4398046511104.B"
      mem8tib: "memory = 8796093022208.B"
      mem16tib: "memory = 17592186044416.B"
      mem32tib: "memory = 35184372088832.B"
      mem64tib: "memory = 70368744177664.B"
      mem128tib: "memory = 140737488355328.B"
      mem256tib: "memory = 281474976710656.B"
      mem512tib: "memory = 562949953421312.B"
      cpu1: "cpus = 1"
      cpu2: "cpus = 2"
      cpu5: "cpus = 5"
      cpu10: "cpus = 10"
      cpu20: "cpus = 20"
      cpu50: "cpus = 50"
      cpu100: "cpus = 100"
      cpu200: "cpus = 200"
      cpu500: "cpus = 500"
      cpu1000: "cpus = 1000"
  debug: false
  container: "docker"
engines:
- type: "docker"
  id: "docker"
  image: "quay.io/biocontainers/samtools:1.19.2--h50ea8bc_1"
  target_registry: "images.viash-hub.com"
  target_tag: "main"
  namespace_separator: "/"
  setup:
  - type: "docker"
    run:
    - "samtools --version 2>&1 | grep -E '^(samtools|Using htslib)' | \\\nsed 's#Using\
      \ ##;s# \\([0-9\\.]*\\)$#: \\1#' > /var/software_versions.txt\n"
  entrypoint: []
  cmd: null
- type: "native"
  id: "native"
build_info:
  config: "src/samtools/samtools_view/config.vsh.yaml"
  runner: "nextflow"
  engine: "docker|native"
  output: "target/nextflow/samtools/samtools_view"
  executable: "target/nextflow/samtools/samtools_view/main.nf"
  viash_version: "0.9.4"
  git_commit: "9991e9a4f5ddd5085a4e2becf962950b1daf594b"
  git_remote: "https://github.com/viash-hub/biobox"
package_config:
  name: "biobox"
  version: "main"
  summary: "A curated collection of high-quality, standalone bioinformatics components\
    \ built with [Viash](https://viash.io).\n"
  description: "`biobox` offers a suite of reliable bioinformatics components, similar\
    \ to [nf-core/modules](https://github.com/nf-core/modules) and [snakemake-wrappers/bio](https://github.com/snakemake/snakemake-wrappers/tree/master/bio),\
    \ but built using the [Viash](https://viash.io) framework.\n\nThis approach emphasizes\
    \ **reusability**, **reproducibility**, and adherence to **best practices**. Key\
    \ features of `biobox` components include:\n\n* **Standalone & Nextflow Ready:**\
    \ Run components directly via the command line or seamlessly integrate them into\
    \ Nextflow workflows.\n* **High Quality Standards:**\n    * Comprehensive documentation\
    \ for components and parameters.\n    * Full exposure of underlying tool arguments.\n\
    \    * Containerized (Docker) for dependency management and reproducibility.\n\
    \    * Unit tested for verified functionality.\n"
  info: null
  viash_version: "0.9.4"
  source: "src"
  target: "target"
  config_mods:
  - ".requirements.commands += ['ps']\n"
  - ".engines += { type: \"native\" }"
  - ".engines[.type == 'docker'].target_registry := 'images.viash-hub.com'"
  - ".engines[.type == 'docker'].target_tag := 'main'"
  keywords:
  - "bioinformatics"
  - "modules"
  - "sequencing"
  license: "MIT"
  organization: "vsh"
  links:
    repository: "https://github.com/viash-hub/biobox"
    issue_tracker: "https://github.com/viash-hub/biobox/issues"
