{
  "slug": "sam-to-csv",
  "name": "gizza-ai/sam-to-csv",
  "version": "0.1.0",
  "title": "SAM to CSV Converter — Parse Alignment Records — gizza.ai",
  "description": "Convert SAM sequence-alignment records into CSV or TSV with named columns, decoded FLAG bits, optional tag columns, filters, and computed spans.",
  "tags": [
    "sam",
    "csv",
    "tsv",
    "sequence alignment",
    "bioinformatics",
    "genomics",
    "sam flag",
    "cigar",
    "mapq",
    "bam",
    "alignment"
  ],
  "category": "data",
  "urls": {
    "page": "https://gizza.ai/tools/sam-to-csv/",
    "markdown": "https://gizza.ai/tools/sam-to-csv/index.md",
    "descriptor": "https://gizza.ai/tools/sam-to-csv/tool.json",
    "deep_link_example": "https://gizza.ai/tools/sam-to-csv/?input=%40HD%09VN%3A1.6%0Ar001%0999%09chr1%097%0960%098M2I4M1D3M%09%3D%0937%0939%09TTAGATAAAGGATACTG%09%2A%09NM%3Ai%3A1%09AS%3Ai%3A30&delimiter=comma&header=true&flags=summary&tags=expand&tag_fields=NM%2CAS%2CMD&include_seq=true&computed=true&mapped_only=true&primary_only=true&min_mapq=0&missing=."
  },
  "cli": "gizza tool sam-to-csv \"@HD\tVN:1.6\nr001\t99\tchr1\t7\t60\t8M2I4M1D3M\t=\t37\t39\tTTAGATAAAGGATACTG\t*\tNM:i:1\tAS:i:30\"",
  "tool": {
    "description": "Parse SAM (Sequence Alignment/Map) text into a delimited table with named columns. @ header lines are skipped and each alignment line becomes one row of QNAME, FLAG, RNAME, POS, MAPQ, CIGAR, RNEXT, PNEXT, TLEN, SEQ and QUAL. The bitwise FLAG can be decoded into a FLAG_SUMMARY column of set bit names, into 12 true/false FLAG_* columns, or both. Optional TAG:TYPE:VALUE fields can be expanded one column per tag, joined into a single TAGS column, or dropped, and tag_fields whitelists which tags to keep. Set computed=true to add END, REF_SPAN, READ_LEN and STRAND derived from POS/CIGAR/SEQ; use mapped_only, primary_only and min_mapq to filter records; include_seq=false drops the bulky SEQ/QUAL columns; delimiter picks comma, tab, semicolon or pipe output. Runs locally on pasted text: it does not read BAM/CRAM binaries, index files, or a reference genome.",
    "parameters": {
      "additionalProperties": false,
      "properties": {
        "computed": {
          "default": false,
          "description": "Add columns derived from POS, CIGAR and SEQ: END (last reference base covered), REF_SPAN (reference bases consumed by M/D/N/=/X), READ_LEN (SEQ length, or the CIGAR query span when SEQ is '*'), and STRAND ('+' or '-' from the 0x10 bit). Default false.",
          "type": "boolean"
        },
        "delimiter": {
          "default": "comma",
          "description": "Output field separator. 'comma' (default) writes CSV with RFC 4180 quoting; 'tab' writes TSV; 'semicolon' and 'pipe' suit European spreadsheets and shell pipelines.",
          "enum": [
            "comma",
            "tab",
            "semicolon",
            "pipe"
          ],
          "type": "string"
        },
        "flags": {
          "default": "summary",
          "description": "How the bitwise FLAG is decoded. 'summary' (default) adds one FLAG_SUMMARY column listing the set bit names (PAIRED, PROPER_PAIR, UNMAPPED, MATE_UNMAPPED, REVERSE, MATE_REVERSE, READ1, READ2, SECONDARY, QCFAIL, DUPLICATE, SUPPLEMENTARY); 'bits' adds 12 true/false columns FLAG_PAIRED..FLAG_SUPPLEMENTARY; 'both' adds all of them; 'none' keeps only the raw FLAG number.",
          "enum": [
            "none",
            "summary",
            "bits",
            "both"
          ],
          "type": "string"
        },
        "header": {
          "default": true,
          "description": "Emit the column-name header row. Turn off when appending to a table that already has one. Default true.",
          "type": "boolean"
        },
        "include_seq": {
          "default": true,
          "description": "Keep the SEQ and QUAL columns. Turn off for a compact coordinate table without read bases and base qualities. Default true.",
          "type": "boolean"
        },
        "input": {
          "description": "SAM text to parse. Paste tab-separated Sequence Alignment/Map records; @HD/@SQ/@RG/@PG/@CO header lines are skipped. Each record needs the 11 mandatory fields QNAME, FLAG, RNAME, POS, MAPQ, CIGAR, RNEXT, PNEXT, TLEN, SEQ, QUAL, optionally followed by TAG:TYPE:VALUE fields such as NM:i:0.",
          "type": "string"
        },
        "mapped_only": {
          "default": false,
          "description": "Keep only mapped records by dropping those with the 0x4 (UNMAPPED) bit set. Default false.",
          "type": "boolean"
        },
        "min_mapq": {
          "default": 0,
          "description": "Drop records whose MAPQ is below this value (0-255). MAPQ 255 means 'unavailable' and is never filtered out by a threshold below 255. Default 0 (keep everything).",
          "maximum": 255,
          "minimum": 0,
          "type": "integer"
        },
        "missing": {
          "default": ".",
          "description": "Placeholder written when a value does not apply: an absent tag, a FLAG of 0 in summary mode, or END/REF_SPAN/STRAND for an unmapped record. Default '.'.",
          "type": "string"
        },
        "primary_only": {
          "default": false,
          "description": "Keep only primary alignments by dropping records with the 0x100 (SECONDARY) or 0x800 (SUPPLEMENTARY) bit set. Default false.",
          "type": "boolean"
        },
        "tag_fields": {
          "default": "",
          "description": "Optional comma-separated whitelist of tag names to keep, in the requested output order (for example 'NM,AS,MD'). Leave blank to keep every tag found.",
          "type": "string"
        },
        "tags": {
          "default": "expand",
          "description": "How optional TAG:TYPE:VALUE fields are emitted. 'expand' (default) creates one column per discovered tag name (NM, AS, MD, ...) holding its value; 'joined' puts them all in a single TAGS column as 'NM:1 AS:30'; 'none' drops them.",
          "enum": [
            "none",
            "joined",
            "expand"
          ],
          "type": "string"
        }
      },
      "required": [
        "input"
      ],
      "type": "object"
    }
  }
}