VARAN - Quickstart

Quickstart using Docker container

Requirements

Software Requirements:

Docker

Hardware Requirements:

~3 GB storage space for the container image.
~2 GB storage space for the VEP cache and the reference genome.

Getting Started with Varan

We will guide you through a comprehensive tutorial that covers everything from installing Varan using Docker (for instructions on local installation, please refer to this guide), to creating and managing studies, offering a practical introduction to the core functionalities of the tool.

Step 1: Clone Varan repository

Follow the steps below to clone and set up the Varan repository:

Open a terminal on your system.
Navigate to the directory where you would like to install the repository. You can do so by using the cd command followed by the desired path.

Once you're in the desired directory, you can proceed by running the following commands:

git clone https://github.com/bioinformatics-policlinicogemelli/Varan.git

Before proceeding, ensure that Docker is running on your system. You can verify this by checking if the Docker service is active. If Docker is not running, start the Docker service before continuing.

Once Docker is running, navigate to the repository and build the Docker container:

cd Varan

docker build -t varan .

Test the installation with the following command:

docker run --rm -it varan -h

If the installation was successful, you should see the help output for the Varan container. This confirms that the container is correctly set up and running.

⚠️ For Windows users: Some issues with Git Bash have been reported. It is recommended to launch the docker command through Powershell.

Step 2: Download the example data

To download test data follow the steps below:

Download all the necessary files at this link.
Move TEST.zip folder in Varan folder.
Unzip TEST.zip.

The 'TEST' folder contains the following subfolders:

Genome: includes the reference sequence for chromosome 2 only.
Input: includes all necessary input files for processing. These files are synthetic.
Output: empty folder to store our test outputs.
Vep_cache: stores transcript models, regulatory features, and variant data for Homo sapiens, limited to chromosome 2.

⚠️Note: This reduced dataset is intended for lightweight testing and demonstration purposes only.

Step 3: Create a new study

To create your first study, run the following command:

docker run --rm -it -v ./TEST:/test_folder -v ./conf.ini:/conf.ini  varan -i test_folder/Input -o test_folder/Output/output_test -c mixed

⚠️ Watch out for paths! Depending on your Docker version and your OS, you may need to use absolute paths instead of relative ones in the volume mapping. Using relative paths might result in an error when mounting directories.

After about 2 minutes, the output_test_v1 folder will be ready.

Congratulations on completing your first Varan study! You can take some time to explore the output files.

Step 4: Modify an existing study

Now we can manipulate the output_test_v1 study and explore other Varan functions.

Step 4.1: Extract samples from an existing study

You can create a new study by extracting specific samples from an existing study.

Create a list of the desired samples:

nano TEST/Input/extract_list.tsv

In the editor, type the sample IDs:

0000001_DNA
0000002_DNA

To save and close the file, press Ctrl + X (or control + X on Mac). When prompted to save changes, press Y to confirm. Finally, press Enter to save the file and exit the editor.

Extract the samples using:

docker run --rm -it -v ./TEST:/test_folder -v ./conf.ini:/conf.ini  varan -e -p test_folder/Output/output_test_v1 -s test_folder/Input/extract_list.tsv -o test_folder/Output/extract_study

The new extract_study_v1 folder contains a study with the selected samples.

Step 4.2: Remove samples from an existing study

You can create a new study by removing specific samples from an existing study.

Create a list of the samples to remove:

nano TEST/Input/remove_list.tsv

In the editor, type the sample IDs:

0000001_DNA
0000002_DNA
0000003_DNA

To save and close the file, press Ctrl + X (or control + X on Mac). When prompted to save changes, press Y to confirm. Finally, press Enter to save the file and exit the editor.

Remove the samples using:

docker run --rm -it -v ./TEST:/test_folder -v ./conf.ini:/conf.ini  varan -r -p test_folder/Output/output_test_v1 -s test_folder/Input/remove_list.tsv -o test_folder/Output/remove_study

The new remove_study_v1 folder contains a study with the original samples, excluding the ones that were removed

Step 4.3: Merge two existing studies

You can create a new study by merging two existing studies and updating the information.

To merge the remove_study_v1 and extract_study_v1 studies, use the following command:

docker run --rm -it -v ./TEST:/test_folder -v ./conf.ini:/conf.ini varan -u -p test_folder/Output/extract_study_v1 -n test_folder/Output/remove_study_v1 -o test_folder/Output/output_test

Since the output folder name output_test coincides with an already existing folder, a new version of the folder will be created automatically. The resulting folder will be named output_test_v2, containing the merged samples from both input studies.

Now that you've completed the quickstart tutorial, you can explore advanced features in the full user guide.