Package: learna-tools
LEARNA-toolsGenerative RNA Design with Automated Reinforcement Learning.Thelearna_toolspackage provides commandline interfaces for
LEARNA, Meta-LEARNA, Meta-LEARNA-Adapt, and libLEARNA as described in the following publicationsLearning to Design RNA(ICLR'19)Partial RNA Design(Under Review)The original repository of the LEARNA approach can be foundhere.InstallationTo install the current version oflearna_toolsfrom the github repository, first clone the repo as followsgit clone https://github.com/Rungetf/learna_tools.gitAndcdinto the cloned directorycd learna_toolsNext, setup the conda environment to include all requirements withconda env create -f environment.ymlandconda activate learna_toolsThen you can installlearna_toolsinto the nevironment withpip install .libLEARNAlibLEARNA is the most recent algorithm from the LEARNA family of algorithms. It provides an interface to design RNAs for the partial RNA design paradigm.
In essence, libLEARNA can design RNAs from sequence and structure motifs under different objectives.
For more information, take a look into ourbioRxiv paperthat is currently under review.General usageThe general interface to libLEARNA is as followsliblearna --input_file <path to file> [options]To see a list of available command line options, runliblearna -hProgram InputlibLEARNA requires sequence and structure inputs to be defined in an input file with specific tags.
Sequence input follow after a#seqtag, and structure inputs follow after a#strtag.
A typical input file for inverse RNA folding on the Frog Foot example of theEterna100 benchmarkthen looks as follows>Frog Foot
#seq NNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNNN
#str ..........((((....))))((((....))))((((...))))Note:We use the letterNto denote unconstrained positions.You can find the example file for the Frog Foot task in theexamplesdirectory asif_frog_foot_example_liblearna.input.To run libLEARNA on the example you can useliblearna --input_file examples/if_frog_foot_example_liblearna.inputIf you would like to design RNAs from sequence and structure motifs, you can usewhitespacesorX('Xtend here') to mark positions for exploration (denoted $\overset{\ast}{?}$ in our paper).
The input file for the design of theophylline riboswitch constructs for example looks as follows>theophylline riboswitch example
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......which is equal to>theophylline riboswitch example with X
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCAXNNNNNNXNNNNNNNNNNXUUUUUUUU
#str ........NNN(((((.....)))))...NNN((((((((((XNN....X))))))))))XN.......To run libLEARNA on the riboswitch design task, you can useliblearna --input_file examples/riboswitch_design_example.input --min_length 66 --max_length 91To additionally specify a desired GC-content for the design, one can use the--desired_gcoption with a given tolerance via the--gc_toleranceoption.
The default tolerance is set to0.01.
An example call could look as follows:liblearna --input_file examples/riboswitch_design_example.input --min_length 66 --max_length 91 --desired_gc 0.5 --gc_tolerance 0.1Alternatively, a desired GC-content can also be specified in the input file via the#globgctag:>theophylline riboswitch example with GC content
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......
#globgc 0.5Specifiying Multiple InputsYou can define multiple targets in a single input file for libLEARNA.
As an example, we use the Riboswitch design examples from above to design RNAs with multiple desired GC contents.>theophylline riboswitch example 1
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......
#globgc 0.3
>theophylline riboswitch example 2
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......
#globgc 0.4
>theophylline riboswitch example 3
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......
#globgc 0.5
>theophylline riboswitch example 4
#seq AAGUGAUACCAGCAUCGUCUUGAUGCCCUUGGCAGCACUUCA NNNNNN NNNNNNNNNN UUUUUUUU
#str ........NNN(((((.....)))))...NNN(((((((((( NN.... )))))))))) N.......
#globgc 0.6libLEARNA will successively process each task, reporting results whenever a task is done.Command Line OptionsGenerating Multiple CandidatesBy default libLEARNA generates a single solution.
However, one can specify any number of solutions for a given design via the--num_solutions <natural number>option.
The requested number of solutions counts for each individual task provided, in case multiple input tasks are provided.
An example call to libLEARNA then could look as follows:liblearna --input_file examples/if_frog_foot_example_liblearna.input --num_solutions 20Changing the Folding AlgorithmTo change the folding algorithm from RNAfold MFE predictions to RNAfold with MEA predictions, you can use the--algorithmoption.liblearna --input_file examples/if_frog_foot_example_liblearna.input --num_solutions 10 --algorithm rnafold_meaPlotting ResultsYou can directly generate logo plots using theLogomakerPython package.liblearna --input_file examples/if_frog_foot_example_liblearna.input --num_solutions 10 --plot_logoThe plots will by default be saved into theplotsdirectory relative to the current working directory.
However, you can specify a directory for saving plots via the--plotting_dir <path to directory>option.
To visualize plots besides saving, you can use the--show_plotsflag.libLEARNA also supports plotting of the structures viaVARNAvia theplot_structureflag.
This will generate secondary structure plots of all generated solutions.
These plots will also be saved into theplotsdirectory (or the directory for saving plots provided with the--plotting_diroption), and can be directly visualized with the--show_plotsflag.Handling ResultsYou can save the predictions of libLEARNA with the--results_dir <path to directoryoption. libLEARNA allows to select from three output formats:pickle,csv, andfasta.
The output format is specified via the--output_format <string>option.
By default, results are saved in a pandas data frame inpickleformat.
You can specify a comma separated output of the dataframe when choosing thecsvformat.
Thefastaformat outputs a file with the following lines:>ID of task
<sequence>
<structure in dot-bracket format>Limiting the RuntimeYou can limit the runtime of libLEARNA via the--timeout <time in seconds>option.
The provided limit counts for each target if providing multiple input tasks.For resetting the weights of the policy network to their initial values, you can use the--restart_timeout <time in seconds>option.
The algorithm will start from scratch after the provided time.Show all DesignsWhile most of the time w are interested in the solutions, we can also add the--show_all_designsflag to output all the designed candidates.
We note, however, that this option should be used with care because, depending on the specified runtime and the task, there might be a large number of candidates.CM design with libLEARNAYou can use the latest Rfam database CMs as followsmkdir rfam_cmsno go to the directorycd rfam_cmsand download Rfam CMswget https://ftp.ebi.ac.uk/pub/databases/Rfam/CURRENT/Rfam.cm.gzYou can unzip the files withgunzip Rfam.cm.gzThen runcmpress Rfam.cmTo design RNAs that match the Hammrhead ribozyme (Type III) family as described in our recentpaper, you can then for example runliblearna --input_file examples/cm_design.input --num_solutions 20 --cm_design --cm_path rfam_cms/Rfam.cm --cm_name RF00008 --cm_threshold 10 --min_length 50 --max_length 60with the following options--input_file: The sequence and structure restrictions on the design space.--num_solutions: The number of solutions provided by libLEARNA.--cm_design: Flag to design RNAs for a given covariance model.--cm_path: The path to the covariance model database.--cm_name: The name of the covariance model that we want to design RNAs for.--cm_threshold: A bitscore threshold to decide which candidates count as solutions.--min_length: The minimum length of the designed candidates.--max_length: The maximum length of the designed candidates.RRI Design with libLEARNATo run libLEARNA for RRI design, you can use the following callliblearna --input_file examples/rri_design.input --rri_design --rri_threshold 10 --min_length 50 --max_length 60This will use the example design space without any restrictions (unconstrained design space in our paper) with the default target mRNA.
However, you can use a new target via the--rri_targetoption, followed by the target sequence.
The--rri_thresholdparameter allows to set a threshold for the reported canidates.
We use positive numbers here, because the threshold is based on the reward of libLEARNA, however, since we are optimizing for energy, the actual threshold from our example corresponds to an energy threshold of -10.LEARNAThe LEARNA algorithms tackle the inverse RNA folding problem: Given a target secondary structure, find an RNA sequence that folds into the desired structure.Program InputsLEARNA, Meta-LEARNA, and Meta-LEARNA-Adapt either read a secondary structure directly from the commandline, or from an input file, starting with a structure Id, followed by the desired structure in dot-bracket notation.An example input file might look as follows:> Test structure
....((((....))))....All three algorithms, LEARNA, Meta-LEARNA, and Meta-LEARNA-Adapt further support input files with multiple targets.To run LEARNA on the Frog Foot example of the Eterna100 Benchmark, you can calllearna --input_file examples/frog_foot_example.input --min_solutions 1000 --timeout 1000This will run learna until it generated 1000 solutions for the target.UsageThe command line interface for LEARNA, Meta-LEARNA, and Meta-LEARNA-Adapt differs only marginally.
All of the following calls are exemplified using the LEARNA approach, however, you can replacelearnawithmeta-learnaormeta-learna-adaptin all of the calls to run the different approaches.The easiest way of running LEARNA from commandline is to simply calllearna --target_structure "<RNA structure in dot-bracket format>"This will run the LEARNA algorithm on the secondary structure in dot-bracket notation.Note:LEARNA Does not support pseudoknots. The input structure has to be in standard dot-bracket notation, i.e. the input may only contain'.', '(', and ')'.You can use the--num_solutionsargument to define the number of (optimal) solutions that LEARNA should provide.
Using the--hamming_toleranceargument, you can further define a distance (Hamming distance between the input structure and the folded candidate sequence) threshold to ask LEARNA to additionally output all sub-optimal solutions with a distance below the given threshold.For example, the output of the calllearna --target_structure "...(((((....)))))..." --num_solutions 10 --hamming_tolerance 10could look as followsIdtimehamming_distancerel_hamming_distancesequencestructure010.018719900GUCUACAGCUCUCUGUAUUG...(((((....)))))...110.029345800AUUCGAUCCUGCGAUCGCGC...(((((....)))))...210.03349800GCCGGCGUGCUGACGCCCAA...(((((....)))))...310.038753700AAUACUACACCCGUAGUGAA...(((((....)))))...410.047487500CUCGAUGACCCCUCAUCCAC...(((((....)))))...510.052376700CGGCCAUCAUAUGAUGGACG...(((((....)))))...610.11600200GCACUAGCUGGAGCUAGCUC...(((((....)))))...710.12015900ACCAGUUUGUUUAAACUCAC...(((((....)))))...810.12429600GGAGAAGCUCGGGCUUCGGC...(((((....)))))...910.12840200AAUUGGAGCGCUCUCCAUCC...(((((....)))))...1010.024622760.3CUGGGCACUGCGGUGCCCAG((((((((....))))))))1110.042892560.3GAUAUGAUGACAAUCAUCAC....((((((...)))))).Note:The last two predictions are sub-optimal with a Hamming distance of 6 each. The output is sorted by Hamming distance.Command Line OptionsSimilar to libLEARNA, all three versions of the LEARNA approach support plotting and saving the results in different formats.
You can use the same command line options as described for libLEARNA.Further, all three versions support the--timeoutoption, while the--restart_timeoutoption is only available for LEARNA and Meta-LEARNA-Adapt.For a detailed list of all commanline options, you can run<tool> -hwhere tool is one oflearna,meta-learna, ormeta-learna-adapt.Automated Reinforcement LearningLEARNA as well as libLEARNA areautomated reinforcement learningalgorithm that uses an efficient Bayesian Optimization method,BOHB,
to automatically find the best model for solving the RNA design problem. To learn more about automated machine learning, we refer to theautoML website. For more about BOHB, see thedocumentation.