Opening your data

An analysis needs three things: the counts, the sequence the variants are named against, and the design that says which column is which sample. This page covers the first two; the next, the design.

What to bring

• Variant counts: a table with one row per variant and one column per sequenced sample (CSV or TSV, gzipped or not), as Enrich2, DiMSum, dms_variants or a lab's own scripts write them, or one file per sample. Or a table of barcodes, one row per barcode, with the barcode-to-variant map that says which variant each carries (below).
• The target sequence the variants are named against: a FASTA file, protein or DNA, or a GenBank file (a plasmid map, a RefSeq record), its coding feature chosen (below).
• The design: which column is which sample, replicate and time point. MaveScape drafts it from the column names, or reads it from a sample sheet (The design).

A score set published in MaveDB opens directly, its record, scores and counts together: Open from MaveDB (Public data).

Worth bringing if you have them, because they unlock or improve an analysis: what the assay measures and how the library was made (from the protocol); the cells carried into selection, the bins' gates and the cells sorted into each, and the times in generations (from the bench); the target's UniProt or RefSeq identifier. The Start page lists them with why each matters, and once there is a design, What the analysis can do says which are missing and what each would unlock.

Open the files from the start page, the workspace menu (⌘O), by dropping them on the window, or by naming them on the command line. Open the table and its FASTA (or GenBank file) together: sequences are read first, so the table finds its target.

hgvs_pro,input_rep1,output_rep1,input_rep2,output_rep2
p.=,52011,61873,48320,57112
p.Ser2Val,812,640,775,591
p.Ser2Ter,905,12,880,9
p.Lys3Pro,488,NA,502,33

The import wizard

The wizard shows what MaveScape found: the layout, the column of variant names and its level, the columns of counts with the roles their names suggest, the target, and the checks. Correct anything it got wrong, then Import; Save as template remembers the mapping for the next table with the same columns. Nothing is coerced silently: problems that block scoring (the same variant on two rows, counts that are not numbers or are negative, rows of the wrong width) are listed by line.

Barcodes and their map

In a barcoded library each variant is carried by several random barcodes, and the counts are counts of barcodes. Open the table of barcode counts and its barcode-to-variant map together: the wizard recognizes the map (a column of barcodes, a column of variants, no counts), applies it, and names the variant of every barcode. The map's variants may be MAVE-HGVS or lab names, dms_variants' substitutions (aa_substitutions, codon_substitutions), or whole variant sequences, as Enrich2's map gives them, named against the target's DNA.

A barcode the map gives two different variants is in conflict: neither can be trusted, so the barcode is left unmapped and listed, never resolved by guessing (Enrich2 stops with an error; dms_variants' tables cannot hold one). A counted barcode missing from the map is unmapped too; both are counted in quality control's "Barcodes the map names". A barcode written on two rows blocks scoring. The source keeps both files and how they were put together, so the table is assembled again the same way whenever it is read from the library.

dms_variants' own variant_counts table needs no map: it names each barcode's substitutions. When a barcode is in two libraries, it is written library/barcode, each library's its own.

Variant names

Names are MAVE-HGVS, MaveDB's nomenclature: p.Ala12Val, p.Ala12Ter, p.Ala12= (synonymous), p.= (the wild type), p.[Ala12Val;Lys14Arg], and c.34C>T at the nucleotide level. Lenient reading, the default, also takes lab and legacy forms (A12V, p.A12V, p.Ala12*, _wt, _sy) and keeps each as written beside its MAVE-HGVS form. Every name is checked against the target: one that disagrees with it (another residue at that position, or a position beyond the target) is not scored, and says why.

The whole of MAVE-HGVS is read: substitutions, deletions, insertions, duplications, deletion-insertions, frameshifts, multi-variants, intronic and UTR positions (c.67+1G>A, c.-12A>G, c.*30del), exactly as the reference parser, mavehgvs, reads them. A name may be prefixed by its target (NM_007294.3:c.68A>G); one naming another target is set aside, not scored (a score set of several targets opens one at a time).

What a nucleotide variant does to the protein

On a DNA target, each nucleotide variant is read for the protein change it makes: the variant is applied to the target's sequence and both coding sequences translated, then compared as HGVS describes protein changes. Its class is what it does: synonymous, missense, nonsense, start or stop lost, an in-frame deletion, insertion, duplication or deletion-insertion, a frameshift, a multi-variant; or a splice site (within two bases of an exon), intronic, or in a UTR. The protein change is written in MAVE-HGVS: a frameshift short (p.Gly5fs), a lost stop as the substitution at it (p.Ter120Gln), substitutions of several codons as a multi-variant, nothing after a stop the variant makes. So a nucleotide library's synonymous and nonsense variants serve as controls, its map is drawn at the protein level (The map), and its scores are exported with each variant's protein change.

The translation is checked against biocommons hgvs, variant by variant, on BRCA1's, TP53's and BAP1's transcripts (16,188 variants), and against the protein names MaveDB records publish beside their nucleotide names (validation).

Codon variants

Some tables name each codon variant on its own row, several codons to an amino-acid substitution (the EMPIRIC tables on MaveDB, for Hsp90 and others), and a protein-level column then names the same substitution on several rows. MaveScape does not guess which row is right: read at the protein level, such a table is blocked. Each row is: a codon variant (offered when a column holds coding names, c.…, and suggested when the protein names repeat) reads it at the protein level instead:

• each row's protein change is worked out from its nucleotide name against the target's DNA, in its reading frame (substitutions in the coding sequence; any other change is not named and not scored, and says why);
• a variant written on several rows with the same count in every column is one measurement written more than once, and is read once (MaveDB writes Hsp90's wild type once per position); with different counts it is a problem, not a guess;
• the codons of each protein variant are summed in every count column, into a column named hgvs_pro (from hgvs_nt).

The table's own protein column is not used: Hsp90's names the wild type's nine copies as synonymous changes, where their nucleotide names say no change. A design naming hgvs_pro (from hgvs_nt) reads its table this way wherever it is opened, by mavescape run too. Read at the nucleotide level, the rows stay codons.

Missing is not zero

An empty cell or NA (also N/A, NaN, null, None) is missing: the variant was not counted in that sample, and is not scored in that replicate. Write 0 only for a variant counted zero times. Some tables write variants that dropped out during selection as missing; quality control's "Missing after selection" finding says when that happens, and Missing = 0 in the Experiment view reads those samples' missing counts as 0.

The target

A FASTA or GenBank file of the protein or DNA sequence the variants are named against. Positions are numbered from 1 on the target; an offset, set in the Experiment view, numbers them on the reference too (an offset of 158 makes position 1 residue 159), and the map shows both. For DNA named at the protein level, the coding start can be set. With the target's UniProt accession, Check against UniProt finds the offset, and the differences of a construct, from the entry itself, and records which release it used (Public data).

>grb2-sh3 GRB2 SH3 domain, UniProt P62993 residues 159-214
TYVQALFDFDPQEDGELGFRRGDFIHVMDNSDPNWWKGACHGQTGMFPRNYVTPVN

From a GenBank file

A plasmid or construct map from your map tool (SnapGene, Benchling, ApE and Geneious export GenBank: .gb, .gbk, .gbff, .genbank, .ape), or a RefSeq record. When the record has several coding features (CDS), MaveScape asks which the variants are named on, offering first the longest whose translation checks. Each feature's translation is checked against the record's own, and the check kept with the target. A plasmid's target is its coding sequence, read on its strand (and joined, for a gene split by introns); an mRNA's is the whole record, numbered from its coding start, so that variants in its UTRs (c.-12, c.*30) are on it. Where the target came from (the file, the feature, the check) is kept with the workspace, shown in the Experiment view and the inspector, and named in the methods. A score set from MaveDB whose target is a RefSeq or Ensembl transcript has it fetched (Public data).

Every file

FORMATS.md describes every file MaveScape reads and writes, and the start page has blank layouts to fill in.