Package: chiron
ChironA basecaller for Oxford Nanopore Technologies' sequencersUsing a deep learning CNN+RNN+CTC structure to establish end-to-end basecalling for the nanopore sequencer.Built withTensorFlowand python 2.7.If you found Chiron useful, please consider to cite:Haotian Teng, Minh Duc Cao, Michael B Hall, Tania Duarte, Sheng Wang, Lachlan J M Coin; Chiron: translating nanopore raw signal directly into nucleotide sequence using deep learning, GigaScience, Volume 7, Issue 5, 1 May 2018, giy037,https://doi.org/10.1093/gigascience/giy037DNA basecall:python chiron/entry.py call -i <input_fast5_folder> -o <output_folder> -m chiron/model/DNA_default -p dna-preRNA basecall:python chiron/entry.py call -i <input_fast5_folder> -o <output_folder> -m chiron/model/RNA_default -p rna-pre --mode rnaTable of contentsInstallInstall usingpipInstall from GitHubBasecallIf installed frompipIf installed from GitHubTest runPreprocessing using BoostNanoDecoder choiceOutputOutput formatTrainingHardware requestPrepare training data setTrain a modelTraining parametersTrain on Google Cloud ML engineLocal testingCreate a new bucketUse gsutil to copy the fast5 files to your Cloud Storage bucketTrain model on Google Cloud ML engineDistributed training on Google CLoud ML EngineConfigureTransfer fast5 filesSubmit training requestInstallInstall usingpip(recommended)If you currently have TensorFlow installed on your system, we would advise you to create a virtual environment to install Chiron into, this way there is no clash of versions etc.If you would like to do this, the best options would bevirtualenv, the more user-friendlyvirtualenvwrapper, or throughanaconda. After installing one of these and activating the virtual environment you will be installing Chiron into, continue with the rest of the installation instructions as normal.To install withpip:pip install chironThis will install Chiron, andh5py(required for reading in.fast5files).
Tensorflow need to be install in addition by:pip install tensorflow==1.15or GPU version:pip install tensorflow-gpu==1.15Install from Sourcegit clone https://github.com/haotianteng/chiron.git
cd ChironYou will also need to install dependencies.python setup.py installFor CPU-version:pip install tensorflow==1.15For GPU-version(Nvidia GPU required):InstallCUDAInstallcuDNNInstall tensorflow gpu versionpip install tensorflow-gpu==1.15And then add the Chiron into PYTHONPATH,for convinience you can add it to the .bashrcexport PYTHONPATH=[Path to Chiron/Chiron]:$PYTHONPATHFor alternate/detailed installation instructions for TensorFlow, see thedocumentation.BasecallIf installed frompip:An example call to Chiron to run basecalling is:chiron call -i <input_fast5_folder> -o <output_folder> -m <model_folder>If installed from Github:All Chiron functionality can be run fromentry.pyin the Chiron folder. (You might like to also add the path to Chiron into your PATH for ease of running).python chiron/entry.py call -i <input_fast5_folder> -o <output_folder> -m <model_folder>Test runWe provide 5 sample fast5 files for DNA(courtesy ofnanonet) and 5 sample files for RNA in the GitHub repository and two models (DNA_default and RNA_default) which you can run a test on. These are located inchiron/example_data/. From inside the Chiron repository:python chiron/entry.py call -i chiron/example_folder/ -o <output_folder> -m chiron/model/DNA_default --preset dna-preAnd from v0.5 we have provide a good RNA model for the direct-RNA basecall.python chiron/entry.py call -i <input_fast5_folder> -o <output_folder> -m chiron/model/RNA_default --mode rna --preset rna-preYou can reduce the batch size(defualt is 400) if you have limited RAM/GPU-RAM or extend it, bigger batch size has (very)slightly better result and faster inference speed.python chiron/entry.py call -i <input_fast5_folder> -o <output_folder> -m chiron/model/RNA_default --mode rna --preset rna-pre -b 200Any arguments provided afterward will override the argument in the preset, preset arguments values are:DNA preset arguments value(dna-pre):'start':0,'batch_size':400,'segment_len':400,'jump':390,'threads':0,'beam':30RNA preset arguments value(rna-pre):'start':0,'batch_size':300,'segment_len':2000,'jump':1900,'threads':0,'beam':30PreprocessFor better RNA basecalling result, the fast5 files can be preproceesd usingBoostNano, which is a tool developed by me to segment and remove the polyA and adapter tail.Decoder choice(From v0.3)Beam search decoder: chiron call -i-o  --beam <beam_width>Greedy decoder: chiron call -i-o  --beam 0Beam Seach decoder give a higher accuracy, and larger beam width can furthur improve the accuracy.
Greedy decoder give a faster decoding speed than the beam search decoder:DeviceGreedy decoder rate(bp/s)Beam Search decoder rate(bp/s), beam_width=50CPU2117GPU16521204Outputchiron callwill create five folders in<output_folder>calledraw,result,segments,meta, andreference.result: fastq/fasta files with the same name as the fast5 file they contain the basecalling result for. To create a single, merged version of these fasta files, try something likepaste --delimiter=\\n --serial result/*.fasta > merged.fastaraw: Contains a file for each fast5 file with it's raw signal. This file format is an list of integers. i.e544 554 556 571 563 472 467 487 482 513 517 521 495 504 500 520 492 506 ...segments: Contains the segments basecalled from each fast5 file.meta: Contains the meta information for each read (read length, basecalling rate etc.). Each file has the same name as it's fast5 file.reference: Contains the reference sequence (if any).Output formatWith -e flag to output fastq file(default) with quality score or fasta file.Example:chiron call -i <input_fast5_folder> -o <output_folder> -e fastqchiron call -i <input_fast5_folder> -o <output_folder> -e fastaTrainingThe default DNA model trained on R9.4 protocol with a mix of Lambda and E.coli dataset, and the default RNA model is trained on R9.4 direct RNA kit (-200mV configuration).
If the basecalling result is not satisfying, you can train a model on your own training data set.Hardware request:Recommend training on GPU with TensorFlow - usually 8GB RAM (GPU) is required.Prepare training data set.Using raw.py script to extract the signal and label from the re-squiggled fast5 file.
(For how to re-squiggle fast5 file, checkTombo re-squiggle)If installed frompip:chiron export -i <fast5 folder> -o <output_folder>or directly use the raw.py script in utils.python chiron/utils/raw.py --input <fast5 folder> --output <output_folder> --mode dnaThis will generate a tfrecord file for training when using the chiron_rcnn_train.py and chiron_input.py pipeline.python chiron/utils/file_batch.py --input <fast5 folder> --output <output folder> --length 400 --mode dnaThis will generate several binary .bin file for training when using the chiron_train.py and chiron_queue_input.py pipeline.Train a modelsource activate tensorflowIf installed frompip:chiron train --data_dir <signal_label folder> --log_dir <model_log_folder> --model_name <saved_model_name>or run directly bypython chiron/chiron_rcnn_train.py  --data_dir <signal_label folder/ tfrecord file> --log_dir <model_log>Training parametersFollowing parameters can be passed to Chiron when trainingdata_dir(Required): The folder containing your signal and label files.log_dir(Required): The folder where you want to save the model.model_name(Required): The name of the model. The record will be stored in the directorylog_dir/model_name/tfrecord: File name of tfrecord. Default is train.tfrecords.sequence_len: The length of the segment you want to separate the sequence into. Longer length requires larger RAM.batch_size: The batch size.step_rate: Learning rate of the optimizer.max_step: Maximum step of the optimizer.k_mer: Chiron supports learning based on k-mer instead of a single nucleotide, this should be an odd number, even numbers will cause an error.retrain: If this is a new model, or you want to load the model you trained before. The model will be loaded fromlog_dir/model_name/Train on Google Cloud ML enginelocal testingBefore training the model on cloud ml engine, please check if it is working on local machine or not by following commandsgcloud ml-engine local train \
    --module-name chiron.utils.raw \
    --package-path chiron.utils/  \
    -- --input input_fast5_folder \
    --output output

gcloud ml-engine local train \
    --module-name chiron.chiron_rcnn_train \
    --package-path chiron/If it is working well, please go to next step.create a new bucketBUCKET_NAME=chiron-ml
REGION=us-central1
gsutil mb -l $REGION gs://$BUCKET_NAMEUse gsutil to copy the fast5 files to your Cloud Storage bucketgsutil cp -r raw_fast_folder gs://$BUCKET_NAME/fast5-dataTrain model on google cloud ML engineJOB_NAME=chiron_single_1
OUTPUT_PATH=gs://$BUCKET_NAME/$JOB_NAME
INPUT_PATH=gs://$BUCKET_NAME/train_tfdatagcloud ml-engine jobs submit training $JOB_NAME \
    --staging-bucket gs://chiron-ml \
    --module-name chiron.chiron_rcnn_train \
    --package-path chiron/ \
    --region $REGION \
    --config config.yaml \
    -- \
    --data_dir gs://$BUCKET_NAME/train_tfdata \
    --cache_dir gs://$BUCKET_NAME/cache/train.hdf5 \
    --log_dir gs://$BUCKET_NAME/GVM_modelDistributed training on Google Cloud ML EngineConfigureChange configure.yaml according toGCloud DocsFor example the following configure_multi_gpu.yaml:trainingInput: 
  scaleTier: CUSTOM 
  masterType: standard_p100 
  workerType: standard_p100 
  parameterServerType: large_model 
  workerCount: 3 
  parameterServerCount: 3Will enable 3 workers + 1 master worker with one P-100 GPU in each worker.Transfer fast5 filesFAST5_FOLDER=/my/fast5/
OTUPUT_FOLDER=/my/file_batch/
SEGMENT_LEN=512Transfer fast5 to file batchpython utils/file_batch.py --input $FAST5_FOLDER --output $OUTPUT_FOLDER --length $SEGMENT_LENCopy to Google Cloudgsutil cp -r $OUTPUT_FOLDER gs://$BUCKET_NAME/file_batchSubmit training requestJOB_NAME=chiron_multi_4
DATA_BUCKET=chiron-training-data
MODEL_BUCKET=chiron-model
REGION=us-central1
MODEL_NAME=test_model1
GPU_NUM=4gcloud ml-engine jobs submit training ${JOB_NAME} \
    --runtime-version 1.6 \
    --staging-bucket gs://chiron-model/ \
    --module-name chiron.chiron_multi_gpu_train \
    --package-path chiron \
    --region $REGION \
    --config config_multi_gpu.yaml \
    -- \
    -i gs://$DATA_BUCKET/file_batch \
    -o gs://$MODEL_BUCKET/ \
    -m ${MODEL_NAME} \
    -n ${GPU_NUM}