Package: pango-collapse
Pango-collapseCLI to collapse Pango lineages for reportingInstallInstall from pypi with pip.pipinstallpango-collapseUsagepango-collapsetakes a CSV file of SARS-CoV-2 samples (input.csv) with a column (defaultLineage) indicating the pango lineage of the samples (e.g. output from pangoLEARN, nextclade, USHER, etc).$catinput.csvLineageBA.5.2.1BA.4.6BE.1pango-collapsewill collapse lineages up to the first user defined parent lineage (specified in a text file with--collapse-file). If the sample lineage has no parent lineage in the user defined collapse file the compressed lineage will be returned. Collapse up to eitherAorBby adding A and B to the collapse file. By default (i.e. if no collapse file is specified)pango-collapseuses the collapse file foundhere. This file is dependant on the version ofpango-collapse, use--latestto load the latest version of the collapse file from github at run time.$catcollapse.txtBA.5
BE.1pango-collapsewill produce an output file which is a copy of the input file plusLineage_full(the uncompressed lineage),Lineage_expanded(the expanded lineage format) andLineage_family(the lineage collapsed up to) columns.pango-collapseinput.csv--collapse-filecollapse.txt-ooutput.csv$ cat output.csvLineageLineage_fullLineage_familyLineage_expandedBA.5.2.1B.1.1.529.5.2.1BA.5B.1.1.529:BA.5.2.1BA.4.6B.1.1.529.4.6BA.4.6B.1.1.529:BA.4.6BE.1B.1.1.529.5.3.1.1BE.1B.1.1.529:BA.5.3.1:BE.1Expanded lineage formatTheLineage_expandedcolumn contains the lineage in exapaned format which provides complete lineage information and searchability.B.1.1.529:BA.5.3.1:BE.1==B.1.1.529.5.3.1.1==BE.1The delimiter (:) separates each alias level in the full lineage. You can determine the parental lineages of a lineage in expanded format by reading from right to left. For example, from the expanded lineageB.1.1.529:BA.5.3.1:BE.1we can see thatBE.1comes fromBA.5.3.1which inturn comes fromB.1.1.529.Expanded lineages can be converted to full lineages by removing the delimiters and sub-lineage letters. Compressed lineages can be obtained by taking the final component of the expanded lineage.$echo"B.1.1.529:BA.5.3.1:BE.1"|sed-E's/:[A-Za-z]+//g'B.1.1.529.5.3.1.1# full lineage$echo"B.1.1.529:BA.5.3.1:BE.1"|awk-F:'{print $NF}'BE.1# compressed lineageLineages to the right of a delimiter are equivalent (although the parental lineages are implicit).B.1.1.529:BA.5.3.1:BE.1==BA.5.3.1:BE.1==BE.1Lineages in expanded format are easily searched. Exact matches can be found by matching with the end of the expanded lineage e.g. using the regex$anchor (:BE.1$to exactly match BE.1). Sub-lineages can be found by simply checking if the expanded lineage contains the parental lineage of interest.$grep":BA.5"output.csv# find all BA.5 sub-lineagesBA.5.2.1,B.1.1.529.5.2.1,BA.5,B.1.1.529:BA.5.2.1
BE.1,B.1.1.529.5.3.1.1,BE.1,B.1.1.529:BA.5.3.1:BE.1Nextclade exampleThis example shows how to use some of thepango-collapsefeatures by collapsing the Pango Lineages in the output fromNextclade.Produce a nextclade.tsv file from anextcladeanalysis (there is an example file intests/data).We are only interested in the major sub-lineages of omicron i.e. BA.1-BA.5. We can therefor make a collapse file with the following:$catcollapse.txtBA.1
BA.2
BA.3
BA.4
BA.5Note: BA is an alias of B.1.1.529, however, as we have not included B.1.1.529 in our collapse file any samples designated B.1.1.529 will not be included.Run the following command to collapse the omicron sub-lineages:pango-collapse -c collapse.txt -o nextclade_collapsed_omicron.tsv -l Nextclade_pango --strict nextclade.tsvThe-l(--lineage-column) flag tellspango-collapseto look for the compressed lineage in theNextclade_pangocolumn in the nextclade.tsv file.The--stricttellspango-collapseto use strict mode i.e. only report lineages in the collapse file. If the lineage cannot be collapsed then no value is returned in the collapse column.We can visualise the results in pandas:importpandasaspddf=pd.read_csv("nextclade_output.tsv",sep="\t")df.Lineage_family.fillna('Other',inplace=True)df.Lineage_family.value_counts().plot(kind='bar')--helpUsage: pango-collapse [OPTIONS] INPUT                                             
                                                                                   
 Collapse Pango sublineages up to user defined parent lineages.                    
                                                                                   
╭─ Arguments ─────────────────────────────────────────────────────────────────────╮
│ *    input      FILE  Path to input CSV/TSV with Lineage column.                │
│                       [default: None]                                           │
│                       [required]                                                │
╰─────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────────────╮
│ *  --output              -o      FILE  Path to output CSV/TSV with Lineage      │
│                                        column.                                  │
│                                        [default: None]                          │
│                                        [required]                               │
│    --collapse-file       -c      PATH  Path to collapse file with lineages (one │
│                                        per line) to collapse up to. Defaults to │
│                                        collapse file shipped with this version  │
│                                        of pango-collapse.                       │
│                                        [default:                                │
│                                        /Users/wwirth/Library/CloudStorage/OneD… │
│    --lineage-column      -l      TEXT  Column to extract from input file for    │
│                                        lineage.                                 │
│                                        [default: Lineage]                       │
│    --full-column         -f      TEXT  Column to use for the uncompressed       │
│                                        output.                                  │
│                                        [default: Lineage_full]                  │
│    --collapse-column     -k      TEXT  Column to use for the collapsed output.  │
│                                        [default: Lineage_family]                │
|    --expand-column       -e      TEXT  Column to use for the expanded output.   |
|                                        [default: Lineage_expanded]              |
│    --alias-file          -a      PATH  Path to Pango Alias file for             │
│                                        pango_aliasor. Will download latest file │
│                                        if not supplied.                         │
│                                        [default: None]                          │
│    --strict              -s            If a lineage is not in the collapse file │
│                                        return None instead of the compressed    │
│                                        lineage.                                 │
│    --latest              -u            Load the collapse from from a url        │
│                                        (--url).                                 │
│    --url                         TEXT  Url to use when loading the collapse     │
│                                        file with --latest.                      │
│                                        [default:                                │
│                                        https://raw.githubusercontent.com/MDU-P… │
│    --version             -v            Print the current version number and     │
│                                        exit.                                    │
│    --install-completion                Install completion for the current       │
│                                        shell.                                   │
│    --show-completion                   Show completion for the current shell,   │
│                                        to copy it or customize the              │
│                                        installation.                            │
│    --help                -h            Show this message and exit.              │
╰─────────────────────────────────────────────────────────────────────────────────╯