To assemble a sample, RiboPilot compares its reads with known ribosomal sequences from a reference database of related organisms. A new project has no usable database until you build one in the app’s Reference step. You do not need to find or format any sequences yourself, and a database can be reused by every later project on that group.
The Reference step
The Reference step comes between the Taxonomy and Assemble steps. Set up a database for every group before you assemble.
After resolving the sample taxonomy, open the Reference step and press Propose groups. RiboPilot looks at each sample’s lineage and groups samples that can share one reference database. RiboPilot picks the narrowest group containing your samples that contains at least at least 1,000 GenBank rDNA records. Samples from very different parts of the tree end up in different groups, each with its own reference database.
After defining groups, the Reference page automatically switches from a samples table to a groups table. Each row is one proposed group. The Status column says where that group stands (“Needs a database”, “Building”, “Ready”, “Build failed”, or “Left on current database”), and the rest of the row shows the clade, how many of your samples it covers, how many GenBank records matched the clade’s search (# GenBank Hits), and, once built, how many sequences the database holds (# Database Sequences). The second number is usually much smaller: the build keeps one copy of each identical sequence and drops short records. RefSeq genome annotations list many identical rDNA copies per genome, so a clade with many sequenced genomes can lose most of its hits this way. For example, Actinopteri had about 43,900 hits but built to about 12,100 sequences.
Setting a group up
The link at the right-hand end of each row says what that group needs: Set up database, Try again, or Change. Click it and you are offered four choices:
- Download sequences from GenBank. The normal choice. Opens a run window, then press Run from App to download the database. When the build finishes, RiboPilot points the group’s unlocked samples at the new database. A database that already exists in your reference folder is automatically used, not rebuilt.
- Use a database I already have. Points the group at a database built earlier, in this project or by someone else sharing the reference folder.
- Change which clade this group uses. Lists the group’s lineage from the broadest rank to the narrowest. Pick another rank to widen or narrow the group, or search for another clade. If some samples in the group are not contained in the clade you select, they are split off into a different group. Clicking the group’s Clade cell opens the same window.
- Leave these samples on their current database. Nothing is built. Use it only when you have already set a database in these samples’ Assembly Options yourself.
To handle several groups at once, tick their rows first, then click the link on any one of them. The “change clade” option is offered only for a single group.
If you press Update in the Assemble step while some groups have no database, RiboPilot warns you but goes ahead, and those samples fail.
The reference folder
Built databases live in a reference folder that can be shared across projects. You can set the location of the reference folder using the Settings button (which also lets you adjust the minimum and maximum record counts the grouping step uses). Or you can set the reference folder when you create a project.
RiboPilot::new_project(
path = "~/my_project",
mapping_fn = "~/my_samples.csv",
data_path = "~/my_reads",
ref_dir = "~/ribopilot_refs"
)If you do not set a folder, RiboPilot uses a folder in your home
directory. RiboPilot::ribopilot_ref_dir() prints the folder
path.
On a cluster, we recommend setting the reference folder somowhere other than your home directory where disk quotas are lower: see Disk space, caches, and offline use.