.TH TRANSMUTE 1 2023-02-21 NCBI "NCBI Entrez Direct User's Manual"
.SH NAME
transmute \- transform data, particularly within NCBI Entrez Direct
.SH SYNOPSIS
\fBtransmute\fP \fB\-x2p\fP|\fB\-j2p\fP

\fBtransmute\fP \fB\-align\fP
[\|\fB\-a\ \fIcodes\fP\|]
[\|\fB\-g\ \fIN\fP\|]
[\|\fB\-h\ \fIN\fP\|]
[\|\fB\-w\ \fIN\fP\|]

\fBtransmute\fP \fB\-j2x\fP (\fBjson2xml\fP)
[\|\fB\-set\fP\ \fItag\fP\|]
[\|\fB\-rec\fP\ \fItag\fP\|]
[\|\fB\-nest\fP\ \fBflat\fP|\fBrecurse\fP|\fBplural\fP\
|\fBsingular\fP|\fBdepth\fP|\fBelement\fP\|]

\fBtransmute\fP \fB\-a2x\fP
[\|\fB\-set\fP\ \fItag\fP\|]
[\|\fB\-rec\fP\ \fItag\fP\|]

\fBtransmute\fP \fB\-t2x\fP|\fB\-c2x\fP|\fB\-s2x\fP
(\fBtbl2xml\fP / \fBcsv2xml\fP / \fBscn2xml\fP)
[\|\fB\-set\fP\ \fItag\fP\|]
[\|\fB\-rec\fP\ \fItag\fP\|]
[\|\fB\-skip\fP\ \fIN\fP\|]
[\|\fB\-header\fP]
[\|\fB\-lower\fP|\fB\-upper\fP\|]
[\|\fB\-indent\fP|\fB\-flush\fP\|]
\fIcolumnName1\fP\ ...

\fBtransmute\fP \fB\-g2x\fP (\fBgbf2xml\fP)

\fBtransmute\fP \fB\-g2r\fP (\fBgbf2ref\fP)

\fBtransmute\fP \fB\-r2p\fP (\fBref2pmid\fP)
[\|\fB\-options\fP
\fBconfirm\fP|\fBverbose\fP|\fBfast\fP|\fBslow\fP|\fBexact\fP ...\|]

\fBtransmute\fP \fB\-revcomp\fP

\fBtransmute\fP \fB\-remove\fP
[\|\fB\-first\fP\ \fIN\fP\|]
[\|\fB\-last\fP\ \fIN\fP\|]

\fBtransmute\fP \fB\-retain\fP
\fB\-leading\fP\ \fIN\fP\|\fB\-trailing\fP\ \fIN\fP

\fBtransmute\fP \fB\-replace\fP
\fB\-offset\fP\ \fIN\fP|\fB\-column\fP\ \fIN\fP
[\|\fB\-delete\fP\ \fIN\fP\|]
[\|\fB\-insert\fP\ \fIseq\fP\|]
[\|\fB\-lower\fP\|]

\fBtransmute\fP \fB\-extract\fP
[\|\fB\-1\-based\fP\|]
[\|\fB\-0\-based\fP\|]
[\|\fB\-lower\fP\|]
\fIfeat_loc\fP

\fBtransmute\fP \fB\-cds2prot\fP
[\|\fB\-code\fP\ \fIN\fP\|]
[\|\fB\-frame\fP\ \fIN\fP\|]
[\|\fB\-stop\fP\|]
[\|\fB\-trim\fP\|]
[\|\fB\-part5\fP\|]
[\|\fB\-part3\fP\|]
[\|\fB\-every\fP\|]

\fBtransmute\fP \fB\-molwt\fP
[\|\fB\-met\fP\|]

\fBtransmute\fP \fB\-hgvs\fP

\fBtransmute\fP \fB\-counts\fP

\fBtransmute\fP \fB\-diff\fP

\fBtransmute\fP \fB\-codons\fP
\fB\-nuc\fP\ \fIseq\fP
\fB\-prot\fP\ \fIseq\fP
[\|\fB\-frame\fP\ \fIN\fP\|]
[\|\fB\-three\fP\|]

\fBtransmute\fP \fB\-search\fP
[\|\fB\-protein\fP\|]
[\|\fB\-circular\fP\|]
[\|\fB\-top\fP\|]
\fIpattern\fP\ ...

\fBtransmute\fP \fB\-find\fP
[\|\fB\-relaxed\fP\|]
[\|\fB\-sensitive\fP\|]
[\|\fB\-whole\fP\|]
\fIpattern\fP\ ...

\fBtransmute\fP \fB\-encodeXML\fP|\fB\-decodeXML\fP|\fB\-plainXML\fP

\fBtransmute\fP \fB\-encodeURL\fP|\fB\-decodeURL\fP

\fBtransmute\fP \fB\-encode64\fP|\fB\-decode64\fP

\fBtransmute\fP \fB\-plain\fP

\fBtransmute\fP \fB\-upper\fP|\fB\-lower\fP

\fBtransmute\fP \fB\-aa1to3\fP|\fB\-aa3to1\fP

\fBtransmute\fP \fB\-relax\fP

\fBtransmute\fP \fB\-format\fP\ [\|\fIfmt\fP\|]
[\|\fB\-xml\fP\ \fIdeclaration\fP\|]
[\|\fB\-doctype\fP\ \fIdeclaration\fP\|]
[\|\fB\-comment\fP\|]
[\|\fB\-cdata\fP\|]
[\|\fB\-combine\fP\|]
[\|\fB\-self\fP\|]
[\|\fB\-unicode\fP\ \fIstyle\fP\|]
[\|\fB\-script\fP\ \fIstyle\fP\|]
[\|\fB\-mathml\ terse\fP\|]

\fBtransmute\fP \fB\-filter\fP \fIelement\fP \fIaction\fP \fItarget\fP

\fBtransmute\fP \fB\-normalize\fP \fIdatabase\fP
.SH DESCRIPTION
\fBtransmute\fP reads data from standard input,
transforms it according to the specified mode,
and writes the transformed data to standard output.
.SH OPTIONS
.SS Pretty\-Printing
.TP
\fB\-x2p\fP
Reformat XML.
.TP
\fB\-j2p\fP
Reformat JSON.
.TP
\fB\-align\fP
Table column alignment.
.PD 0
.RS
.IP "\fB\-a\fP \fIcodes\fP" 9
Column alignment codes:
.RS
.IP \fBl\fP
Left.
.IP \fBc\fP
Center.
.IP \fBr\fP
Right.
.IP \fBn\fP
Numeric align on decimal point.
.IP \fBN\fP
Trailing zero\-pad decimals.
.IP \fBz\fP
Leading zero\-pad integers.
.IP \fBm\fP
Commas to group by 3 digits.
.IP \fBM\fP
Commas plus zero\-pad decimals.
.RE
.IP "\fB-g\fP \fIN\fP" 9
Spacing between columns.
.IP "\fB-h\fP \fIN\fP" 9
Indentation before columns.
.IP "\fB-w\fP \fIN\fP" 9
Minimum column width.
.RE
.PD
.SS Data Conversion
.TP
\fB\-j2x\fP
Convert JSON stream to XML suitable for \fB\-path\fP navigation.
.PD 0
.RS
.TP
\fB\-set\fP\ \fItag\fP
Replace set wrapper tag.
.TP
\fB\-rec\fP\ \fItag\fP
Replace record wrapper tag.
.TP
\fB\-nest\fP \
\fBflat\fP|\fBrecurse\fP|\fBplural\fP|\fBsingular\fP|\fBdepth\fP|\fBelement\fP
Nested array naming policy.
.RE
.PD
.TP
\fB\-a2x\fP
Convert text ASN.1 stream to XML suitable for \fB\-path\fP navigation.
.PD 0
.RS
.IP \fB\-set\fP\ \fItag\fP 10
Replace set wrapper tag.
.IP \fB\-rec\fP\ \fItag\fP 10
Replace record wrapper tag.
.RE
.PD
.TP
\fB\-t2x\fP, \fB\-c2x\fP, \fB\-s2x\fP
Convert tab\-delimited table, comma\-separated values file,
or semicolon\-delimited table,
respectively, to XML.
.PD 0
.RS
.IP \fB\-set\fP\ \fItag\fP 16
Replace set wrapper tag.
.IP \fB\-rec\fP\ \fItag\fP 16
Replace record wrapper tag.
.IP \fB\-skip\fP\ \fIN\fP 16
Skip the first \fIN\fP lines.
.IP \fB\-header\fP 16
Use fields from first row for column names.
.IP \fB\-lower\fP 16
Convert text to lowercase.
.IP \fB\-upper\fP 16
Convert text to uppercase.
.IP \fB\-indent\fP 16
Indent XML output.
.IP \fB\-flush\fP 16
Do not indent XML output.
.IP \fIcolumnName1\fP\ ... 16
XML object names per column.
.RE
.PD
.TP
\fB\-g2x\fP
Convert GenBank/GenPept flatfile format to INSDSeq XML.
.TP
\fB\-g2r\fP
Convert GenBank/GenPept flatfile format to Reference XML.
.TP
\fB\-r2p\fP [\|\fB\-options\fP \fIoption\fP ...\|]
Reference Index XML lookup to find PMIDs.
Supported \fIoption\fP values:
.RS
.TP 10
\fBconfirm\fP
Recheck existing PMID claims.
.TP 10
\fBverbose\fP
Add \fBNOTE\fP nodes explaining reasoning.
.TP 10
\fBfast\fP
Prefilter candidates relatively heavily (default).
.TP 10
\fBslow\fP
Prefilter candidates less heavily.
.TP 10
\fBexact\fP
Require exact, unique title matches.
.RE
.SS Sequence Editing
.TP 10
\fB\-revcomp\fP
Reverse complement nucleotide sequence.
.TP 10
\fB\-remove\fP
Trim at ends of sequence.
.PD 0
.RS
.TP 15
\fB\-first\fP\ \fIN\fP
Delete first \fIN\fP bases or residues.
.TP 15
\fB\-last\fP\ \fIN\fP
Delete last \fIN\fP bases or residues.
.RE
.PD
.TP 10
\fB\-retain\fP
Save either end of sequence.
.PD 0
.RS
.TP 15
\fB\-leading\fP\ \fIN\fP
Keep first \fIN\fP bases or residues.
.TP 15
\fB\-trailing\fP\ \fIN\fP
Keep last \fIN\fP bases or residues.
.RE
.PD
.TP 10
\fB\-replace\fP
Apply base or residue substition.
.PD 0
.RS
.TP 15
\fB\-offset\fP\ \fIN\fP
Skip ahead by 0\-based count (SPDI), or
.TP 15
\fB\-column\fP\ \fIN\fP
Move just before 1\-based position (HGVS).
.TP 15
\fB\-delete\fP\ \fIN\fP
Delete \fIN\fP bases or residues.
.TP
\fB\-insert\fP\ \fIseq\fP
Insert given sequence.
.TP
\fB\-lower\fP
Lower-case original sequence.
.RE
.PD
.TP 10
\fB\-extract\fP\ [\|\fB\-lower\fP\|]\ \fIfeat_loc\fP
Use \fBxtract \-insd\fP ... \fBfeat_location\fP instructions.
.PD 0
.RS
.TP
\fB\-1\-based\fP
GenBank feat_location convention.
.TP
\fB\-0\-based\fP
Alignment, or \fB\-insd\fP feat_intervals.
.TP
\fB\-lower\fP
Lower-case extracted sequence.
.RE
.PD
.SS Sequence Processing
.TP 10
\fB\-cds2prot\fP
Translate coding region into protein.
.PD 0
.RS
.TP 15
\fB\-code\fP\ \fIN\fP
Use genetic code \fIN\fP (\fB1\fP by default).
.TP 15
\fB\-frame\fP\ \fIN\fP
Offset in sequence.
.TP 15
\fB\-stop\fP
Include stop residue.
.TP 15
\fB\-trim\fP
Remove trailing \fBX\fPs and \fB*\fPs.
.TP 15
\fB\-part5\fP
CDS partial at 5' end.
.TP 15
\fB\-part3\fP
CDS extends past 3' end.
.TP
\fB\-every\fP
Translate all codons.
.RE
.PD
.TP 10
\fB\-molwt\fP
Calculate molecular weight of peptide.
.PD 0
.RS
.TP 15
\fB\-met\fP
Do not cleave leading methionine.
.RE
.PD
.SS Variation Processing
.TP
\fB\-hgvs\fP
Convert Human Genome Variation Society variation format to XML.
.SS Sequence Comparison
.TP 10
\fB\-counts\fP
Print summary of base or residue counts.
.TP 10
\fB\-diff\fP
Compare two aligned files for point differences.
.TP 10
\fB\-codons\fP
Display nucleotide codons above amino acid residues.
.PD 0
.RS
.TP 15
\fB\-nuc\fP\ \fIseq\fP
Nucleotide sequence.
.TP 15
\fB\-prot\fP\ \fIseq\fP
Protein sequence.
.TP 15
[\|\fB\-frame\fP\ \fIN\fP\|]
Offset in nucleotide sequence.
.TP 15
[\|\fB\-three\fP\|]
Use three\-letter residue abbreviations.
.RE
.PD
.SS Sequence Searching
.TP 10
\fB\-search\fP
Search for one or more patterns in a sequence,
skipping any FASTA definition line (with a leading \fB>\fP).
Each pattern can have an optional alias,
\fIe.g.\fP, \fBGGATCC:BamHI\fP.
.PD 0
.RS
.TP 10
\fB\-protein\fP
Do not expand nucleotide ambiguity characters.
.TP 10
\fB\-circular\fP
Match patterns spanning the origin of a circular molecule.
.TP 10
\fB\-top\fP
Do not search reverse complements of non\-palindromic patterns.
.TP 10
\fIpattern\fP
Pattern to search for.
.RE
.PD
.SS Text Searching
.TP 10
\fB\-find\fP
Find one or more patterns in text,
allowing digits, spaces, punctuation, and phrases,
\fIe.g.\fP, \fB"double, double toil and trouble"\fP.
.PD 0
.RS
.TP 15
\fB\-relaxed\fP
Match on words with letters and digits,
ignoring spacing and punctuation.
.TP 15
\fB\-sensitive\fP
Case\-sensitive match, distinguishing upper\-case and lower\-case letters.
.TP 15
\fB\-whole\fP
Match on whole words or multi\-word phrases; implies \fB\-relaxed\fP.
.TP 15
\fIpattern\fP
Pattern to search for.
.RE
.PD
.SS String Transformations
.SS "  XML"
.TP 12
\fB\-encodeXML\fP
XML\-encode \fB<\fP, \fB>\fP, \fB&\fP,
\fB\(dq\fP, and \fB\[aq]\fP characters.
.TP 12
\fB\-decodeXML\fP
Decode XML entity references.
.TP 12
\fB\-plainXML\fP
Remove embedded mixed\-content tags and compress runs of spaces.
.SS "  URL"
.TP 12
\fB\-encodeURL\fP
Compress runs of spaces, and URI\-escape the result.
.TP 12
\fB\-decodeURL\fP
URI\-unescape the input.
.SS "  Base64"
.TP 12
\fB\-encode64\fP
Base64\-encode the input.
.TP 12
\fB\-decode64\fP
Base64\-decode the input.
.SS "  Accent"
.TP 9
\fB\-plain\fP
Strip accents from the input.
.SS "  Case"
.TP 9
\fB\-upper\fP
Convert the input to uppercase.
.TP 9
\fB\-lower\fP
Convert the input to lowercase.
.SS Protein
.TP 9
\fB\-aa1to3\fP
Convert amino acids from 1\-character to 3\-character format.
.TP 9
\fB\-aa3to1\fP
Convert amino acids from 3\-character to 1\-character format.
.SS Letters plus Digits
.TP
\fB\-relax\fP
Remove all punctuation and compress whitespace.
.SS Customized XML Reformatting
.TP
\fB\-format\fP\ [\|\fIfmt\fP\|]
.PD 0
.RS
.IP \fBcompact\fP 9
Compress runs of spaces.
.IP \fBflush\fP 9
Suppress line indentation.
.IP \fBindent\fP 9
Indent according to nesting depth.
.IP \fBexpand\fP 9
Place each attribute on a separate line.

.TP
\fB\-xml\fP\ \fIdeclaration\fP
Use the given XML declaration.
.TP
\fB\-doctype\fP\ \fIdeclaration\fP
Use the given document type declaration.
.TP
\fB\-comment\fP
Preserve comments.
.TP
\fB\-cdata\fP
Preserve \fBcdata\fP blocks.
.TP
\fB\-combine\fP
If the input contains multiple top\-level documents,
combine them.
.TP
\fB\-self\fP
Keep empty self\-closing tags.
.TP
\fB\-unicode\fP\ \fIstyle\fP
How to handle Unicode superscript and subscript digits
(first converted to ASCII form in all cases).
.\".PD 0
.RS
.IP \fBfuse\fP 9
Run them all together, with no additional markup.
.IP \fBspace\fP 9
Add spaces between digits in different positions.
.IP \fBperiod\fP 9
Add periods between digits in different positions.
.IP \fBbrackets\fP 9
Surround superscripts by square brackets and subscripts by parentheses.
.IP \fBmarkdown\fP 9
Surround superscripts with carets and subscripts with tildes.
.IP \fBslash\fP 9
Add backslashes when going up in height
and forward slashes when going down.
.IP \fBtag\fP 9
Put superscripts in XML \fBsup\fP elements
and subscripts in \fBsub\fP elements.
.RE
.\".PD
.TP
\fB\-script\fP\ \fIstyle\fP
How to handle XML \fBsup\fP and \fBsub\fP elements
(denoting superscripts and subscripts, respectively).
.\".PD 0
.RS
.IP \fBbrackets\fP 9
Surround superscripts by square brackets and subscripts by parentheses.
.IP \fBmarkdown\fP 9
Surround superscripts with carets and subscripts with tildes.
.RE
.\".PD
.TP
\fB\-mathml\ terse\fP
Flatten MathML markup tersely.
.RE
.PD
.SS XML Modification
.TP
\fB\-filter\fP\ \fIelement\fP \fIaction\fP\ \fItarget\fP
Actions:
.PD 0
.RS
.IP \fBretain\fP 12
Keep matching elements (no\-op).
.IP \fBremove\fP 12
Remove matching elements.
.IP \fBencode\fP 12
HTML\-escape special characters.
.IP \fBdecode\fP 12
Decode HTML escapes.
.IP \fBshrink\fP 12
Compress runs of spaces.
.IP \fBexpand\fP 12
Place each attribute on a separate line.
.IP \fBaccent\fP 12
Strip off Unicode accents.
.PD
.P
Targets:
.PD 0
.IP \fBcontent\fP 12
Plain\-text content.
.IP \fBcdata\fP 12
\fBCDATA\fP blocks.
.IP \fBcomment\fP 12
Comments.
.IP \fBobject\fP 12
The whole object.
.IP \fBattributes\fP 12
Attributes.
.IP \fBcontainer\fP 12
Start and end tags.
.RE
.PD
.SS EFetch XML Normalization
.TP
\fB\-normalize\fP\ \fIdatabase\fP
Adjust XML fields to conform to common conventions.
.SH SEE ALSO
.BR align\-columns (1),
.BR blst2tkns (1),
.BR cit2pmid (1),
.BR csv2xml (1),
.BR disambiguate\-nucleotides (1),
.BR download\-pubmed (1),
.BR ds2pme (1),
.BR efetch (1),
.BR pma2pme (1),
.BR ref2pmid (1),
.BR tbl2prod (1),
.BR uniq\-table (1),
.BR xml2fsa (1),
.BR xml2tbl (1),
.BR xtract (1).