Papillon is a python alternative to cummeRbund to read and plot Galaxy
RNA-seq data.

To start
========

After RNA-seq analysis with `Galaxy <https://usegalaxy.org/>`__,
download the 4 files generated by cuffdiff containing respectively:

*... transcript\_FPKM\_tracking...*

*... gene\_FPKM\_tracking ...*

*... gene\_differential\_expression...*

*... transcript\_differential\_expression...*

And put them in the same folder.

You can either use directly the files or change the names according to
cummeRbund in:

*... transcript\_FPKM\_tracking...* = isoforms.fpkm\_tracking

*... gene\_FPKM\_tracking ...* = gene.fpkm\_tracking

*... gene\_differential\_expression...* = gene\_exp.diff

*... transcript\_differential\_expression...* = isoform\_exp.diff


Commands
========

Functions:
----------

``read_db(path, drop_comparison=[])``

Read the cuffdiff/cummeRbund files. Return a class papillon.

**path**: *str*

folder path and folder name, containing the files

**drop\_comparison**: *str or list*

what comparison do not import

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment", drop_comparison=["Sample 1_vs_Sample 2","Sample 3_vs_Sample 4"])


Class:
------

``papillon``

this class store cuffdiff/cummeRbund data. The class has the following
attributes:

``self.path`` - files path

``self.samples`` - samples found

``self.comparison`` - comparisons found

``self.genes_detect`` - dataframe of genes detected

``self.genes_significant`` - dataframe of genes significant expressed
among comparisons

``self.isoforms_detect`` - dataframe of isoforms detected

``self.isoforms_significant`` - dataframe of isoforms significant
expressed among comparisons

Some papillon class methods create

``self.selected`` - contains a list of genes/isoforms selected
(according with ``self.type_selected``)

``self.type_selected`` - could be either equal to "gene" or "isoform".
Define the type of ``self.selected`` entry.


Class Methods:
--------------
**self.dropComparison(self, comparison)**

Drop Comparison or list of comparisons and re-calculate significant
genes/isoforms

**comparison**: *str* or *list*

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.drop_comparison(["Sample 1_vs_Sample 2","Sample 3_vs_Sample 4"])

--------------

**self.change_order(self, new_order)**

Change the samples order

**new\_order**: *list*

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.change_order(["Sample 4","Sample 3","Sample 2","Sample 1"]

--------------

**self.get_gene(self, genelist=None, comparison=None, sign=None, export=False)**

This method selects genes. Create ``self.selected`` and
``self.type_selected="gene"``

**genelist**: *None*, *str* or *list*

with *None* (default) select all the genes differential expressed in the
select comparison. *str* can be either a gene name or a plain text file
with a list of gene names. *list* accept a list of gene names.

**comparison**: *None* or *str*

with *None* (default) select all the genes differential expressed in at
least one comparison. If *str* is passed, it selects only genes
differential expressed in that specific comparison

**sign**: *None*, *">"* or *"<"*

with *None* (default) select all the genes differential expressed in the
select comparison. If sign is different from *None*, comparison is
required. If *">"* is passed, it selects all genes higher in the first
term compared to the second one. The opposite with *"<"*

I.e.

``self.get_gene(self, comparison="Sample 3_vs_Sample 4", sign=">")``

select all the genes where Sample 3 is higher ( > ) than Sample 4

**export** - True/False

False is default. Whether or not export the selected genes as .xls file.

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.get_gene()

     MyExp.get_gene(genelist="IL6", export=True)

     MyExp.get_gene(genelist="my_list.txt", comparison="Sample 3_vs_Sample 4", sign="<")

--------------

**self.get_isoform(self, genelist=None, comparison=None, sign=None, export=False, show_dup=False)**

This method selects isoform. Create ``self.selected`` and
``self.type_selected="isoform"``

**genelist**: *None*, *str* or *list*

with *None* (default) select all the isoforms differential expressed in
the select comparison. *str* can be either a gene name or a plain text
file with a list of gene names. *list* accept a list of gene names.

**comparison**: *None* or *str*

with *None* (default) select all the isoforms differential expressed in
at least one comparison. If *str* is passed, it selects only isoforms
differential expressed in that specific comparison

**sign**: *None*, *">"* or *"<"*

with *None* (default) select all the isoforms differential expressed in
the select comparison. If sign is different from *None*, comparison is
required. If *">"* is passed, it selects all isoforms higher in the
first term compared to the second one. The opposite with *"<"*

I.e.

``self.get_isoform(self, comparison="Sample 3_vs_Sample 4", sign=">")``

select all the isoforms where Sample 3 is higher ( > ) than Sample 4

**export** - True/False

False is default. Whether or not export the selected isoforms as .xls
file.

**show\_dup** - True/False

False is default. Whether or not indicate if there are more then 1
isoform for each gene name in the exported .xls file (export=True
required)

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.get_isoform()

     MyExp.get_isoform(genelist="IL6", export=True)

     MyExp.get_isoform(genelist="my_list.txt", comparison="Sample 3_vs_Sample 4", sign="<")

--------------

**self.onlyFPKM(return_as, **option)**

Use self.selected and return a DataFrame with only FPKM values columns.

**return\_as** - *"df"*, *"array"* or *"gene name"*

*"df"* return a pandas DataFrame, *"array"* return a numpy array, *"gene
name"* return a pandas DataFrame containing gene names in addition to
the FPKM values columns

\*\*option - accepts extra\_df parameter extra\_df parameter accepts an
external dataframe (it has to be a papillon class format).

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.get_isoform()

     MyExp.onlyFPKM("df")

--------------

**self.heatmap(self, z_score=True, col_cluster=False, method="complete", cmap="seismic", export=False, **options)**

Generate a heatmap with self.selected genes/isoforms

**z\_score** - True/False or 1.

True is default. Whether or not apply z-score normalization. Z-score
normalization is quite common in heatmap for gene/isoform expression. Z
scores are: z = (x - mean)/std, so values in each row will get the mean
of the row subtracted, then divided by the standard deviation of the
row. This ensures that each row has mean of 0 and variance of 1. It is
possible apply the same normalization to the column giving z\_score = 1.

**col\_cluster** - True/False

False is default. Whether or not cluster the samples.

**method** - *str*

Linkage method to use for calculating clusters. Default is "complete",
because according to D'haeseleer P. Nat Biotechnol. 2005, complete
linkage is one of the best linkage methods for gene expression
clustering. See `seaborn.clustermap documentation to use other linkage
methods <http://seaborn.pydata.org/generated/seaborn.clustermap.html>`__

**cmap** - *str*

matplotlib colormap name or object, or list of colors. Default is
"seismic". Check
`here <https://matplotlib.org/examples/color/colormaps_reference.html>`__
or `here <https://matplotlib.org/users/colormaps.html>`__ for more color
maps. See `seaborn.heatmap documentation for more
information <https://seaborn.pydata.org/generated/seaborn.heatmap.html>`__

**export** - True/False

False is default. Whether or not export the heatmap as .png file.

\*\*options Accept all the parameter and values accepted by
seaborn.clustermap. See `seaborn.clustermap documentation for more
information. <http://seaborn.pydata.org/generated/seaborn.clustermap.html>`__
i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.get_isoform()

     MyExp.heatmap()

     MyExp.heatmap(z_score=False, export=True)

     MyExp.heatmap(z_score=True, col_cluster=True)

--------------

**self.plot(self, title="", legend=True, z_score=False, export=False, df=None, size=10, **option)**

Create a lineplot with self.selected. Max number of genes/isoforms is
200.

**title** - *str*

accept a string as title of the plot

**legend** - True/False

True is default. Whether show or not the legend. Default is True, if the
number of genes is higher than 50 is forced to False.

**z\_score** - True/False

False is default. Whether or not apply z-score normalization. Z-score
normalization. Z scores are: z = (x - mean)/std, so values in each row
will get the mean of the row subtracted, then divided by the standard
deviation of the row. This ensures that each row has mean of 0 and
variance of 1.

**export** - True/False

False is default. Whether or not export the plot as .png file.

**df** - *pandas.DataFrame*

accept a dataframe different from self.selected. It should have a
papillon class structure.

**size** - *int* Size of the figure to create. Default is 10

\*\*options - all the options accepted by seaborn.factorplot. `See
seaborn.factorplot documentation for more
info. <https://seaborn.pydata.org/generated/seaborn.factorplot.html>`__

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.get_isoform()

     MyExp.plot()

     MyExp.plot(title="My genes", legend=False)

     MyExp.heatmap(z_score=True, export=True)

--------------

**self.search(self, word, where, how="table", export=False)**

search among gene/isoform names in detected and significant.

**word** - *str* str to search among the gene names

**where** - *"genes\_detected"*, *"genes\_significant"*,
*"isoforms\_detected"*, *"isoforms\_significant"* define where search
the word.

**how** - *"table"*, *"list"* or *"selected"*

*"table"* return found names as pandas.DataFrame.

*"list"* return found names as list with no duplicates.

*"selected"* select the genes/isoforms as self.selected, works only with
where="...significant"

**export** - True/False

False is default. Whether or not export the found isoforms/genes as .xls
file.

i.e.:

::

     import papillon as pl

     MyExp=pl.read_db("My Experiment")

     MyExp.search(word="IL", where="genes_significant", export=True)

     MyExp.search(word="CCL", where="isoforms_detected", how="list")
