Skip to main content

User Documentation and Tutorials

This document provides guidance and information about:

  • How Do I Create User Accounts?
  • How Do I Upload Reference Genome and Data Tracks?
  • How Do I Prepare My Data Track?
  • What Data Files Are Required To Create Tracks In Apollo?
  • How Do I Create Tracks In Apollo?
  • How Can I Publish My Genome?
  • How Do I Manually Annotate My Genome In Apollo?

How Do I Create User Accounts?


Only project administrators can add or remove user accounts.

To add a user account:

  1. Log into the Apollo Instance via the GUI using your project admin account
  2. Click on the “User” tab
  3. Click on “+ Create User”
  4. Click on the “Detail” tab and add the following information:
    • First Name
    • Last Name
    • Email
    • Password
    • Role: Choose from “user” or “admin”
  5. Click on the “Groups” tab
    • Assign the user to a group (optional)
    • Assign the user permissions for an organism. This can only be done after the organism has been added to the Apollo Instance

How Do I Upload Reference Genome and Data Tracks?


There are a number of methods to upload reference genome to get your organism genome into the Apollo Instance. Reference genome can be uploaded through one of three ways, via the Apollo graphical user interface, via CloudStor or the via command line or terminal on your local machine. Instructions for each of these methods are listed below:

  1. Uploading data via your Apollo Instance graphical user interface:
    1. Log into your Apollo Instance
    2. If the Apollo Instance is newly built, please follow one of the instructions below to upload your reference genome
      1. 1c) to upload your reference genome
      2. 1d) to upload your tracks only if the step 1c) is comopleted
    3. In the 'Annotator Panel' to the right-hand side of the view and click on 'Organism' tab.
      1. Click on the "Upload New Organism" buttom at the bottom of the right-hand side panel
      2. Follow the instruction on the pop-up menu to upload your reference genome
      3. Click on "Upload" button when finished
    4. In the ‘Annotator Panel’ to the right-hand side of the view and click on ‘Track’ tab
      1. Click on “New Track” button
      2. Select Track Type
      3. Provide the information of the upload track (i.e GFF3)
      4. Click On "Upload" button when finished
  2. Uploading data via CloudStor:
    1. The Project Administrator requires a CloudStor account and there are two options for sharing reference genome and evidence files with the Apollo team.
    2. Option 1, upload files to Apollo team’s shared CloudStor folder:
      1. Share the email address connected to your CloudStor account with the Apollo team;
      2. The Apollo team will share a folder named ‘Host Name Apollo Files’ to the Project Administrator’s via CloudStor account;
      3. Login to your CloudStor account and locate the folder named ‘Host Name Apollo Files’ and upload your reference genome and evidence files into the folder;
      4. Notify the Apollo team via help@genome.edu.au your reference genome and evidence files have been uploaded to the CloudStor folder.
    3. Option 2, create and share your CloudStor folder:
      1. Login to your CloudStor account and create a new folder by clicking on the white plus sign in the orange box;
      2. Upload your reference genome and evidence files into the folder;
      3. Share the folder with the Apollo team via help@genome.edu.au.
    4. The Apollo team will move the data tracks into your Apollo Instance
    5. Please contact your project administrator to make your reference genome and data tracks displaying on the Apollo Instance
    6. See the CloudStor FAQs for help and guidance on using CloudStor.
  3. Uploading data using the command line or terminal:
    1. The Project Administrator requires a public SSH key for each user to access the backend via the command line. To create a keypair follow one of the options spending on your local
    2. To create a keypair on your Unix/Linux/MacOS/Windows subsystem for Linux, use the following commands on your local machine (the computer that you will be accessing the Apollo Instance from):
    3. >ssh-keygen -t rsa -f ~/.ssh/firstname_lastname_key
      >chmod 600 ~/.ssh/firstname_lastname_key
      >cat ~/.ssh/firstname_lastname_key.pub

    4. The output of the last command is the public key. Please note that you should never give out the private key, which is stored in ~/.ssh/ as above.
    5. Notify the Apollo team via help@genome.edu.au of your public key
    6. Login credentials will be provided by the Apollo team
    7. The Project Administrator with the login credential is responsible for uploading the data tracks and managing the data tracks via the terminal.

How do I Prepare My Data Track?


Apollo is a Genome Browser. It allows you to visualise evidence from analyses on a genome, create and edit genes, and create and edit annotations on those genes. The reference genome in FASTA file format and the genome annotation in GFF file format are needed to view the genome in the Apollo browser. The reference genome can be obtained from the public repository or generated from any genome assembly workflow. The genome annotation describes genes and other features of DNA, RNA and protein sequences. The genome annotation can be generated using any genome annotation workflow. For the evidence tracks such as alignment file (BAM), variant file (VCF) and genome coverage file (Bigwig), they should be prepared using the appropriate workflows before uploading into your Apollo Instance.

This section outlines the steps required to prepare a track file for Apollo. In order to create tracks in your Apollo instance you must provide the following files:

  1. Organism files:
    1. Genome reference file (fasta, fa, fna)
    2. Genome reference indexing file (fai). It can be yielded from running the following command in the Samtools suite of programs:

      >samtools faidx [species.fasta]

    3. Genome sequence file in binary format (2bit). The 2bit file can be created using the following command in the faToTwoBit program:

      >faToTwoBit [species.fasta] [species.2bit]

  2. Genome annotation files:
    1. Genome annotation file (gff3) generated from the annotation process.
    2. Genome annotation compressed file (gz). This file can be compressed by running the following commands in the Samtools suite of programs:

      >bgzip [species.sorted.gff3]
      >tabix -p gff [species.sorted.gff3.gz]

  3. Evidence track files:
    1. Alignment file (bam)
    2. Alignment index file (bam). The index file can be yield from running the following commands in the Samtools suite of programs:

      >samtools index [species.bam]

  4. Variant files:
    1. Variant calling file (vcf) generated from the variant calling process.
    2. Variant calling index file (vcf.gz). The variant calling index file of the variant calling file. The index file can be created running the following commands in theSamtools suite of programs:

      >bgzip [species.vcf]
      >tabix -p vcf [species.vcf.gz]

  5. BigWig files are compressed, indexed, binary format of genome-wide signal data. They can be created by running the following commands in the bedtools suite of programs:

    >bedtools genomecov -ibam -bg -split -strand + -I [species.bam] -g Chrominfo.txt > [species.plus.bedGraph]
    >bedtools genomecov -ibam -bg -split -strand - -I [species.bam] -g Chrominfo.txt > [species.minus.bedGraph]
    >bedGraphToBigWig [species.plus.bedGraph] Chrominfo.txt [species.plus.bw]
    >bedGraphToBigWig [species.minus.bedGraph] Chrominfo.txt [species.minus.bw]

What Data Files are Required to Create Tracks in Apollo?


This section provides a list of the available file formats that can be used with Apollo

File Format Description Requirement
Fasta Genome Reference File Mandatory
Fai Genome Reference Index File Mandatory
2bit Genomic Sequence in Binary File Mandatory
Gff Genome Annotation File Mandatory
Gff.gz Genome Annotation Compressed File Mandatory
Bam Alignment File Optional
Bai Alignment Index File Optional
Vcf Variant Calling File Optional
Vcf.gz Variant Calling Index File Optional
bw A compressed, indexed, binary format of genome-wide signal data Optional

How Do I Create Tracks in Apollo?


Tracks can be created by uploading track data files through one of three ways, via the Apollo graphical user interface, via CloudStor or the via command line or terminal on your local machine. Instructions for each of these methods are listed below:


  1. Uploading data tracks via your Apollo Instance graphical user interface:
    1. Prepare track data (see [How Do I Prepare My Data Track?])
    2. Log into your Apollo Instance
    3. Navigate to ‘File’ in the blue menu at the top left of the Instance.
      1. From the drop down menu, select ‘Open track file or URL’ to upload track data (i.e. bam, vcf, bed, gff, or bigwig).
      2. Select ‘Open’.
  2. Uploading data tracks via CloudStor:
    1. Prepare track data (see [How Do I Prepare My Data Track?])
    2. The Project Administrator requires a CloudStor account and there are two options for sharing data tracks with the Apollo team.
      1. Option 1, upload files to Apollo team’s shared CloudStor folder:
      2. Share the email address connected to your CloudStor account with the Apollo team;
      3. The Apollo team will share a folder named ‘Host Name Apollo Files’ to the Project Administrator’s CloudStor account;
      4. Login to your CloudStor account and locate the folder named ‘Host Name Apollo Files’ and upload your evidence files into the folder;
      5. Notify the Apollo team via help@genome.edu.au the evidence files have been uploaded to the CloudStor folder.
    3. Option 2, create and share your CloudStor folder:
      1. Login to your CloudStor account and create a new folder by clicking on the white plus sign in the orange box;
      2. Upload your evidence files into the folder;
      3. Share the folder with the Apollo team via help@genome.edu.au.
    4. The Apollo team will move the data tracks into your Apollo Instance
    5. See the CloudStor FAQs for help and guidance on using CloudStor.
  3. Uploading data tracks using the command line or terminal:
    1. Prepare track data (see [How Do I Prepare My Data Track?])
    2. The Project Administrator requires a public SSH key for each user to access the backend via the command line. To create a keypair follow one of the options spending on your local
    3. To create a keypair on your Unix/Linux/MacOS/Windows subsystem for Linux, use the following commands on your local machine (the computer that you will be accessing the Apollo Instance from):

      >ssh-keygen -t rsa -f ~/.ssh/firstname_lastname_key
      >chmod 600 ~/.ssh/firstname_lastname_key
      >cat ~/.ssh/firstname_lastname_key.pub

    4. The output of the last command is the public key. Please note that you should never give out the private key, which is stored in ~/.ssh/ as above
    5. Notify the Apollo team via help@genome.edu.au of your public key
    6. Login credentials will be provided by the Apollo team
    7. The Project Administrator with the login credential is responsible for uploading the data tracks and managing the data tracks via the terminal.
    8. Once access has been granted, navigate to the folder ’apollo_data’ with one of the following command:

      >cd ~/data
      >cd /home/data/apollo_data

    9. Transfer or upload your data into this folder. Be sure to include all of the files listed as mandatory as listed in the table in [What Data Files are Required to Create Tracks in Apollo?]
    10. To copy a single file to the ‘apollo_data’ folder, you can use:

      >cp ~/home/apollo_data
      ~/username/apollo_files/[species.bam]

    11. To copy a complete directory of files in a folder, including subfolders and their files, to the ‘apollo_data’ folder you can use:

      >cp -R ~/home/apollo_data ~/username/apollo_files/

    12. While in the folder ‘apollo_data’, create a new folder for your organism named ‘organism_A’ using the following command:

      >mkdir organism_A

    13. Navigate into the folder named ‘organism_A’ and make sure the genome reference file (fasta and faidx) and the annotation file (gff3 and gff3.gz) are in this folder.
    14. Prepare the config file with the following commands:

      >Prepare-refseqs.pl –fasta [Organism_A.fa]
      >Flatfile-to-json.pl –tracklabel [Organism_A] –key “Organism_A” –gff Organism_A.gff3 –trackType CanvasFeatures –type CDS –autocomplete all
      >Generate-name.pl

    15. For further instructions about configuring track data files, you can read through the official Apollo documentation of data loading.

How Can I Publish My Genome?


A genome can be published via via your Apollo Instance graphical user interface:

  1. Log into your Apollo Instance
  2. In the ‘Annotator Panel’ to the right-hand side of the view and click on ‘Organism’ tab.
  3. Tick the ‘Public’ box at the bottom of the ‘Detail’ tab.

How Do I Manually Annotate My Genome in Apollo?


Detailed documentation on the use of Apollo for manual annotation can be found in the Apollo User’s Guide. See also tutorials on manual genome annotation and Apollo in the Training and Help Resources’ tab.
https://apollo-portal.genome.edu.au/resources1.