qpcr - Getting Started
In this Notebook you will get some basic introduction to using the qpcr module. Including an overview of the main and submodules, input data and resulting outputs.
Installing qpcr
qpcr can be directly installed via pip using
pip install qpcr
Basic structure of qpcr
The qpcr module consists of the “main” module that essentially defines everything you need to work with your data and compute Delta-Delta-Ct values for your assays. However, it does not do so on its own but relies on a number of submodules to achieve this. For some features you will also directly have to work with these submodules.
Module |
Description |
|---|---|
|
The main |
|
Defines default settings and values for |
|
Defines the classes that will help read your input data files. |
|
Defines classes that will allow you to quickly and easily visualise your results. |
|
Defines classes that allow you to filter out bad Ct values from your assays. |
|
Defines classes that allow you to extract data from “irregular” datafiles ( |
|
Contains pre-implemented pipelines that assemble fully-working |
Input Data
qpcr is able to read input datafiles in both csv and excel format. As described in the API documentation, there are multiple types of input datafiles that qpcr can work with.
“Regular” single-assay files
Contain a replicate identifier and Ct column from a single assay.
id |
Ct |
other_data |
|---|---|---|
ctrl1 |
5.67 |
… |
ctrl2 |
5.79 |
… |
ctrl3 |
5.86 |
… |
condA1 |
5.34 |
… |
… |
… |
… |
Note
If only two columns are present in the file, then no column names need to be passed but they must be in the order:
id (1st) Ct (2nd)!
“Irregular” files
“Irregular” files may either contain one single dataset or multiple datasets. Note, we will use the term “assay” henceforth to talk more intuitively about the more formally correct “dataset”. Files that specify multiple assays are called “multi-assay files”. They specify each assay in a separate table (separated either by at least one blank row or column between them). However, the architecture of the indivdual tables is still that of the “regular”.
Some meta-data here |
maybe today’s date |
||
Assay 1 |
|||
id |
Ct |
other_data |
|
ctrl1 |
5.67 |
… |
|
ctrl2 |
5.79 |
… |
|
… |
… |
||
<- blank line here! |
|||
Assay 2 |
|||
id |
Ct |
other_data |
|
ctrl1 |
10.23 |
… |
|
ctrl2 |
10.54 |
… |
|
… |
… |
Note
This setup also works transposedly (i.e. assays are next to each other instead of above one another, but it does require that the assay identifiers are either in the same row or colum!)
Also, the column names are important for file reading and must be specified.
“Big Table” Files
“Big Table” files contain are multi-assay files that specify all their assay in one single “big table”. There are two kinds of “Big Table” files called vertical or horizontal. Big Table files are considered “irregular” so they allow additional meta-data etc. alongside the actual “big table”.
Vertical Big Table Files
Contain a replicate identifier, a Ct value, and an assay identifier column. Replicate groups are thus “vertically” arranged.
assay |
id |
Ct |
other_data |
|---|---|---|---|
assay 1 |
ctrl1 |
5.67 |
… |
assay 1 |
ctrl2 |
5.79 |
… |
… |
… |
… |
… |
assay 2 |
ctrl1 |
10.23 |
… |
… |
… |
… |
… |
Note
This requires column names for file reading!
Horizontal Big Table Files
Contain replicate identifier and assay identifier columns but specify the actual Ct values in side-by-side neighbouring columns. Thus replicate groups are arranged “horizontally”.
assay |
ctrl1 |
ctrl2 |
… |
other_data |
|---|---|---|---|---|
assay 1 |
5.67 |
5.79 |
… |
… |
assay 2 |
10.23 |
10.54 |
… |
… |
… |
… |
… |
… |
… |
Note
This requires column names, manually specified
replicates, anddecoratorsfor file reading! You can learn more about replicates and learn more about decorators in the API documentation.
#### Hybrid Big Tables Big Tables of this kind store Ct values of different assays in separate side-by-side columns, but they store the replicate identifiers as a separate column. Hence, they combine aspects of vertical and horizontal Big Tables.
Example:
id |
assay 1 |
assay 2 |
other_data |
|---|---|---|---|
ctrl |
7.65 |
11.78 |
… |
ctrl |
7.87 |
11.56 |
… |
ctrl |
7.89 |
11.76 |
… |
condA |
7.56 |
11.98 |
… |
condA |
7.34 |
11.56 |
… |
… |
… |
… |
… |
Note
Two options exist to read this kind of setup. - A
listofct_colvalues can be passed which contains the column header of each assay. - The table can bedecorated, in which case only decorated assays (columns) are extracted.Please, note that the two methods of reading this table are mutually exclusive! So, if you decorate your table you cannot pass specific assay headers to the
ct_colargument anymore.
Reading your data
qpcr reads your datafiles using the Readers from the qpcr.Readers submodule. However, as a central hub the main qpcr module provides the DataReader class that will automatically try to determine the appropriate Reader for your datafile, given the setup you provide.
Note
The
DataReaderis designed for easy reading cases and should be appropriate for most cases most of the time. However, if you find that your datafile is not properly working with theDataReader, then use one of theqpcr.Readersor even one of theqpcr.Parsersdirectly to manually read in your data.
First look
There are a number of more detailed tutorials available, so please check these out to learn more about using qpcr. Here, we will just give a very prief preview of doing some Delta-Delta-Ct analysis so you get a feeling of the “flavour” of qpcr.
As of Version 4.0.0 qpcr offers a number of functions to call the underlying qpcr classes with default settings and thus allow even faster coding. However, the full power of customization is only availbale when setting up the objects conventionally (which is easy enough).
In the code below we will just use the main qpcr module to manually assemble our workflow. Much of this code can be omitted when using a pre-defined pipeline from the qpcr.Pipes submodule.
[2]:
# import the module
import qpcr
[3]:
# declare some datafiles
assay_files = [ "./Example Data/HNRNPL_prot.csv", "./Example Data/HNRNPL_nmd.csv" ]
normaliser_files = [ "./Example Data/28S.csv", "./Example Data/actin.csv" ]
# we can now read the files easily using:
assays = qpcr.read( assay_files )
normalisers = qpcr.read( normaliser_files )
# and have a look at the first assay
assays[0]
[3]:
Assay(id='HNRNPL_prot', eff=1.0, n=24)
The qpcr.read function is very handy but relies on default settings for the qpcr.DataReader and is less efficient when you wish to read many identically formatted files, compared to setting up a DataReader directly. We can do so quite easily using:
[19]:
# first create a DataReader to read the files
# we can modify the settings of this reader freely now (but we don't do that here)
reader = qpcr.DataReader()
# then read the files
assays = reader.read(assay_files)
normalisers = reader.read(normaliser_files)
# this could also be written as
# assays, normalisers = reader.read( [assays, normalisers] )
You will find this kind of “flavour” very widely used throughout the Tutorials as this is the original concept of qpcr’s API.
The next step is to compute Delta-Ct values for the assays (dataset internal noralisation against an “anchor”). Here the same logic can be followed as before. qpcr offers to that end the qpcr.Analyser class that handles this first computation.
[20]:
# first set up the qpcr.Analyser (which we could customize to our desires now)
analyser = qpcr.Analyser()
# compute Delta-Ct
assays = analyser.pipe(assays)
normalisers = analyser.pipe(normalisers)
Alternatively, there is (since v.4.0.0), you may have guessed, also a qpcr.analyse function to perform this step with a default Analyser.
[21]:
assays = qpcr.analyse( assays )
Once we have computed Delta-Ct values we can normalise our “assays of interest” against our “normalisers”. To that end qpcr provides the qpcr.Normaliser class that works pretty much like the qpcr.Analyser in the previous step.
[22]:
# setup the normaliser to compute Delta-Delta-Ct values / normalised Fold-Change values
normaliser = qpcr.Normaliser()
# compute Delta-Delta-Ct
results = normaliser.pipe( assays = assays, normalisers = normalisers )
At this point you probably guessed that there is also a qpcr.normalise function, and you are right.
[23]:
results = qpcr.normalise( assays = assays, normalisers = normalisers )
With this we have all the numbers we are interested in for this basic tutorial. We can now inspect the results we obtained. The qpcr.Results class that stores the results table offers a handy method preview to directly visualise the results in a variety of ways.
[24]:
# visualise
fig = results.preview()
At this point you may wonder if there is also a qpcr.preview function. Well, there isn’t. However, the qpcr.plot function is a generic implementation that supports visualisations from qpcr.Assay, qpcr.Results, qpcr.Calibrator, and qpcr.Filters.
[25]:
fig = qpcr.plot( results )
Naturally we can also inspect the data directly by either printing the Results object (or it’s get output) or it’s statistical summary using stats.
[26]:
# also show summary statistics view of the results
results.stats()
[26]:
| group | group_name | assay | n | mean | stdev | median | IQR_(0.25, 0.75) | CI_0.95 | |
|---|---|---|---|---|---|---|---|---|---|
| 11 | 5 | NK6 | HNRNPL_nmd_rel_28S+actin | 2 | 4.842562 | 0.060002 | 4.842562 | 0.060002 | [4.080169048235552, 5.604954117226358] |
| 21 | 10 | NK11 | HNRNPL_nmd_rel_28S+actin | 2 | 15.772739 | 1.024227 | 15.772739 | 1.024227 | [2.7586975862320013, 28.786779942335905] |
| 19 | 9 | NK10 | HNRNPL_nmd_rel_28S+actin | 2 | 16.941957 | 0.190889 | 16.941957 | 0.190889 | [14.516488624589774, 19.36742575285254] |
| 17 | 8 | NK9 | HNRNPL_nmd_rel_28S+actin | 2 | 10.105629 | 0.226306 | 10.105629 | 0.226306 | [7.23013449749268, 12.981123150685496] |
| 15 | 7 | NK8 | HNRNPL_nmd_rel_28S+actin | 2 | 9.623898 | 0.273373 | 9.623898 | 0.273373 | [6.15036182189704, 13.09743362205634] |
| 13 | 6 | NK7 | HNRNPL_nmd_rel_28S+actin | 2 | 8.969974 | 0.124859 | 8.969974 | 0.124859 | [7.383484846018764, 10.55646413477016] |
| 9 | 4 | NK5 | HNRNPL_nmd_rel_28S+actin | 2 | 6.717150 | 0.295022 | 6.717150 | 0.295022 | [2.9685397502667006, 10.465760121873714] |
| 23 | 11 | NK12 | HNRNPL_nmd_rel_28S+actin | 2 | 18.106299 | 0.005835 | 18.106299 | 0.005835 | [18.03216076969107, 18.180436594010164] |
| 5 | 2 | NK3 | HNRNPL_nmd_rel_28S+actin | 2 | 1.037911 | 0.005383 | 1.037911 | 0.005383 | [0.9695147805146154, 1.1063075108984326] |
| 3 | 1 | NK2 | HNRNPL_nmd_rel_28S+actin | 2 | 1.072644 | 0.015405 | 1.072644 | 0.015405 | [0.8769055130766266, 1.2683823879671026] |
| 1 | 0 | NK1 | HNRNPL_nmd_rel_28S+actin | 2 | 1.039614 | 0.039614 | 1.039614 | 0.039614 | [0.536269021286344, 1.5429592152180849] |
| 7 | 3 | NK4 | HNRNPL_nmd_rel_28S+actin | 2 | 6.598869 | 0.288495 | 6.598869 | 0.288495 | [2.9331944405994883, 10.264543340323536] |
| 8 | 4 | NK5 | HNRNPL_prot_rel_28S+actin | 2 | 0.957835 | 0.042069 | 0.957835 | 0.042069 | [0.42330030452717105, 1.4923699257520244] |
| 6 | 3 | NK4 | HNRNPL_prot_rel_28S+actin | 2 | 0.856391 | 0.022619 | 0.856391 | 0.022619 | [0.5689907375205898, 1.143791899621203] |
| 10 | 5 | NK6 | HNRNPL_prot_rel_28S+actin | 2 | 0.927049 | 0.008274 | 0.927049 | 0.008274 | [0.8219172548446965, 1.032180238367934] |
| 22 | 11 | NK12 | HNRNPL_prot_rel_28S+actin | 2 | 0.988872 | 0.024304 | 0.988872 | 0.024304 | [0.6800609070837584, 1.2976828814327155] |
| 12 | 6 | NK7 | HNRNPL_prot_rel_28S+actin | 2 | 0.868270 | 0.036139 | 0.868270 | 0.036139 | [0.40907374291302523, 1.3274653240226644] |
| 14 | 7 | NK8 | HNRNPL_prot_rel_28S+actin | 2 | 0.865168 | 0.003593 | 0.865168 | 0.003593 | [0.8195121908628192, 0.910822927771808] |
| 4 | 2 | NK3 | HNRNPL_prot_rel_28S+actin | 2 | 1.002580 | 0.008699 | 1.002580 | 0.008699 | [0.8920519203336306, 1.1131087521301164] |
| 16 | 8 | NK9 | HNRNPL_prot_rel_28S+actin | 2 | 0.836537 | 0.027424 | 0.836537 | 0.027424 | [0.48807648627136646, 1.1849972491819172] |
| 18 | 9 | NK10 | HNRNPL_prot_rel_28S+actin | 2 | 0.896784 | 0.020972 | 0.896784 | 0.020972 | [0.6303134079329084, 1.163253617537006] |
| 2 | 1 | NK2 | HNRNPL_prot_rel_28S+actin | 2 | 1.055505 | 0.054296 | 1.055505 | 0.054296 | [0.3656075604413517, 1.7454030186338851] |
| 20 | 10 | NK11 | HNRNPL_prot_rel_28S+actin | 2 | 0.891338 | 0.054804 | 0.891338 | 0.054804 | [0.19499208903604948, 1.5876847923663904] |
| 0 | 0 | NK1 | HNRNPL_prot_rel_28S+actin | 2 | 1.017632 | 0.017632 | 1.017632 | 0.017632 | [0.793590790749073, 1.2416741330923047] |
With this we have reached the end of this basic introduction. Congrats, you now know the very basics of qpcr !