v.1.1.0

.gitignore

@@ -1,4 +1,3 @@
 *.ipynb
-.ipynb_checkpoints/
-tests/
+.ipynb_checkpoints
 dist/

README.md

@@ -1,41 +1,273 @@
-# Python 3 function to assign compact letter display letters
+# Cld4py is a Python3 package that allows to assign compact letter display and can add them to seaborn/matplotlib figures
 
 Function to apply compact letter display for pairwise contrasts.
+
 Groups with no significant differences share a letter.
 
-## Parameters:
+It also can be used for plotting letters to seaborn/matplotlib figures.
+
+## Installation
 
 
 ```python
-Required:
-    df     - dataframe with contrasts (pairwise comparisons).
-    G1, G2 - columns in contrasts df with compared groups.
-    P      - column in contrasts df with p-value (adjusted, right?).
-Optional:
-    alpha  - sigificance level (default 0.05).
-    order  - None (default), list or ['ascending', 'descending'].
-             This parameter will define the order of assigned letters.
-             None - alphabetical order will be applied.
-             List - order of groups will be defined by that list.
-             String 'ascending' or 'descending' requires parameters
-             'data', 'values' and 'group' to order groups by the mean.
-    data   - dataframe with values that were compared to get contrasts.
-    vals   - column in data with compared values.
-    group  - column in data with group information.
+pip install cld4py
 ```
 
-## Installation
+## Package content
+
+Cld4py currently includes two functions:
+- assign_letters(): this function will assign CLD letters to the contrasts
+- plot_letters(): this function can add CLD letters to matplotlib/seaborn figures
+
+## Parameters
 
 
 ```python
-pip install cld4py
+assign_letters()
+    """
+    Function to apply compact letter display for pairwise contrasts.
+    Groups with no significant differences share a letter.
+    
+    Parameters:
+    
+      Required:
+        df    - dataframe with contrasts (pairwise comparisons).
+        G1, G2 - columns in contrasts df with compared groups.
+        P      - column in contrasts df with p-value (adjusted, right?).
+        
+      Optional:
+        alpha  - sigificance level (default 0.05).
+        order  - None (default), list or ['ascending', 'descending'].
+                 This parameter will define the order of assigned letters.
+                 None - alphabetical order will be applied.
+                 List - order of groups will be defined by that list.
+                 String 'ascending' or 'descending' requires parameters
+                 'data', 'values' and 'group' to order groups by the mean.
+        data   - dataframe with values that were compared to get contrasts.
+        vals   - column in data with compared values.
+        group  - column in data with group information.
+    """
+
+plot_letters()
+    """
+    Function to plot CLD letters for sns boxplot, violinplot, barplot or swarmplot.
+    Groups with no significant differences share a letter.
+    
+    Parameters:
+    
+      Required:
+        cld    - dataframe or dictionary with groups and letters. If df then groups 
+                 should be in the index and letters in the "Letters" column.
+        data   - dataframe with values that were plotted.
+        vals   - column in data with compared values.
+        group  - column in data with group information.
+        figax  - matplotlib or sns figure or ax with plot.
+        
+      Optional:
+        axis   - axis with plotted groups: "x" or "y" (default "x").
+        plot   - plot type: "boxplot", "violinplot", "barplot" or "swarmplot"
+                 (default "boxplot").
+        pos    - letters position: "upper", "lower", "top" or "bottom" 
+                 (default: "upper"). If axis = "y", "upper" and "top" will be 
+                 plotted on the right side, "lower" and "bottom" - on the left.
+        pad    - distance (% of data range) to the plotted group object (default 1).     
+        c      - color of letters.
+        fs     - fontsize of letters.
+        lim    - increase axes limits, expressed in "pad" (see above) values (default 0)
+    """
+```
+
+## Usage examples
+
+
+```python
+import cld4py
+import pandas as pd
+import seaborn as sns
+import matplotlib.pyplot as plt
+%matplotlib inline
+
+cont = pd.read_csv('tests/contrasts.tsv', sep='\t')
+data = pd.read_csv('tests/data.tsv', sep='\t')
+
+order = sorted(data.Sample.unique().tolist())
+
+cld = cld4py.assign_letters(cont, 'Group1', 'Group2', 'P-adj', order='descending', 
+                            data=data, vals='Metric', group='Sample')
+cld
+```
+
+
+
+
+<div>
+<style scoped>
+    .dataframe tbody tr th:only-of-type {
+        vertical-align: middle;
+    }
+
+    .dataframe tbody tr th {
+        vertical-align: top;
+    }
+
+    .dataframe thead th {
+        text-align: right;
+    }
+</style>
+<table border="1" class="dataframe">
+  <thead>
+    <tr style="text-align: right;">
+      <th></th>
+      <th>Letters</th>
+    </tr>
+    <tr>
+      <th>Group</th>
+      <th></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>S3</th>
+      <td>a</td>
+    </tr>
+    <tr>
+      <th>S1</th>
+      <td>a</td>
+    </tr>
+    <tr>
+      <th>S4</th>
+      <td>a</td>
+    </tr>
+    <tr>
+      <th>S7</th>
+      <td>b</td>
+    </tr>
+    <tr>
+      <th>S6</th>
+      <td>b</td>
+    </tr>
+    <tr>
+      <th>S2</th>
+      <td>c</td>
+    </tr>
+    <tr>
+      <th>S5</th>
+      <td>d</td>
+    </tr>
+  </tbody>
+</table>
+</div>
+
+
+
+### Boxplots
+
+
+```python
+#boxplot x upper
+fig, ax = plt.subplots(1, 1, )
+sns.boxplot(y='Metric', x='Sample', data=data, ax=ax, order=order, showfliers=False)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='x', plot='boxplot', pos='upper', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=1)
+plt.savefig(f'tests/Figures/Boxplot_x_upper.png')
+
+#boxplot x top
+fig, ax = plt.subplots(1, 1, )
+sns.boxplot(y='Metric', x='Sample', data=data, ax=ax, order=order, showfliers=False)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='x', plot='boxplot', pos='top', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=2)
+
+#boxplot y lower
+fig, ax = plt.subplots(1, 1, )
+sns.boxplot(x='Metric', y='Sample', data=data, ax=ax, order=order, showfliers=False)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='y', plot='boxplot', pos='lower', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=2)
+
+#boxplot y bottom
+fig, ax = plt.subplots(1, 1, )
+sns.boxplot(x='Metric', y='Sample', data=data, ax=ax, order=order, showfliers=False)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='y', plot='boxplot', pos='bottom', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=2)
+plt.savefig(f'tests/Figures/Boxplot_y_bottom.png')
+```
+
+![](tests/figs_readme/output_11_0.png)
+![](tests/figs_readme/output_11_1.png)
+![](tests/figs_readme/output_11_2.png)
+![](tests/figs_readme/output_11_3.png)
+
+### Violinplots
+
+
+```python
+#violinplot x upper
+fig, ax = plt.subplots(1, 1, )
+sns.violinplot(y='Metric', x='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='x', plot='violinplot', pos='upper', 
+            vals='Metric', group='Sample', pad=2, c='black', fs=None, lim=2)
+plt.savefig(f'tests/Figures/Violinplot_x_upper.png')
+
+#violinplot y top
+fig, ax = plt.subplots(1, 1, )
+sns.violinplot(x='Metric', y='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='y', plot='violinplot', pos='top', 
+            vals='Metric', group='Sample', pad=2, c='black', fs=None, lim=2)
+
+```
+
+![](tests/figs_readme/output_13_0.png)
+![](tests/figs_readme/output_13_1.png)
+
+### Barplots
+
+
+```python
+#barplot x upper
+fig, ax = plt.subplots(1, 1, )
+sns.barplot(y='Metric', x='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='x', plot='barplot', pos='upper', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=2)
+plt.savefig(f'tests/Figures/Barplot_x_upper.png')
+
+#barplot y top
+fig, ax = plt.subplots(1, 1, )
+sns.barplot(x='Metric', y='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='y', plot='barplot', pos='top', 
+            vals='Metric', group='Sample', pad=1, c='black', fs=None, lim=2)
+```
+
+![](tests/figs_readme/output_15_0.png)
+![](tests/figs_readme/output_15_1.png)
+
+
+```python
+#swarmplot x upper
+fig, ax = plt.subplots(1, 1, )
+sns.swarmplot(y='Metric', x='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='x', plot='swarmplot', pos='upper', 
+            vals='Metric', group='Sample', pad=2, c='black', fs=None, lim=2)
+
+#swarmplot y bottom
+fig, ax = plt.subplots(1, 1, )
+sns.swarmplot(x='Metric', y='Sample', data=data, ax=ax, order=order,)
+
+cld4py.plot_letters(cld=cld, data=data, figax=ax, axis='y', plot='swarmplot', pos='bottom', 
+            vals='Metric', group='Sample', pad=2, c='black', fs=None, lim=2)
 ```
 
-## Usage
+![](tests/figs_readme/output_17_0.png)
+![](tests/figs_readme/output_17_1.png)
 
 
 ```python
-from cld4py.cld4py import *
 
-cld4py(*args)
 ```

tests/contrasts.tsv

@@ -0,0 +1,22 @@
+No	P-adj	Group1	Group2
+17	1.033122348E-09	S5	S6
+12	0.4864265495	S7	S6
+8	2.285159142E-10	S7	S5
+1	0.001057061053	S1	S6
+0	0	S1	S5
+4	0.00649685914	S1	S7
+14	0.0003480325656	S3	S6
+10	0	S3	S5
+19	0.002399973452	S3	S7
+2	0.6609280009	S3	S1
+6	0.00004188242423	S2	S6
+3	0.0002316115293	S2	S5
+15	0.000005533705725	S2	S7
+9	3.114963165E-09	S2	S1
+13	1.30230027E-09	S2	S3
+11	0.003529401992	S4	S6
+7	0	S4	S5
+20	0.02114499298	S4	S7
+5	0.6403693552	S4	S1
+18	0.4031747292	S4	S3
+16	9.298768806E-09	S4	S2

tests/data.tsv

@@ -0,0 +1,36 @@
+	sample	Metric	Sample
+0	C1S	0.24533477341104	S1
+1	C2S	0.34442567650215	S1
+2	C3S	0.31610653499393	S1
+3	C4S	0.283534187246732	S1
+4	C5S	0.364409914894505	S1
+5	C1S	0.192581411032272	S2
+6	C2S	0.113045495147333	S2
+7	C3S	0.129773508264844	S2
+8	C4S	0.0773508287422996	S2
+9	C5S	0.0465190752216192	S2
+10	C1S	0.265093838643477	S3
+11	C2S	0.330497501937435	S3
+12	C3S	0.325285944609476	S3
+13	C4S	0.37481690706195	S3
+14	C5S	0.307355356476943	S3
+15	C1S	0.258835822112931	S4
+16	C2S	0.320682972882345	S4
+17	C3S	0.311237288953274	S4
+18	C4S	0.346214243462401	S4
+19	C5S	0.259527432571054	S4
+20	C1S	0.0070997921051234	S5
+21	C2S	0.0078478725764369	S5
+22	C3S	0.0101977615744241	S5
+23	C4S	0.0192774680359609	S5
+24	C5S	0.0195620075442413	S5
+25	C1S	0.217007939363974	S6
+26	C2S	0.223970579302429	S6
+27	C3S	0.233619494504861	S6
+28	C4S	0.218512597868662	S6
+29	C5S	0.234869236073231	S6
+30	C1S	0.241402886835251	S7
+31	C2S	0.238695850321986	S7
+32	C3S	0.260832537875267	S7
+33	C4S	0.235857609619879	S7
+34	C5S	0.238172462240107	S7