cual-id

Citing cual-id

Please cite this article if you use cual-id in any published work with the following citation:

cual-id: Globally Unique, Correctable, and Human-Friendly Sample Identifiers for Comparative Omics Studies John H. Chase, Evan Bolyen, Jai Ram Rideout, J. Gregory Caporaso mSystems Dec 2015, 1 (1) e00010-15; DOI: 10.1128/mSystems.00010-15

cual-id: Globally Unique, Correctable, and Human-Friendly Sample Identifiers for Comparative Omics Studies.

Install

Miniconda

We strongly recommend installing cual-id using Miniconda. which greatly simplifies Python package management. To do this, you should first choose which version of Miniconda to install from the install page. You can choose either the Python 2 or 3 version. After you've installed Miniconda, you should run:

conda create -c https://conda.anaconda.org/johnchase -n cual-id python=3 cual-id

After this completes (it should take less than a minute), you can activate your cual-id environment by running:

source activate cual-id

Then, to see the available cual-id commands, run:

cual-id --help

pip

If you prefer to install with pip, and already have a Python 3 development environment configured, you can do this with the following command:

pip install cual-id

Usage

Activating your environment

If you installed cual-id using Miniconda, to start using cual-id you'll need to run the following command when you open a new terminal:

source activate cual-id

Getting help

cual-id --help

Creating a list of IDs

cual-id create ids 42 # writes 42 ids to stdout
cual-id create ids 42 > my-ids.txt # writes 42 ids to my-ids.txt
cual-id create ids 42 --existing-ids my-ids.txt # creates ids that do not
# overlap with existing ids. Note this will only compare new ids to the first
# column of the file

Creating a PDF of ID labels

If you need to label sample containers with stickers, you can create a printable PDF for those stickers. Currently the only sticker sheet format supported is a 4 by 9 sheet. We designed this printout for Electronic Imaging Materials #80402 label sheets. When printing PDFs make sure to check Actual Size in the print dialog box.

cual-id create labels my-ids.txt --output-pdf my-labels.pdf
cual-id create labels my-ids.txt --output-pdf my-labels.pdf --suppress-ids # don't print the ids, only the barcodes
cual-id create labels my-ids.txt --output-pdf my-labels.pdf --barcode none # don't print barcodes, just the ids

Correcting a list of ids

cual-id fix examples/modified-ids.txt --correct-ids examples/ids.txt # report fixed, unfixable and duplicates, the default
cual-id fix examples/modified-ids.txt --correct-ids examples/ids.txt --show FN # report only fixed and unfixable IDs

Result code definitions

• D: duplicate
• F: fixed
• N: not fixable
• V: valid (didn't need correction)

Output Format

input-id <tab> output-id <tab> result-codes

For example:

1a529f8b     1a529f88        F
d60d0e2b     d60d0c2b        F
439628o9     43962809        F
439628o9     43962809        DF
df47deb4     df47deba        F

Python API

from cualid import create_ids
create_ids(10, 7) # Creates a list of tuples containing a UUID and a cualid