Rohan Dandage, Philippe C. Després, Nozomu Yachie and Christian R. Landry. GENETICS 2019

1. Installation
2. Configuration
3. Input format
4. Output format
5. API

Basic requirements: Anaconda package manager. See requirements.md for set of bash commands that would install it.

1. Once all the requirements are satisfied, create a python 3.6 virtual environment.

wget https://raw.githubusercontent.com/rraadd88/beditor/master/environment.yml
conda env create -f environment.yml

2. Activate the virtual environment.

source activate beditor

3. Install beditor python package from pypi.

pip install beditor

Open the GUI window from terminal.

beditor

step1: input the configuration settings.

Note: genomes listed on the gui correspond to ensembl release=95.

step2: save the configuration settings and run beditor. Outputs will be stored in the same directory as the saved configuration settings file (yml file) in a folder with the same same name as the basename of the configuration settings file.

Note: output directory will have the same basename as the saved configuration file. If /a/b/gene_ed.yml is the path of the configuration file, the output directory will be /a/b/gene_ed/. See Output format for structure of the output directory.
Note: see the terminal messages in case of any issue.

1. Run the analysis.

beditor --cfg configuration.yml

2. Run a single step in the analysis.

beditor --step {step number} configuration.yml

step number and corresponding analysis:

1: Get genomic loci flanking the target site
2: Get possible mutagenesis strategies
3: Design guides
4: Check offtarget-effects

3. Help

beditor --help

Note: Path to this tsv (tab-separated values) file is provided in configuration file as a value for variable called dinp. E.g. dinp: input.tsv.

According to the mutation_format opted in configuration.yml file and corresponding columns needed in input.

Example for S. cerevisiae (ensembl genome release=95):

Example for S. cerevisiae (ensembl genome release=95):

Note: genomes listed in the gui correspond to ensembl release=95.
Note: nucleotide mutation and amino acid mutation are the desired mutations (not the wildtype/reference).

This YAML formatted file contains the all the analysis specific parameters.

Template: https://github.com/rraadd88/test_beditor/blob/master/common/configuration.yml

# Input: Mutation information
## Path to this tsv (tab-separated values) file
dinp: input.tsv
reverse_mutations: False

# Step 1: Extracting sequences flanking mutation site (`01_sequences/`).
## host information
host: scientific name
genomerelease: 93
# check assembly from http://useast.ensembl.org/index.html
genomeassembly: fromensembl


# Step 2: Estimating the editable mutations based on base editors chosen. (`02_mutagenesis/`).
# whether aminoacid or nucleotide mutations
mutation_format: aminoacid or nucleotide
##[N nonsyn] S syn else both
mutation_type: N
## keep nonsense mutations
keep_mutation_nonsense: False

## Mutations information can be provided in 3 options: 
## `mutations`: Required Mutations mentioned in input file. 
## `substitutions`: Required Substitutions provided as a file (template: https://github.com/rraadd88/test_beditor/blob/master/common/dsubmap.tsv).
## `mimetic`: Carry out Mimetic substitutions (base on genome wide substitution maps). Only for human and yeast.
## input: options 
## mutations, substitutions, mimetic, [no input: keeps all possible mutations (slow)]
mutations: mutations

## Parameters specific to above options
## 2. Substitutions provided as a file
dsubmap_preferred_path: 
## 3. Mimetic substitutions
## mimetism level (high: only the best one, [medium: best 5], low: best 10)
mimetism_level: medium
## can not mutate between these 
## if ['S','T','K'] is provided all mutations between thsese amino acids are disallowed
non_intermutables: []


# Step 3: Designed guides (`03_guides/`).
## allowed nucleuotide substitutions per codon
max_subs_per_codon: 1
## base editors to use (restriction max_subs_per_codon would override the choice of base editors)
BEs: ['Target-AID','ABE']
# Cas9 related options
## PAM sequence
pams: ['NGG','NG']

#------------------------------------------------
# System related options 
## Number of cpus/threads
cores: 6
## Number of lines to process per cpu
chunksize: 200
## Dependencies 
## by default the dependencies are installed from the conda environment.
## "optionally" paths to the dependencies could be included below.
bedtools: bedtools
bwa: bwa
samtools: samtools

mutation_format opted in configuration.yml file and corresponding columns needed in input: 

nucleotide :  ['genome coordinate','nucleotide wild-type','nucleotide mutation',]
aminoacid : ['transcript: id','aminoacid: wild-type','aminoacid: position','amino acid mutation','codon: wild-type','guide: id','guide+PAM sequence','beditor score','alternate alignments count','CFD score']

Format of guide: id:

{genomic locus}|{position of mutation}|({strategy})
where,
strategy= {base editor};{strand};@{distance of mutation from PAM};{PAM};{codon wild-type}:{codon mutation};{amino acid wild-type}:{amino acid mutation};

A directory by the basename of configuration file (eg. directory called 'human' if configuration file is 'human.yml') would be created in the same folder where configuration file is located. It is referred to as 'project directory'.

Inside a project directory there would be following folders named by corresponding steps of analysis.

1. 01_sequences/
Stores the output of step #1. Extracting sequences flanking mutation site.
2. 02_mutagenesis/
Stores the output of step #2. Estimating the editable mutations based on base editors chosen.
3. 03_guides/
Stores the output of step #3. Designed guides.
4. 04_offtargets/
Stores the output of step #4. Offtarget effects.
5. 05_outputs/
Stores combined output and visualizations and sets of positive and negative control guides.   
positive control guides are designed so that they introduce stop mutation in genes being targeted.  
begative control guides lack editable nucleotide in the window of maximum activity, thereby supposed to not introduce any mutation.  

Also,
- 00_input/
Stores input files.
- chunks/
If parallel processing is used, this folder would store individual parts (chunks) of the analysis. 

Custom base editor and PAM sequences can be used incorporated in the workflow by selecting 'Custom' option in the 1st tab of the GUI. Following is the layout of the options to input the information about the base editor and the PAM sequence.

The sets of installed BEs and PAMs are stored in a tab-separated table, located at beditor/data/dbepams.tsv directory (use which beditor to locate directory of beditor). In order to install new base editor or PAM, user would have to simply append the relevant information in the table.

# make the input files with mock data
git clone https://github.com/rraadd88/test_beditor.git
source activate beditor;cd test_beditor;python test_datasets.py

https://github.com/openvax/pyensembl#non-ensembl-data

Collects analysed chunks

• cfg – main configuration dict.
• chunkcfgps – paths to all configuration files of chunks

Collects minor chunk files

• cfg – configuration dict
• fpinchunk – path inside chuck’s project directory
• force – if True overwrites the outputs

Provides command-line inputs to the pipeline.

For checking the command-lineinputs,

beditor --help

Cobines stepwise analysis files into a pretty table.

• cfg – main configuration dict
• plot – if True creates visualizations

Runs steps of the analysis workflow in tandem.

• cfgp – path to configuration file
• step – step number
• test – if True uses only one core, linear processing with verbose allowed
• force – if True overwrites outputs

Runs indivudual chunk.

• cfgp – path to configuration file.
• cfg – configuration dict

Returns:

Checks if configuration dict is valid i.e. contains all the required fields

cfg – configuration dict

Checks if input file is valid i.e. contains all the required columns.

• cfg – configuration dict
• din – dataframe containing input data

Installs dependencies of beditor

cfg – configuration dict

Installs genomes

cfg – configuration dict

Wrapper for converting input data (transcript ids and positions of mutation) to seqeunces flanking the codon.

cfg – configuration dict

Fetches sequences if mutation format is amino acid

• cfg – configuration dict
• din – input data

Returns dsequences:

dataframe with sequences

Fetches sequences if mutation format is nucleotide

• cfg – configuration dict
• din – input data

Returns dsequences:

dataframe with sequences

Maps transcript id with protein id.

• t – pyensembl transcript object
• t – reading frames

Returns coding_sequence_positions:

dataframe with mapped positions

Fetches positions from transcript boundaries.

t – pyensembl transcript object

Returns coding_sequence_positions:

reading frames

Generates mutagenesis strategies from identities of reference and mutated codons (from dseq).

cfg – configurations from yml file

Filters the mutagenesis strategies by multiple options provided in configuration file (.yml).

• dmutagenesis – mutagenesis strategies (pd.DataFrame)
• cfg – configurations from yml file

Gets host specific codon table.

• aa – list of amino acids
• host – name of host

Returns:

codon table (pandas dataframe)

Creates codon usage table.

cuspp – path to cusp generated file

Returns:

codon usage table (pandas dataframe)

Assesses possible mutagenesis strategies, given the set of Base editors and positions of mutations.

• dcodontable – Codon table
• dcodonusage – Codon usage table
• BEs – Base editors (dict), see global_vars.py
• pos_muts – positions of mutations
• host – host organism

Returns:

possible mutagenesis strategies as a pandas dataframe

Fetches mimetic substitution map that would be used to filter mutagenesis strategies.

cfg – configurations from yml file.

Makes dseqeunces dataframe of nucleotide mutation format compatible to guide design modules

• dsequences – dsequences dataframe
• dmutagenesis – dmutagenesis dataframe

Duplicates dpam dataframe to be compatible for searching PAMs on - strand

• dpam – dataframe with pam information
• pams – pams to be used for actual designing of guides.

Wrapper around make guides function.

cfg – configuration dict.

Search PAM occurance

• dpam – dataframe with PAM sequences
• seq – target sequence
• pos_codon – reading frame
• test – debug mode on

Returns dpam_searches:

dataframe with positions of pams

Get positions of guides relative to the target site and PAM sequence Note: Index and flank sequence based indexing are 0-based Distances and positions from pam are 1-based

x – lambda section of dguides dataframe

Wrapper around submodules that design guides by 1. searching all PAM sequences on ‘both’ the strands, 2. filtering guides by all possible strategies (given in dmutagenesis) e.g. activity window, Finally generates a table.

• cfg – configuration dict
• dseq – dsequences dataframe
• dmutagenesis – dmutagenesis dataframe
• dpam – dpam dataframe
• test – debug mode on
• dbug – more verbose

Get sequences in FASTA format from BED file step#5

cfg – configuration dict

Get annotations from the aligned BED file step#3

cfg – configuration dict

Get guide seqeunces from the BED file step#4

cfg – configuration dict

Get sequences from BED file step#6

cfg – configuration dict

Aggregate annotations per alignment to annotations per guide. step#10

cfg – configuration dict

Gets scores for guides step#7

cfg – configuration dict

Aggregate annotations per guide step#8

cfg – configuration dict

Map aggregated annotations to guides step#9

cfg – configuration dict

Aligns guides to genome and gets SAM file step#1

• cfg – configuration dict
• dguides – dataframe of guides

All the processes in offtarget detection are here.

cfg – Configuration settings provided in .yml file

Processes SAM file to get the genomic coordinates in BED format step#2

cfg – configuration dict