name: samtools_view
namespace: samtools
description: Views and converts SAM/BAM/CRAM files.
keywords: [view, convert, bam, sam, cram]
links:
  homepage: https://www.htslib.org/
  documentation: https://www.htslib.org/doc/samtools-view.html
  repository: https://github.com/samtools/samtools
references: 
  doi: [10.1093/bioinformatics/btp352, 10.1093/gigascience/giab008]
license: MIT/Expat

argument_groups:
  - name: Inputs
    arguments:
    - name: --input
      type: file
      description: Input SAM, BAM, or CRAM file.
      required: true
      must_exist: true
    - name: --fai_reference
      alternatives: -t
      type: file
      description: |
        A tab-delimited FILE. Each line must contain the reference name in the first column
        and the length of the reference in the second column, with one line for each distinct
        reference. Any additional fields beyond the second column are ignored. This file also
        defines the order of the reference sequences in sorting. If you run: `samtools faidx <ref.fa>',
        the resulting index file <ref.fa>.fai can be used as this FILE.
    - name: --reference
      alternatives: -T
      type: file
      description: |
        A FASTA format reference FILE, optionally compressed by bgzip and ideally indexed by samtools faidx.
        If an index is not present one will be generated for you, if the reference file is local.
        If the reference file is not local, but is accessed instead via an https://, s3:// or other URL,
        the index file will need to be supplied by the server alongside the reference. It is possible to
        have the reference and index files in different locations by supplying both to this option separated
        by the string "##idx##", for example:
        --reference ftp://x.com/ref.fa##idx##ftp://y.com/index.fa.fai
        However, note that only the location of the reference will be stored in the output file header.
        If this method is used to make CRAM files, the cram reader may not be able to find the index,
        and may not be able to decode the file unless it can get the references it needs using a different
        method.
    - name: --target_file
      alternatives: -L
      type: file
      description: |
        Only output alignments overlapping the input BED FILE [null].
    - name: --region_file
      type: file
      description: |
        Use an index and multi-region iterator to only output alignments overlapping the input BED FILE.
        Equivalent to --use_index --target_file FILE.
    - name: --qname_file
      alternatives: -N
      type: file
      description: |
        Output only alignments with read names listed in FILE. If FILE starts with ^ then the operation is
        negated and only outputs alignment with read groups not listed in FILE. It is not permissible to mix
        both the filter-in and filter-out style syntax in the same command.
      must_exist: true
    - name: --read_group_file
      alternatives: -R
      type: file
      description: |
        Output alignments in read groups listed in FILE [null]. If FILE starts with ^ then the operation is
        negated and only outputs alignment with read names not listed in FILE. It is not permissible to mix
        both the filter-in and filter-out style syntax in the same command. Note that records with no RG tag
        will also be output when using this option. This behaviour may change in a future release.
      must_exist: true
    - name: --use_index
      alternatives: -M
      type: boolean_true
      description: |
        Use the multi-region iterator on the union of a BED file and command-line region arguments.
        This avoids re-reading the same regions of files so can sometimes be much faster. Note this also
        removes duplicate sequences. Without this a sequence that overlaps multiple regions specified on
        the command line will be reported multiple times. The usage of a BED file is optional and its path
        has to be preceded by --target_file option.
     
  - name: Outputs
    arguments:
    - name: --output
      alternatives: -o
      type: file
      description: Output to FILE instead of [stdout].
      required: true
      direction: output
      example: output.bam
    - name: --bam
      alternatives: -b
      type: boolean_true
      description: Output in the BAM format.
    - name: --cram
      alternatives: -C
      type: boolean_true
      description: |
        Output in the CRAM format (requires --reference).
    - name: --fast
      type: boolean_true
      description: |
        Enable fast compression. This also changes the default output format to BAM,
        but this can be overridden by the explicit format options or using a filename
        with a known suffix.
    - name: --uncompressed
      alternatives: -u
      type: boolean_true
      description: |
        Output uncompressed data. This also changes the default output format to BAM,
        but this can be overridden by the explicit format options or using a filename
        with a known suffix.
        This option saves time spent on compression/decompression and is thus preferred
        when the output is piped to another samtools command.
    - name: --with_header
      type: boolean_true
      description: |
        Include the header in the output.
    - name: --header_only
      alternatives: -H
      type: boolean_true
      description: |
        Output the header only.
    - name: --no_header
      type: boolean_true
      description: |
        When producing SAM format, output alignment records but not headers.
        This is the default; the option can be used to reset the effect of 
        --with_header/--header_only.
    - name: --count
      alternatives: -c
      type: boolean_true
      description: |
        Instead of printing the alignments, only count them and print the total number.
        All filter options, such as --require_flags, --excl_flags, and --min_MQ, are taken
        into account. The --unmap option is ignored in this mode.
    - name: --output_unselected
      alternatives: -U
      type: file
      description: |
        Write alignments that are not selected by the various filter options to FILE.
        When this option is used, all alignments (or all alignments intersecting the regions
        specified) are written to either the output file or this file, but never both.
    - name: --unmap
      alternatives: -p
      type: boolean_true
      description: |
        Set the UNMAP flag on alignments that are not selected by the filter options.
        These alignments are then written to the normal output. This is not compatible
        with --output_unselected.
    - name: --read_group
      alternatives: -r
      type: string
      description: |
        Output alignments in read group STR [null]. Note that records with no RG tag will also be output
        when using this option. This behaviour may change in a future release.
    - name: --tag 
      alternatives: -d
      type: string
      description: |
        Only output alignments with tag STR1 and associated value STR2, which can be a string or an integer
        [null].
        The value can be omitted, in which case only the tag is considered.
        Note that this option does not specify a tag type. For example, use --tag XX:42 to select alignments
        with an XX:i:42 field, not --tag XX:i:42.
    - name: --tag_file
      alternatives: -D
      type: file
      description: |
        Only output alignments with tag STR and associated values listed in FILE.
      must_exist: true
    - name: --min_MQ
      alternatives: -q
      type: integer
      description: |
        Skip alignments with MAPQ smaller than INT.
      default: 0
    - name: --library
      alternatives: -l
      type: string
      description: |
        Only output alignments in library STR.
    - name: --min_qlen
      alternatives: -m
      type: integer
      description: |
        Only output alignments with number of CIGAR bases consuming query sequence >= INT.
      default: 0
    - name: --expr
      alternatives: -e
      type: string
      description: |
        Only include alignments that match the filter expression STR. The syntax for these expressions is
        described in the main samtools.
    - name: --require_flags
      alternatives: -f
      type: string
      description: |
        Only output alignments with all bits set in FLAG present in the FLAG field. FLAG can be specified
        in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal by beginning with `0' (i.e. /^0[0-7]+/),
        as a decimal number not beginning with '0' or as a comma-separated list of flag names.
    - name: --excl_flags
      alternatives: -F
      type: string
      description: |
        Do not output alignments with any bits set in FLAG present in the FLAG field. FLAG can be specified
        in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal by beginning with `0' (i.e. /^0[0-7]+/),
        as a decimal number not beginning with '0' or as a comma-separated list of flag names.
    - name: --excl_all_flags
      alternatives: -G
      type: integer
      description: |
        Do not output alignments with all bits set in INT present in the FLAG field. This is the opposite of
        --require_flags such that --require_flags 12 --exclude_all_flags 12 is the same as no filtering at all.
        FLAG can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal by beginning with `0'
        (i.e. /^0[0-7]+/), as a decimal number not beginning with '0' or as a comma-separated list of flag names.
    - name: --incl_flags
      alternatives: --rf
      type: string
      description: |
        Only output alignments with any bit set in FLAG present in the FLAG field. FLAG can be specified in hex
        by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal by beginning with `0' (i.e. /^0[0-7]+/), as a decimal
        number not beginning with '0' or as a comma-separated list of flag names.
    - name: --remove_tag
      alternatives: -x
      type: string
      description: |
        Read tag(s) to exclude from output (repeatable) [null]. This can be a single tag or a comma separated list.
        Alternatively the option itself can be repeated multiple times.
        If the list starts with a `^' then it is negated and treated as a request to remove all tags except those in STR.
        The list may be empty, so --remove_tag ^ will remove all tags.
        Note that tags will only be removed from reads that pass filtering.
    - name: --keep_tag
      type: string
      description: |
        This keeps only tags listed in STR and is directly equivalent to --remove_tag ^STR. Specifying an empty list
        will remove all tags. If both --keep_tag and --remove_tag are specified then --keep_tag has precedence.
        Note that tags will only be removed from reads that pass filtering.
    - name: --remove_B
      alternatives: -B
      type: boolean_true
      description: |
        Collapse the backward CIGAR operation.
    - name: --add_flags
      type: string
      description: |
        Adds flag(s) to read. FLAG can be specified in hex by beginning with `0x' (i.e. /^0x[0-9A-F]+/), in octal
        by beginning with `0' (i.e. /^0[0-7]+/), as a decimal number not beginning with '0' or as a comma-separated
        list of flag names.
    - name: --remove_flags
      type: string
      description: |
        Remove flag(s) from read. FLAG is specified in the same way as with the --add_flags option.
    - name: --subsample
      type: double
      description: |
        Output only a proportion of the input alignments, as specified by 0.0 <= FLOAT <= 1.0, which gives the fraction
        of templates/pairs to be kept. This subsampling acts in the same way on all of the alignment records in the same
        template or read pair, so it never keeps a read but not its mate.
    - name: --subsample_seed
      type: integer
      description: |
        Subsampling seed used to influence which subset of reads is kept. When subsampling data that has previously
        been subsampled, be sure to use a different seed value from those used previously; otherwise more reads will
        be retained than expected.
      default: 0
    - name: --fetch_pairs
      alternatives: -P
      type: boolean_true
      description: |
        Retrieve pairs even when the mate is outside of the requested region. Enabling this option also turns on the
        multi-region iterator (-M). A region to search must be specified, either on the command-line, or using the
        --target_file option. The input file must be an indexed regular file.
        This option first scans the requested region, using the RNEXT and PNEXT fields of the records that have the
        PAIRED flag set and pass other filtering options to find where paired reads are located. These locations are
        used to build an expanded region list, and a set of QNAMEs to allow from the new regions. It will then make
        a second pass, collecting all reads from the originally-specified region list together with reads from additional
        locations that match the allowed set of QNAMEs. Any other filtering options used will be applied to all reads
        found during this second pass.
        As this option links reads using RNEXT and PNEXT, it is important that these fields are set accurately. Use
        'samtools fixmate' to correct them if necessary.
        Note that this option does not work with the --count, --output-unselected or --unmap options.
    - name: --customized_index
      alternatives: -X
      type: boolean_true
      description: |
        Include customized index file as a part of arguments. See EXAMPLES section for sample of usage.
    - name: --sanitize
      alternatives: -z
      type: string
      description: |
        Perform some sanity checks on the state of SAM record fields, fixing up common mistakes made by aligners.
        These include soft-clipping alignments when they extend beyond the end of the reference, marking records as
        unmapped when they have reference * or position 0, and ensuring unmapped alignments have no CIGAR or mapping
        quality for unmapped alignments and no MD, NM, CG or SM tags.
        FLAGs is a comma-separated list of keywords chosen from the following list.
        
        unmap: The UNMAPPED BAM flag. This is set for reads with position <= 0, reference name "*" or reads starting
        beyond the end of the reference. Note CIGAR "*" is permitted for mapped data so does not trigger this.
        
        pos: Position and reference name fields. These may be cleared when a sequence is unmapped due to the
        coordinates being beyond the end of the reference. Selecting this may change the sort order of the file,
        so it is not a part of the on compound argument.
        mqual: Mapping quality. This is set to zero for unmapped reads.
        cigar: Modifies CIGAR fields, either by adding soft-clips for reads that overlap the end of the reference or
               by clearing it for unmapped reads.
        aux: For unmapped data, some auxiliary fields are meaningless and will be removed. These include NM, MD, CG and SM.
        off: Perform no sanity fixing. This is the default
        on: Sanitize data in a way that guarantees the same sort order. This is everything except for pos.
        all: All sanitizing options, including pos.
    - name: --no_PG
      type: boolean_true
      description: |
        Do not add a @PG line to the header of the output file.
    - name: --input_fmt_option
      type: string
      description: |
        Specify a single input file format option in the form of OPTION or OPTION=VALUE.
    - name: --output_fmt
      alternatives: -O
      type: string
      description: |
        Specify output format (SAM, BAM, CRAM).
    - name: --output_fmt_option
      type: string
      description: |
        Specify a single output file format option in the form of OPTION or OPTION=VALUE.
    - name: --write_index
      type: boolean_true
      description: |
        Automatically index the output files.

resources:
  - type: bash_script
    path: script.sh
test_resources:
  - type: bash_script
    path: test.sh
  - type: file
    path: test_data
engines:
  - type: docker
    image: quay.io/biocontainers/samtools:1.19.2--h50ea8bc_1
    setup:
      - type: docker
        run: |
          samtools --version 2>&1 | grep -E '^(samtools|Using htslib)' | \
          sed 's#Using ##;s# \([0-9\.]*\)$#: \1#' > /var/software_versions.txt
runners:
- type: executable
- type: nextflow