TARNAS

A TrAnslator for RNA Secondary structure formats

Table of Contents

1. About The Project
   • Built With
2. Citation
3. Getting Started
   • Prerequisites
   • Installation
4. Usage
• GUI Application
• CLI Application
5. Contributing
6. License
7. Credits
8. Contact Information

About The Project

Comparison of molecules, more specifically of RNA secondary structures is essential for several studies including RNA prediction and evolution. These structures are stored in text files which may have different representation formats. Some formats also admit their own header, which is a set of additional information for that molecule. Multiple representation of RNA secondary structures through the use of multiple formats becomes a major problem when those who always work with a specific format find themselves working with masses of data of quite a different format. This constrains the user to perform manual translation work, which is disadvantageous for 2 main reasons: the time taken to perform the translation and the difficulty in the translation itself, hence the ease in making errors during this process. This is where TARNAS comes in: an innovative translator of RNA secondary structure formats that frees users from always using a specific format and thus allowing them to switch from one format to another quickly and easily. With TARNAS, the problem of additional information is also solved: it provides cleanup options to allow the user to remove from the file any information he or she deems unnecessary.

(back to top)

TARNAS is available as:

• standalone application (GUI and CLI)
• web application at this link: https://bdslab.unicam.it/tarnas/

The only difference between the standalone and web application versions is that the standalone version allows users to load multiple files at once, whereas the web app supports uploading only one file per use.

Built With

TARNAS (standalone app) was developed with:

• Java
• ANTLR4
• Maven
• JavaFX

TARNAS (CLI) was developed with:

• Java
• ANTLR4
• Maven
• Picocli

TARNAS (web app) was developed with;

• Java
• ANTLR4
• Maven
• Springboot
• Angular

(back to top)

Citation

Please cite the following works whenever TARNAS is used to produce published results or incorporated into other software:

Conference Paper

Quadrini, M., Hierro Canchari, P., Rosati, P., Tesei, L. (2025).
TARNAS, a TrAnslator for RNA Secondary Structure Formats.
In: Cerulo, L., Napolitano, F., Bardozzo, F., Cheng, L., Occhipinti, A., Pagnotta, S.M. (eds)
Computational Intelligence Methods for Bioinformatics and Biostatistics. CIBB 2024.
Lecture Notes in Computer Science, vol 15276. Springer, Cham.
https://doi.org/10.1007/978-3-031-89704-7_24

bib citation:

@inproceedings{TARNAS2025,
author={Quadrini, Michela and Hierro Canchari, Piero and Rosati, Piermichele and Tesei, Luca},
editor={Cerulo, Luigi and Napolitano, Francesco and Bardozzo, Francesco and Cheng, Lu and Occhipinti, Annalisa and Pagnotta, Stefano M.},
title={TARNAS, a TrAnslator for RNA Secondary Structure Formats},
booktitle={Computational Intelligence Methods for Bioinformatics and Biostatistics},
year={2025},
publisher={Springer Nature Switzerland},
address={Cham},
pages={307--316},
abstract={RNAs are single-stranded molecules that fold into themselves, determining a complex shape to perform their biological functions. Considering the chemical bonds established, such shapes can be abstracted into secondary structures, which are tractable from a computational point of view and encode valuable biological information. The analysis of such structures, including comparison and classification, plays a fundamental role in different biological studies. Unfortunately, the available tools take secondary structures as input using different formats, making the translation among different them a necessary step in every analysis.},
isbn={978-3-031-89704-7},
doi={10.1007/978-3-031-89704-7_24}
}

Journal Paper

Quadrini, M., Canchari, P. H., Rosati, P., & Tesei, L. (2025). TARNAS: A Software Tool for Abstracting and Translating RNA Secondary Structures. International Journal of Molecular Sciences, 26(12), 5728. https://doi.org/10.3390/ijms26125728

bib citation:

@article{TARNAS_IJMS2025,
author = {Quadrini, Michela and Canchari, Piero H. and Rosati, Piermichele and Tesei, Luca},
title = {TARNAS: A Software Tool for Abstracting and Translating RNA Secondary Structures},
journal = {International Journal of Molecular Sciences},
volume = {26},
year = {2025},
number = {12},
article-number = {5728},
doi = {10.3390/ijms26125728},
publisher = {MDPI}
}

(back to top)

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Prerequisites

To run TARNAS, the following requirements must be met.

• Java 19

If you want to run the program via Maven:

• Maven

Installation

You can install TARNAS in several ways:

• Clone the repo

  git clone https://github.com/bdslab/TARNAS

• Alternatively, download the latest release from TARNAS latest release. Here you can download:

  • TARNAS.jar
  • TARNAS_CLI.jar
  • Source code (zip)
  • Surce code (tar.gz)

  It's recommended to download just the jar file TARNAS.jar and/or TARNAS_CLI.jar.

(back to top)

USAGE

GUI Application

• If you cloned the repo, you can use Maven to execute TARNAS.
  Position yourself inside the TARNAS folder, which contains the pom.xml, and type the following command:

  mvn clean javafx:run

• If you downloaded the TARNAS.jar from the latest release, you can use Java to execute TARNAS.
  Position yourself inside the folder that contains the jar executable file, and type the following command:

  java -jar TARNAS.jar

TARNAS GUI works as follows:

1. It takes a text file as input representing an RNA secondary structure. the file consists of a header (described by comments) and a body (which is the molecule in that representation).

   The user can upload:

   • a text file via the ADD FILE button.
   • a folder containing multiple text files via the ADD FOLDER button.
   • or directly write the contents of the file via EDIT FILE button. In this case, a window will appear where the user can type in the content of the molecule to be represented. Once this has been represented, the programme will ask the user to enter a name for this file (by default example.ct is entered)

   All uploaded files must have the same format. TARNAS does not provide translation or cleaning options between multiple files of different formats.

   The user can also remove all uploaded files via the `RESET button`.

2. Once one or more files have been uploaded, the user can perform either the cleaning operation or the translation operation (not both atomically).

   This means that cleaning and translation cannot be done at the same time. In this case, it is necessary to perform the cleanup operation first, then reload the cleaned files, and then perform any translation.
   
   When one or more files have been loaded within the program, they are displayed within a table that has the following header:

| File Name | Format | Remove | Preview |

Each row in this table will therefore contain an uploaded file with the following information and options:

• File Name: the name of the uploaded file
• Format: the file format based on the file content
• Remove: an option to delete that file
• Preview: an option to visualize the content of the file
  
  

3. CLEANING OPTIONS: they are on the left side of TARNAS and allow the user to:

   • remove all comments: any comments that form the header are removed.
   • remove lines containing: the user inputs a word and every comment that forms the header and contains the word given as input by the user is deleted.
   • remove empty lines: all lines that contain blank spaces (spaces, tabs) are deleted.
   • merge lines: this option is enabled only in Dot-Bracket format (with or without sequence). Since in these formats the sequence and structure can be represented on multiple lines, therefore the option is provided to merge all lines into a single line.

   Once the desired cleaning options have been selected, you must press the CLEAN button to start cleaning on the uploaded files.

   At this point, the user will be asked to choose where to save the cleaned files, and if successful, a report will be shown of the number of files cleaned and saved in the location specified by the user. 4. TRANSLATION OPTIONS: they are on the center side side of TARNAS and allow the user to translate a file from one format to another.
   Allowed translations:

   	Dot-Bracket no seq.	Dot-Bracket	BPSEQ	Fasta	AAS	AAS no seq.	CT	RNAML
   Dot-Bracket no seq.	-	X	X	X	X	✓	X	X
   Dot-Bracket	✓	-	✓	✓	✓	✓	✓	X
   BPSEQ	✓	✓	-	✓	✓	✓	✓	X
   Fasta	X	X	X	-	X	X	X	X
   AAS	✓	✓	✓	✓	-	✓	✓	X
   AAS no seq.	✓	X	X	X	X	-	X	X
   CT	✓	✓	✓	✓	✓	✓	-	X
   RNAML	✓	✓	✓	✓	✓	✓	✓	-

   You can select the include header checkbox if you want to keep the header during translation.
   Moreover, only for RNAML file format it's possible to generate non canonical pairs.
   TARNAS also allows to generate statistics like nucleotide count, bond count, A,C,G,U count and so on, for all formats.
   Also you can save all the translated files in a zip file to reduce the space occupied by them, to do this just select the save as zip checkbox and then name the zip file.
   When all translation options have been selected, you can start the translation through the TRANSLATE button.

4. ABSTRACTIONS OPTIONS: they are on the right side side of TARNAS and allow the user to abstract a Dot-Bracket or Dot-Bracket file format in three views:

   • Core
   • Core plus
   • Shape

   For more information on the Core, Core+ and Shape abstractions, please refer to the related publication.

CLI Application

• If you downloaded the TARNAS_CLI.jar from the latest release, you can use Java to execute TARNAS.
  Position yourself inside the folder that contains the jar executable file, and type the following command:

  java -jar TARNAS_CLI.jar

TARNAS CLI works as follows:

• The user can execute one of the following commands with one or more options.

• TRANSLATION command:

  • Translates to DB format:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB

  • Translates to DB format, the header is discarded:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB --no-header

  • Translates to DB format and generates a file storing all non-canonical pairs (if any). The output file retains the original input filename with ‘_nc.csv’ appended at the end:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB --non-canonical-pairs

  • Translates to DB format and generates a statistics file based on molecule pair data:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB --statistics

  • All the previous options can be used at the same time:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB --no-header --statistics --non-canonical-pairs

  • Previous commands can be used with other formats too:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate AAS

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate AAS_NO_SEQUENCE

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate BPSEQ

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate FASTA

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate RNAML

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate CT

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> translate DB_NO_SEQUENCE

• CLEANING command:

  • Removes all comments, lines that start with '#' or '>':

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> cleaning --comments

  • Removes all blank lines:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> cleaning --empty

  • Removes all lines that contain a specific string:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> cleaning --lines=<stringToBeRemoved>

  • Sometimes DB files have the sequence split across multiple lines, this command merges them into a single line. This command can be used only for DB or DB_NO_SEQUENCE files:

    java -jar TARNAS_CLI.jar <inputPath_DB> <outputDirectoryPath> cleaning --merge

    or

    java -jar TARNAS_CLI.jar <inputPath_DB_NO_SEQUENCE> <outputDirectoryPath> cleaning --merge

• ABSTRACTIONS command:

• Computes core, core plus and shape:

  java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions

  • Computes core only:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions --core

  • Computes core plus only:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions --coreplus

  • Computes shape only:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions --shape

  • The following 2 commands are equal:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions --core --coreplus --shape

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> abstractions

• SAVE AS ZIP:

  In all commands explained previously, it is possible to save the result into a zip file. To do so, include ‘--zip ’

  • Translation and saving as zip:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> --zip <zipFileName> translate DB

  • Cleaning and saving as zip:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> --zip <zipFileName> cleaning --comments

  • Abstractions and saving as zip:

    java -jar TARNAS_CLI.jar <inputPath> <outputDirectoryPath> --zip <zipFileName> abstractions

If you need help or want to see the available options, you can run the command:

  java -jar TARNAS_CLI.jar -h

or

  java -jar TARNAS_CLI.jar --help

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

Distributed under the GNU License. See LICENSE.txt for more information.

(back to top)

Credits

TARNAS is developed and tested by:

• Piero Hierro, University of Camerino
• Piermichele Rosati, University of Camerino
• Luca Tesei, University of Camerino

TARNAS is tested by:

• Michela Quadrini, University of Camerino

(back to top)

Contact Information

Please report any issue to luca.tesei@unicam.it or to Luca Tesei, Polo Informatico, via Madonna delle Carceri 7, 62032 Camerino (MC) Italy.

(back to top)