TRANSMUTE(1)

📦
version 24.0.20250523 · 3 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 TRANSMUTE(1) 💖

okay bestie, sit down, hydrate, because this is the Swiss-Army-knife-of-a-tool from the NCBI Entrez Direct User's Manual and she does. literally. everything. 💅

transmute is one of those commands where you type the name and then a flag and suddenly your whole data pipeline is fixed. it's giving ✨main character energy✨. we're gonna go through her whole resume, flag by flag, no cap.

✨ NAME ✨

transmute — transform data, particularly within NCBI Entrez Direct 🦋

✨ SYNOPSIS ✨

okay so here's the whole menu of vibes. no skipping, we're listing every single one 🫶

the little plain-ification trio:

transmute -x2p|-j2p|-f2p

sequence alignment moment:

transmute -align [-a codes] [-g N] [-h N] [-w N]

JSON → XML, and her cousin:

transmute -j2x (json2xml) [-set tag] [-rec tag]
[-nest flat|recurse|plural|singular|depth|element]
transmute -a2x [-set tag] [-rec tag]

table / CSV / SCN → XML (the whole little 2x clique ✨):

transmute -t2x|-c2x|-s2x (tbl2xml / csv2xml / scn2xml) [-set tag]
[-rec tag] [-skip N] [-header] [-lower|-upper] [-indent|-flush]
columnName1 ...

ini → XML:

transmute -i2x (ini2xml)

TOML → XML:

transmute -m2x (toml2xml)

YAML → XML:

transmute -y2x (yaml2xml)

filtering records, i.e. the ✂️ era:

transmute -txf (filter-record) [-pattern str] [-exclude str]
[-require str] [-min N] [-max N]

FSA → XML:

transmute -f2x (fsa2xml)

GenBank flat file → XML, and flat file → reference:

transmute -g2x (gbf2xml)
transmute -g2r (gbf2ref)

references → PMIDs, with a whole pile of little -options:

transmute -r2p (ref2pmid) [-options confirm|verbose|fast|slow|exact ...]

filtering GenBank, this time by accession, taxid, organism, all of it:

transmute -gbf (filter-genbank) [-accession acc|-accessions file]
[-taxid id|-taxids file] [-organism name] [-exclude str] [-require str]
[-truncate]

reverse complement szn:

transmute -revcomp

chopping from the front, chopping from the back:

transmute -remove [-first N] [-last N]

keeping a middle slice, -leading through -trailing:

transmute -retain -leading N-trailing N

the editor era — delete, insert, lowercase, offset or column:

transmute -replace -offset N|-column N [-delete N] [-insert seq]
[-lower]

extract a feature location, and yes you pick your indexing:

transmute -extract [-1-based|-0-based] [-lower] feat_loc

CDS → protein, with so many options bestie:

transmute -cds2prot [-gcode N] [-frame N|-all] [-stop] [-trim] [-part5]
[-part3] [-every] [-between str] [-circular] [-orf] [-max N]

molecular weight, with a little methionine flourish:

transmute -molwt [-met|-fmet]

HGVS things:

transmute -hgvs

counting things:

transmute -counts

comparing things:

transmute -diff

codon check — nuc vs prot, frame optional, three-letter optional:

transmute -codons -nuc seq -prot seq [-frame N] [-three]

searching, protein and/or circular, maybe just the top hit:

transmute -search [-protein] [-circular] [-top] pattern ...

finding, with relaxed / sensitive / whole modes:

transmute -find [-relaxed] [-sensitive] [-whole] pattern ...

the XML encoding squad 🎀:

transmute -encodeXML|-decodeXML|-plainXML

the URL encoding squad:

transmute -encodeURL|-decodeURL

the base64 squad:

transmute -encode64|-decode64

strip it back:

transmute -plain

case it up, case it down:

transmute -upper|-lower

amino acids, one letter ↔ three letter:

transmute -aa1to3|-aa3to1

the relaxer:

transmute -relax

the ✨format✨ girl — she has opinions on declarations, comments, CDATA, combining, self-closing, unicode, script, mathml:

transmute -format [fmt] [-xml declaration] [-doctype declaration]
[-comment] [-cdata] [-combine] [-self] [-unicode style] [-script style]
[-mathml terse]

filter by element, action, target:

transmute -filter element action target

and normalize a database:

transmute -normalize database

✨ DESCRIPTION ✨

okay so the whole plot: transmute reads data from standard input, transforms it according to the specified mode, and writes the transformed data to standard output. that's it. that's the girl. 🌸

in → mode → out. iconic behavior, honestly. 💜

and bestie, we are so not done — the flags and the details are still coming 💅

✨ OPTIONS ✨

okay bestie, here's the whole menu, and it's a LOT. we're not skipping a single flag, so grab a snack 🍓

Pretty-Printing 💅

  • -x2p — reformats XML. glow-up for your markup ✨
  • -j2p — reformats JSON. same energy, curly braces edition 🎀
  • -f2p — reformats FASTA. yes, even your sequences get the treatment 🧬
  • -align — table column alignment. lining everything up like the icon it is 👑
    • -a codes — the column alignment codes, pick your fave:
      • l — left.
      • c — center.
      • r — right.
      • n — numeric align on decimal point.
      • N — trailing zero-pad decimals.
      • z — leading zero-pad integers.
      • m — commas to group by 3 digits.
      • M — commas plus zero-pad decimals.
      • w — just print colum widths.
    • -g N — spacing between columns.
    • -h N — indentation before columns.
    • -w N — minimum column width.

Data Conversion 🔄

  • -j2x — convert a JSON stream to XML that's suitable for -path navigation. json girlies stay winning 💖
    • -set tag — replace the set wrapper tag.
    • -rec tag — replace the record wrapper tag.
    • -nest flat|recurse|plural|singular|depth|element — the nested array naming policy. choose your fighter.
  • -a2x — convert a text ASN.1 stream to XML suitable for -path navigation.
    • -set tag — replace the set wrapper tag.
    • -rec tag — replace the record wrapper tag.
  • -t2x, -c2x, -s2x — convert a tab-delimited table, a comma-separated values file, or a semicolon-delimited table (respectively) to XML. three besties, one job ✨
    • -set tag — replace the set wrapper tag.
    • -rec tag — replace the record wrapper tag.
    • -skip N — skip the first N lines.
    • -header — use fields from the first row for column names.
    • -lower — convert text to lowercase.
    • -upper — convert text to uppercase.
    • -indent — indent XML output.
    • -flush — do not indent XML output.
    • columnName1 ... — XML object names per column.
  • -i2x — convert .ini configuration file format to XML.
  • -m2x — convert TOML configuration file format to XML.
  • -y2x — convert YAML configuration file format to XML.
  • -txf — text file filtering. the bouncer at the door of your file 🚪
    • -pattern str — pattern at start of record.
    • -exclude str — reject if string is present.
    • -require str — require presence of string.
    • -min N — minimum record number.
    • -max N — maximum record number.
  • -f2x — convert a FASTA stream to corresponding XML.
  • -g2x — convert GenBank/GenPept flatfile format to INSDSeq XML.
  • -g2r — convert GenBank/GenPept flatfile format to Reference XML.
  • -r2p [-options option ...] — Reference Index XML lookup to find PMIDs. here's what you can throw in option:
    • confirm — recheck existing PMID claims.
    • verbose — add NOTE nodes explaining the reasoning.
    • fast — prefilter candidates relatively heavily (this is the default, bestie).
    • slow — prefilter candidates less heavily.
    • exact — require exact, unique title matches.
  • -gbf — GenBank/GenPept filtering.
    • -accession acc — single accession.
    • -accessions file — file of accessions.
    • -taxid id — single taxon identifier.
    • -taxids file — file of taxon identifiers.
    • -organism name — organism scientific name.
    • -exclude str — reject if string is present.
    • -require str — require presence of string.
    • -truncate — remove features and sequence. bye bye 👋

Sequence Editing ✂️

  • -revcomp — reverse complement nucleotide sequence. flip it and reverse it 🔁
  • -remove — trim at the ends of the sequence.
    • -first N — delete first N bases or residues.
    • -last N — delete last N bases or residues.
  • -retain — save either end of the sequence. keep the good parts 🫶
    • -leading N — keep first N bases or residues.
    • -trailing N — keep last N bases or residues.
  • -replace — apply a base or residue substitution.
    • -offset N — skip ahead by 0-based count (SPDI), or
    • -column N — move just before 1-based position (HGVS).
    • -delete N — delete N bases or residues.
    • -insert seq — insert the given sequence.
    • -lower — lower-case the original sequence.
  • -extract — use xtract -insd ... feat_location instructions.
    • -1-based — GenBank feat_location convention.
    • -0-based — alignment, or -insd feat_intervals.
    • -lower — lower-case the extracted sequence.
    • feat_loc — feature location.

Sequence Processing 🧬

  • -cds2prot — translate a coding region into protein. the main character transformation arc ✨
    • -gcode N — genetic code (1 by default).
    • -frame N — offset in sequence (0-based).
    • -stop — include stop residue.
    • -trim — remove trailing Xs and *s.
    • -part5 — CDS partial at 5' end.
    • -part3 — CDS extends past 3' end.
    • -every — translate all codons.
    • -between str — optional string between residues.
    • -all — simultaneous six-frame translations.
    • -circular — reprocess the first two priming bases at the end.
    • -orf — only capitalize residues at start states.
    • -max N — number of residues per line.
  • -molwt — calculate the molecular weight of a peptide. it's giving chemistry 💅
    • -met — do not cleave the leading methionine.
    • -fmet — retain leading formyl-methionine.

Variation Processing 🦋

  • -hgvs — convert Human Genome Variation Society variation format to XML.

Sequence Comparison 🔍

  • -counts — print a summary of base or residue counts.
  • -diff — compare two aligned files for point differences.
  • -codons — display nucleotide codons above amino acid residues.
    • -nuc seq — nucleotide sequence.
    • -prot seq — protein sequence.
    • [-frame N] — offset in nucleotide sequence.
    • [-three] — use three-letter residue abbreviations.

Sequence Searching 🔎

  • -search — search for one or more patterns in a sequence, skipping any FASTA definition line (the one with a leading >). each pattern can have an optional alias, like GGATCC:BamHI.
    • -protein — do not expand nucleotide ambiguity characters.
    • -circular — match patterns spanning the origin of a circular molecule.
    • -top — do not search reverse complements of non-palindromic patterns.
    • pattern — pattern to search for.

Text Searching 📝

  • -find — find one or more patterns in text, allowing digits, spaces, punctuation, and phrases, like "double, double toil and trouble". shakespeare coded, no cap 🎭
    • -relaxed — match on words with letters and digits, ignoring spacing and punctuation.
    • -sensitive — case-sensitive match, distinguishing upper-case and lower-case letters.
    • -whole — match on whole words or multi-word phrases; implies -relaxed.
    • pattern — pattern to search for.

String Transformations 🪄

XML

  • -encodeXML — XML-encode <, >, &, ", and ' characters.
  • -decodeXML — decode XML entity references.
  • -plainXML — remove embedded mixed-content tags and compress runs of spaces.

URL

  • -encodeURL — compress runs of spaces, and URI-escape the result.
  • -decodeURL — URI-unescape the input.

Base64

  • -encode64 — Base64-encode the input.
  • -decode64 — Base64-decode the input.

Accent

  • -plain — strip accents from the input.

Case

  • -upper — convert the input to uppercase.
  • -lower — convert the input to lowercase.

Protein 🥚

  • -aa1to3 — convert amino acids from 1-character to 3-character format.
  • -aa3to1 — convert amino acids from 3-character to 1-character format.

Letters plus Digits 🔢

  • -relax — remove all punctuation and compress whitespace.

Customized XML Reformatting ✨

  • -format [fmt] — pick your formatting vibe:
    • compact — compress runs of spaces.
    • flush — suppress line indentation.
    • indent — indent according to nesting depth.
    • expand — place each attribute on a separate line.
    • -xml declaration — use the given XML declaration.
    • -doctype declaration — use the given document type declaration.
    • -comment — preserve comments.
    • -cdata — preserve cdata blocks.
    • -combine — if the input contains multiple top-level documents, combine them.
    • -self — keep empty self-closing tags.
    • -unicode style — how to handle Unicode superscript and subscript digits (they get converted to ASCII form first in all cases, every single time):
      • fuse — run them all together, with no additional markup.
      • space — add spaces between digits in different positions.
      • period — add periods between digits in different positions.
      • brackets — surround superscripts by square brackets and subscripts by parentheses.
      • markdown — surround superscripts with carets and subscripts with tildes.
      • slash — add backslashes when going up in height and forward slashes when going down.
      • tag — put superscripts in XML sup elements and subscripts in sub elements.
    • -script style — how to handle XML sup and sub elements (those are superscripts and subscripts, respectively):
      • brackets — surround superscripts by square brackets and subscripts by parentheses.
      • markdown — surround superscripts with carets and subscripts with tildes.
    • -mathml terse — flatten MathML markup tersely.

XML Modification 🛠️

  • -filter element action target

Actions:

  • retain — keep matching elements (a no-op, literally does nothing bestie).
  • remove — remove matching elements.
  • encode — HTML-escape special characters.
  • decode — decode HTML escapes.
  • shrink — compress runs of spaces.
  • expand — place each attribute on a separate line.
  • accent — strip off Unicode accents.

Targets:

  • content — plain-text content.
  • cdata — CDATA blocks.
  • comment — comments.
  • object — the whole object.
  • attributes — attributes.
  • container — start and end tags.

EFetch XML Normalization 🧚

  • -normalize database — adjust XML fields so they conform to common conventions.

🌸 SEE ALSO 🌸

okay bestie, if you're obsessed with transmute (and honestly? same 💅) here's the whole squad of sibling tools you're gonna want to know. go give them a lil follow, they all ate:

  • align-columns(1)
  • blst2tkns(1)
  • bsmp2info(1)
  • cit2pmid(1)
  • csv2xml(1)
  • disambiguate-nucleotides(1)
  • download-flatfile(1)
  • download-pubmed(1)
  • ds2pme(1)
  • efetch(1)
  • filter-columns(1)
  • filter-genbank(1)
  • gbf2info(1)
  • gbf2tbl(1)
  • gff2xml(1)
  • gff-sort(1)
  • jsonl2xml(1)
  • pma2apa(1)
  • pma2pme(1)
  • pmc2bioc(1)
  • pmc2info(1)
  • print-columns(1)
  • ref2pmid(1)
  • snp2tbl(1)
  • sort-table(1)
  • spdi2tbl(1)
  • systematic-mutations(1)
  • tbl2prod(1)
  • uniq-table(1)
  • xml2fsa(1)
  • xml2tbl(1)
  • xfetch(1)
  • xtract(1)

and that's a wrap on the whole page, bestie!! 🎀✨ this iconic little manual was brought to you by the fine folks at NCBI 👑, dated 2025-05-26, and it lives under the name TRANSMUTE(1) in your friendly neighborhood section 1. now go transmute something, you absolute legend 💖🦋

📦 where this page comes from