Package: orcapy
ORCAPython scripts that predict and plot the location of the origin of replication (oriC) of circular bacterial genomes based on Z-curve, GC-skew,dnaA-box, and gene location analyses. This README will not explain all of ORCA's methods. All functions, main or helper, are labelled with docs-strings and type-hinting for ease of use. Most functions in ORCA can be used separately as well. For example,calculate_disparity_curvescan be used outside of ORCA, too. As well as all functions for fetching files from NCBI, or plotter functions, etc. Please, see their provided docs-strings for more info.Installing ORCApyTo install ORCApy, simply use:pipinstallorcapyOr download it directly from the PyPi websitehere. The installation and download only include the files present in thesrcfolder.To download the provided Random Forest Classifier, simply use:wgethttps://github.com/ZoyavanMeel/ORCA/blob/main/data/output/machine_learning/ORCA_RFC_model.pkl.gzOr use a similar method, likecurl. You can also download it manually by goinghere, clicking on the three horizontal dots in the top right and selecting 'Download'.ORCA classThis script predicts the origin of replication for circular bacterial DNA. It makes use of a combination ofZ-curveandGC-skew,dnaA-box, and gene location analyses. You can load the required FASTA files yourself, or simply provide an accession and NCBI-account email and ORCA will fetch them. The docs-string of the function shows more information on what is needed to use ORCA. See theExample Usesection for more information.NOTE:the model provided in this repository has been compressed due to file size limitations. This example also uses theJoblibpackage for unpickling the model. This is not necessary, and Python's standard pickle and gzip package can be used as well.InputPlease, make sure to load the proper file formats into the functions, otherwise ORCA will not work. A lot of invalid parameters will throw warnings or errors, but it is not improbable that a few were missed. More of ORCA's functionality and input methods are discussed in the paper.There are four valid input formats for ORCA. Provided one has an internet connection, ORCA can function using only an accession number (from_accession). When using only an accession, ORCA will fetch the corresponding GenBank file from NCBI using Biopython's Entrez module. Please adhere to NCBI's rules on making use of their API. This module functions as a Python interface for NCBI's Entrez Direct. The version number of the accession can be specified. If this is omitted, the most recent version is automatically chosen. One can also provide the GenBank file themselves (from_gbk). This file will be processed the same way, but does not require an internet connection.Another option is to provide Biopython SeqRecord objects (from_pkl). ORCA uses Biopython's SeqIO module for parsing the GenBank file. This means that input from GenBank will go through this module anyway and uses SeqRecords. Providing a SeqRecord that was made by parsing a Genbank file using this same module is therefore also possible. Pickled SeqRecord objects take up more memory, but they can be parsed quicker. This is a consideration that can be taken into account when processing large genomic datasets.Lastly, one can also simply provide a DNA-sequence string (from_string). This same input method allows for indicating the location of the indicator genes. These gene locations are not inferred from the provided sequence and will have to be provided. This is the fastest input format, but takes the most work from the user. All input parameters are assumed to be in the correct specified format and will not be processed using Biopython. Further explanation on each of these formats can also be found in the documentation of the code.Example use of ORCAWith the RFC, we provide a general use-caseoriCprediction tool as outlined in the application note. However, as shown in the code documentation, there are many parameters that can be fine-tuned and possibly improved. One of the reasons of ORCA being open-source, is to provide not just a transparentoriC-prediction tool, but also a building block for further research.It is possible to tune all parameters and train models for highly accurate prediction of theoriCs of bacterial species of interest. This could be done by incorporating more indicator genes for that species, or changing any number of other parameters. It could also be possible to adapt ORCA for the use in the prediction oforiCs in linear prokaryotic chromosomes, or archaea. it is our hope that ORCA can help research into any or all of these avenues with its adaptability or provide a lightweight easy-to-use tool with good out-of-the-box performance.>>>importjoblib>>>fromorcapyimportORCA>>>email="example@email.com">>>model=joblib.load("path/to/model.pkl.gz")>>>orca=ORCA.from_accession("NC_000913.3",email=email,model=model)>>>orca.find_oriCs(show_info=True,show_plot=False)Accession:NC_000913predictions:0.99412Z_scores:1.0G_scores:0.5D_scores:1.0oriC_middles:3927479Thebest-scoringpotentialoriCwasfoundat:3927479bp.If you do not wish to use joblib, you can also open the model using:importgzip,picklewithgzip.open("path/to/model.pkl.gz","rb")asfh:model=pickle.load(fh)In the case ofEscherichia coli(E. coli) K-12, only one potential origin was found and according to the model, this could also be classified as a true origin. Any prediction value >= 0.5, means that the model believes there is a 50 % or more that the corresponding origin is a true origin. It is possible that multiple candidate origins have a probability of being a true origin that is larger than 50 %. Then simply use the origin corresponding to the highest probability, as this was the origin that the model deemed most likely to be correct.This repository also includes a pickledSeqRecordof theE. coliK-12 chromosome. If one wanted to use that, only a different constructor would have to be used.>>>fromorcapyimportORCA>>>orca=ORCA.from_pkl("data/input/NC_000913_3.pkl",model=model)>>>orca.find_oriCs(show_info=False,show_plot=False)There are four constructors in total:from_accession,from_gbk,from_pkl,from_string. Each comes with extensive documentation of how to use them. Once theORCAobject has been instantiated, callfind_oriCsto analyse the sequence.ORCA's parametersThe parameters listed below are parameters that can be used as they are or can be fine-tuned for specific use cases. The standard parameters reflect ORCA's performance as shown in the application note. Retraining of the Random Forest Classifier is recommended if any parameters are changed. Otherwise, the same performance as is the paper can not be guaranteed.dnaa_boxes: If None, will use the consensus DnaA-box:TTAT(A|C|G|T)CACA(see SectionDnaA). Else, provide a list of 9 base strings. Example input:['AAAAAAAAA', 'TTTTTTTTT'].max_mismatches: Maximum allowed mismatches allowed in a dnaa_box for it still to be read as such. Recommended max: 2. ORCA uses 0 for use with the consensus DnaA-box.genes_of_interest: List of gene names to consider as 'oriC-proximal' and use for helping estimate the location of the oriC. This parameter is case insensitive.max_point_spread: Maximum distance between points in a group can have when looking for connected groups across the disparity curves. Default is 5 % of the total chromosome length.windows: The windows around peaks of skew curves to consider. Defaults are 1, 3, and 5 % of the total chromosome length. ORCA checks each of the given windows.model: A fitted scikit-learn classifier. Recommended to use the one provided on in this repository.Libraries and Versions usedPython 3.11.1SciPy 1.10.0Pandas 1.5.3NumPy 1.24.2Biopython 1.80Scikit-learn 1.2.1Matplotlib 3.6.3Peak classThePeakclass. This class is used in handling potentialoriCs. TheoriCs-attribute of anORCAobject consists of a list ofPeakobjects. EachPeakrepresents a potentialoriCand has attributes for its Z-, G-, and D-score as well as the confidence a potential machine learning model has.BioFileScript with useful functions for I/O. These include functions for downloading, parsing, and saving files. To use these function call:fromorcapyimportBioFilePlotterThere are 3 general functions in this file which can be used to plot any generic 1D-np.array. To use these functions, make sure to havematplotlibinstalled.plot_Z_curve_3D: Makes a 3D-plot of the Z-curve.plot_curves: Can plot a maximum of four curves in a single 2D-plot. This one is useful for plotting single or multiple Z-curve or GC-skew components against each other.plot_skew: Does the same asplot_curves, except only takes one array.To use these functions call:fromorcapyimportPlotterMachine_learningThis folder contains a lot of data used in analysing, training, and testing ORCA and its Random Forest Classifier. The DoriC data can be downloaded from:http://tubic.tju.edu.cn/doric/public/index.phpon May 16th, 2023. Each script comes with docs-string explaining their functionality.datainputThis folder contains all the input data. This includes the data from DoriC 12.0. It also includes theexperimental_datasetCSV. This is a collection of oriCs that have been experimentally verified. It also includes sources for each chromosome. This dataset was made in order to check the quality of DoriC.This folder also includes a pickledSeqRecordobject of theE. coliK-12 chromosome. This file was used for quick testing and demonstration.outputThis folder contains output from the various performance test we ran on ORCA. The machine_learning sub-folder contains the provided Random Forest Classifiers. Use the gzip and pickle from the standard Python library to load the models or, alternatively, usejoblib.ORCA_RFC_model.pkl.gz: This model has been trained on the full DoriC 12.0 dataset. This model is included with installation and can be called with theORCA_RFC_modelfunction.ORCA_RFC_model_70_percent.pkl.gz: This model has been trained on roughly 70 % of the DoriC 12.0 dataset. First all the experimentally verified origins were subtracted and the remaining dataset was split 70:30 stratified. This model is has been included for posterity. Use the other model for any analyses.DnaAThe table below shows a small overview of commondnaA-boxes and relevant papers associated with them. This table is by no means complete, but can serve as a starting point for further research. We also include some more papers that were useful in researching the effects of thednaAprotein and its binding sites:[1],[2],[3],[4].We use the first entry in the table below and allow for 0 mismatches in this sequence.SequencePaperYearNotesTTAT(A|C|G|T)CACA[5],[6]2007/8In (roughly) all eubacteria, not justB. subtilisorE. coliTTATCCACA, TTTTCCACA, TTATCAACA, TCATTCACA, TTATACACA, TTATCCAAA[7]1997Affinity study(T|C)(T|C)(A|T|C)T(A|C)C(A|G)(A|C|T)(A|C)[8]1991Only in E. coli K12. Do not use.TGTG(G|T)ATAAC[9]1985Matsui-boxTTAT(A|C)CA(A|C)A[10]1984The first consensus