Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status Conda Install

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.



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 -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


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


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


A package for creating and managing sample identifiers in comparative -omics datasets.







No packages published