cual-id

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

https://github.com/caporaso-lab/cual-id

Repository

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

README.rst

=======
cual-id
=======
|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 `__.


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:

.. code:: bash

    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:

.. code:: bash

    source activate cual-id

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

.. code:: bash

    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:

.. code:: bash

    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:

.. code:: bash

    source activate cual-id

Getting help
------------

.. code:: bash

   cual-id --help


Creating a list of IDs
----------------------

.. code:: bash

   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.

.. code:: bash

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

.. code:: bash

   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  output-id  result-codes


For example:

::

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


Python API
----------

.. code:: python

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

.. |Build Status| image:: https://travis-ci.org/johnchase/cual-id.svg?branch=master
   :target:  https://travis-ci.org/johnchase/cual-id
.. |Coverage Status| image:: https://coveralls.io/repos/johnchase/cual-id/badge.svg?branch=master&service=github
   :target:  https://coveralls.io/github/johnchase/cual-id?branch=master
.. |Conda Install| image:: https://anaconda.org/johnchase/cual-id/badges/installer/conda.svg?branch=master
   :target: https://anaconda.org/johnchase/cual-id

Owner

GitHub Events