Merge pull request #42 from sbslee/1.14.0-dev

1.14.0 dev

CHANGELOG.rst

@@ -1,6 +1,14 @@
 Changelog
 *********
 
+1.14.0 (2022-06-24)
+-------------------
+
+* :issue:`39`: Add new argument ``palette`` to :meth:`beta_2d_plot` and :meth:`beta_3d_plot` methods so that users can control categorical color mapping.
+* :issue:`39`: Bring back ``add_datapoints`` argument to :meth:`taxa_abundance_box_plot` method to display data points on top of the boxes (note that it was deprecated in 1.11.0 version).
+* Add new argument ``kwargs`` to :meth:`beta_2d_plot` method. It will be passed to :meth:`seaborn.scatterplot()` method so that users can have more control over various aspects of the output plot.
+* :issue:`41`: Fix bug in :meth:`beta_parallel_plot` method when users provide the ``ax`` argument.
+
 1.13.0 (2022-04-02)
 -------------------
 

dokdo/api/beta_2d_plot.py

@@ -9,11 +9,14 @@
 def beta_2d_plot(
     artifact, metadata=None, hue=None, size=None,
     style=None, s=80, alpha=None, hue_order=None, style_order=None,
-    legend='brief', ax=None, figsize=None
+    legend='brief', ax=None, figsize=None, palette=None, **kwargs
 ):
     """
     Create a 2D scatter plot from PCoA results.
 
+    In addition to creating a PCoA plot, this method prints out the
+    proportions explained by each axis.
+
     +---------------------+---------------------------------------------------+
     | q2-diversity plugin | Example                                           |
     +=====================+===================================================+
@@ -54,6 +57,13 @@ def beta_2d_plot(
         Axes object to draw the plot onto, otherwise uses the current Axes.
     figsize : tuple, optional
         Width, height in inches. Format: (float, float).
+    palette : string, list, dict, or matplotlib.colors.Colormap
+        Method for choosing the colors to use when mapping the ``hue``
+        semantic. List or dict values imply categorical mapping, while a
+        colormap object implies numeric mapping.
+    kwargs : other keyword arguments
+        Other keyword arguments will be passed down to
+        :meth:`seaborn.scatterplot()`.
 
     Returns
     -------
@@ -130,22 +140,18 @@ def beta_2d_plot(
             ax.legend(loc='upper left')
         plt.tight_layout()
 
-    .. code-block:: text
+    .. image:: images/beta_2d_plot-2.png
 
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
+    We can control categorical mapping of the ``hue`` variable with
+    ``palette``:
 
-    .. image:: images/beta_2d_plot-2.png
+    .. code:: python3
+
+        palette = {'gut': 'yellow', 'left palm': 'green', 'right palm': 'blue', 'tongue': 'red'}
+        dokdo.beta_2d_plot(qza_file, metadata_file, hue='body-site', palette=palette)
+        plt.tight_layout()
+
+    .. image:: images/beta_2d_plot-3.png
     """
     if isinstance(artifact, pd.DataFrame):
         df = artifact
@@ -175,7 +181,7 @@ def beta_2d_plot(
     sns.scatterplot(
         x='Axis 1', y='Axis 2', data=df, hue=hue, hue_order=hue_order,
         style=style, style_order=style_order, size=size, ax=ax,
-        s=s, alpha=alpha, legend=legend
+        s=s, alpha=alpha, legend=legend, palette=palette, **kwargs
     )
 
     return ax

dokdo/api/beta_3d_plot.py

@@ -7,11 +7,14 @@
 
 def beta_3d_plot(
     artifact, metadata=None, hue=None, azim=-60, elev=30, s=80, ax=None,
-    figsize=None, hue_order=None
+    figsize=None, hue_order=None, palette=None
 ):
     """
     Create a 3D scatter plot from PCoA results.
 
+    In addition to creating a PCoA plot, this method prints out the
+    proportions explained by each axis.
+
     +---------------------+---------------------------------------------------+
     | q2-diversity plugin | Example                                           |
     +=====================+===================================================+
@@ -46,6 +49,9 @@ def beta_3d_plot(
         Width, height in inches. Format: (float, float).
     hue_order : list, optional
         Specify the order of categorical levels of the 'hue' semantic.
+    palette : dict
+        Dictionary for choosing the colors to use when mapping the ``hue``
+        semantic.
 
     Returns
     -------
@@ -74,8 +80,8 @@ def beta_3d_plot(
         qza_file = '/Users/sbslee/Desktop/dokdo/data/moving-pictures-tutorial/unweighted_unifrac_pcoa_results.qza'
         metadata_file = '/Users/sbslee/Desktop/dokdo/data/moving-pictures-tutorial/sample-metadata.tsv'
         dokdo.beta_3d_plot(qza_file,
-                           metadata_file,
-                           'body-site',
+                           metadata=metadata_file,
+                           hue='body-site',
                            figsize=(8, 8))
         plt.tight_layout()
 
@@ -96,29 +102,29 @@ def beta_3d_plot(
         ax1 = fig.add_subplot(1, 2, 1, projection='3d')
         ax2 = fig.add_subplot(1, 2, 2, projection='3d')
         dokdo.beta_3d_plot(qza_file,
-                           metadata_file,
+                           metadata=metadata_file,
                            ax=ax1,
                            hue='body-site',
                            elev=15)
         dokdo.beta_3d_plot(qza_file,
-                           metadata_file,
+                           metadata=metadata_file,
                            ax=ax2,
                            hue='body-site',
                            azim=70)
         plt.tight_layout()
 
-    .. code-block:: text
+    .. image:: images/beta_3d_plot-2.png
 
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
-        # 6.63% for Axis 3
-        # Explained proportions computed by QIIME 2:
-        # 33.94% for Axis 1
-        # 25.90% for Axis 2
-        # 6.63% for Axis 3
+    We can control categorical mapping of the ``hue`` variable with
+    ``palette``:
 
-    .. image:: images/beta_3d_plot-2.png
+    .. code:: python3
+
+        palette = {'gut': 'yellow', 'left palm': 'green', 'right palm': 'blue', 'tongue': 'red'}
+        dokdo.beta_3d_plot(qza_file, metadata=metadata_file, hue='body-site', palette=palette, figsize=(8, 8))
+        plt.tight_layout()
+
+    .. image:: images/beta_3d_plot-3.png
     """
     if isinstance(artifact, pd.DataFrame):
         df = artifact
@@ -158,7 +164,10 @@ def beta_3d_plot(
             _hue_order = hue_order
         for label in _hue_order:
             a = df[df[hue] == label]
-            ax.scatter(a['Axis 1'], a['Axis 2'], a['Axis 3'], label=label, s=s)
+            if palette is None:
+                palette = {x: None for x in _hue_order}
+            c = palette[label]
+            ax.scatter(a['Axis 1'], a['Axis 2'], a['Axis 3'], label=label, s=s, c=c)
             ax.legend()
 
     ax.set_xlabel('Axis 1')

dokdo/api/beta_parallel_plot.py

@@ -111,7 +111,7 @@ def beta_parallel_plot(
         fig, ax = plt.subplots(figsize=figsize)
 
     pd.plotting.parallel_coordinates(df, 'Target',
-        color=plt.cm.get_cmap('tab10').colors)
+        color=plt.cm.get_cmap('tab10').colors, ax=ax)
 
     if hue is None:
         ax.get_legend().remove()

dokdo/api/taxa_abundance.py

@@ -641,7 +641,9 @@ def taxa_abundance_box_plot(
     include_samples=None, exclude_taxa=None, sort_by_names=False,
     sample_names=None, csv_file=None, pseudocount=False,
     taxa_names=None, pretty_taxa=False, show_means=False,
-    meanprops=None, show_others=True, sort_by_mean=True, ax=None, figsize=None
+    meanprops=None, show_others=True, sort_by_mean=True,
+    add_datapoints=False, jitter=1, alpha=None, size=5,
+    ax=None, figsize=None,
 ):
     """
     Create a box plot showing the distribution of relative abundance for
@@ -709,6 +711,17 @@ def taxa_abundance_box_plot(
         Include the 'Others' category.
     sort_by_mean : bool, default: True
         Sort taxa by their mean relative abundance after sample filtration.
+    add_datapoints : bool, default: False
+        Show data points on top of the boxes.
+    jitter : float, default: 1
+        Ignored when ``add_datapoints=False``. Amount of jitter (only along
+        the categorical axis) to apply.
+    alpha : float, optional
+        Ignored when ``add_datapoints=False``. Proportional opacity of the
+        points.
+    size : float, default: 5.0
+        Ignored when ``add_datapoints=False``. Radius of the markers, in
+        points.
     ax : matplotlib.axes.Axes, optional
         Axes object to draw the plot onto, otherwise uses the current Axes.
     figsize : tuple, optional
@@ -775,6 +788,22 @@ def taxa_abundance_box_plot(
 
     .. image:: images/taxa_abundance_box_plot-3.png
 
+    We can add data points on top of the boxes:
+
+    .. code:: python3
+
+        dokdo.taxa_abundance_box_plot(
+            qzv_file,
+            level=2,
+            count=4,
+            pretty_taxa=True,
+            add_datapoints=True,
+            figsize=(8, 7)
+        )
+        plt.tight_layout()
+
+    .. image:: images/taxa_abundance_box_plot-6.png
+
     We can also specify which taxa to plot:
 
     .. code:: python3
@@ -877,8 +906,6 @@ def taxa_abundance_box_plot(
     else:
         df2 = pd.melt(df)
 
-
-
     if meanprops:
         _meanprops = meanprops
     else:
@@ -898,6 +925,13 @@ def taxa_abundance_box_plot(
         ax=ax, **d
     )
 
+    if add_datapoints:
+        sns.stripplot(
+            x='variable', y='value', hue=hue, hue_order=hue_order, data=df2,
+            ax=ax, color='black', size=size, dodge=True, jitter=jitter,
+            alpha=alpha
+        )
+
     # If provided, output the dataframe as a .csv file.
     if csv_file is not None:
         df3 = pd.concat([df, mf], axis=1, join='inner')

dokdo/version.py

@@ -1 +1 @@
-__version__ = '1.13.0'
+__version__ = '1.14.0'