Merge pull request #36 from sbslee/1.12.0-dev

1.12.0 dev

Author: sbslee

CHANGELOG.rst

@@ -1,6 +1,14 @@
 Changelog
 *********
 
+1.12.0 (2022-02-11)
+-------------------
+
+* :issue:`33`: Update the :command:`make-manifest` command to ignore undetermined FASTQ files.
+* :issue:`34`: Update the :meth:`alpha_rarefaction_plot` method to keep 'N/A' values as string instead of NaN.
+* :issue:`35`: Update the methods :meth:`alpha_diversity_plot`, :meth:`beta_2d_plot`, and :meth:`beta_3d_plot` to accept :class:`pandas.DataFrame` in case the input data was not generated from QIIME 2 (e.g. shotgun sequencing).
+* Update the methods :meth:`beta_2d_plot` and :meth:`beta_3d_plot` to print out the proportions explained instead of embedding them in the PCoA plot.
+
 1.11.0 (2021-08-04)
 -------------------
 

README.rst

@@ -20,6 +20,25 @@ Your contributions (e.g. feature ideas, pull requests) are most welcome.
 | Email: sbstevenlee@gmail.com
 | License: MIT License
 
+Citation
+========
+
+If you use Dokdo in a published analysis, please report the program version
+and the GitHub repository (https://github.com/sbslee/dokdo). If applicable,
+please also consider citing the following preprint in which Dokdo was first
+described:
+
+JY Park, H Yoon, S Lee, et al. Do Different Samples From Pregnant Women and
+Their Neonates Share the Common Microbiome: A Prospective Cohort Study.
+November 29th, 2021. Research Square.
+doi: https://doi.org/10.21203/rs.3.rs-1062191/v1.
+
+Below is an incomplete list of publications which have used Dokdo:
+
+- `Silva de Carvalho et al., 2022 <https://www.sciencedirect.com/science/article/pii/S0889159121006127>`__ in *Brain, Behavior, and Immunity*: Post-ischemic protein restriction induces sustained neuroprotection, neurological recovery, brain remodeling, and gut microbiota rebalancing.
+- `Park et al., 2021 <https://www.nature.com/articles/s41598-021-95789-8>`__ in *Scientific Reports*: Effect of black ginseng and silkworm supplementation on obesity, the transcriptome, and the gut microbiome of diet-induced overweight dogs.
+- `Reinold et al., 2021 <https://www.frontiersin.org/articles/10.3389/fcimb.2021.747816/full>`__ in *Frontiers in Cellular and Infection Microbiology*: A Pro-Inflammatory Gut Microbiome Characterizes SARS-CoV-2 Infected Patients and a Reduction in the Connectivity of an Anti-Inflammatory Bacterial Network Associates With Severe COVID-19.
+
 CLI Examples
 ============
 

docs/images/beta_2d_plot-1.png

@@ -82,14 +82,13 @@ def main():
         add_help=False,
         help=("Create a manifest file (.tsv) from a directory containing "
               "FASTQ files."),
-        description=("Create a manifest file (.tsv) from a directory "
-                     "containing FASTQ files. The file names must include "
-                     "either '_R1_001.fastq' or '_R1_002.fastq'. The word "
-                     "before the third-to-last underscore will be set "
-                     "as the sample ID. For example, a file named "
-                     "'EXAMPLE_S1_R1_001.fastq.gz' will produce 'EXAMPLE' "
-                     "as sample ID and 'EXAM_PLE_S1_R1_001.fastq.gz', "
-                     "'EXAM_PLE'."),
+        description=("Create a manifest file (.tsv) from a directory containing FASTQ files. "
+                     "This command assumes that FASTQ filenames end with a suffix such as "
+                     "'_S0_R1_001.fastq' or '_S14_R2_001.fastq'. The word before the "
+                     "third-to-last underscore ('_') will be used as sample ID. For example, a "
+                     "file named 'EXAMPLE_S1_R1_001.fastq.gz' will set 'EXAMPLE' as sample ID. "
+                     "Undertermined reads (e.g. 'Undetermined_S0_R1_001.fastq') will not be "
+                     "included in the output file."),
     )
 
     make_manifest_parser._optionals.title = "Arguments"

docs/images/beta_2d_plot-2.png

@@ -22,9 +22,13 @@ def alpha_diversity_plot(
 
     Parameters
     ----------
-    artifact : str or qiime2.Artifact
+    artifact : str, qiime2.Artifact, or pandas.DataFrame
         Artifact file or object from the q2-diversity plugin with the
-        semantic type ``SampleData[AlphaDiversity]``.
+        semantic type ``SampleData[AlphaDiversity]``. If you are importing
+        data from a software tool other than QIIME 2, then you can provide a
+        :class:`pandas.DataFrame` object in which the row index is sample
+        names and the only column is diversity values with its header being
+        the name of metrics used (e.g. 'faith_pd').
     metadata : str or qiime2.Metadata
         Metadata file or object.
     where : str
@@ -65,10 +69,12 @@ def alpha_diversity_plot(
     """
     if isinstance(artifact, str):
         _alpha_diversity = Artifact.load(artifact)
+        df = _alpha_diversity.view(pd.Series).to_frame()
+    elif isinstance(artifact, pd.DataFrame):
+        df = artifact
     else:
         _alpha_diversity = artifact
-
-    df = _alpha_diversity.view(pd.Series).to_frame()
+        df = _alpha_diversity.view(pd.Series).to_frame()
 
     mf = common.get_mf(metadata)
     df = pd.concat([df, mf], axis=1, join='inner')

docs/images/beta_3d_plot-1.png

@@ -103,7 +103,9 @@ def alpha_rarefaction_plot(
 
     with tempfile.TemporaryDirectory() as t:
         common.export(visualization, t)
-        df = pd.read_csv(f'{t}/{metric}.csv', index_col=0)
+        df = pd.read_csv(f'{t}/{metric}.csv', index_col=0,
+            keep_default_na=False, na_values=[''])
+        df.to_csv('test.csv')
 
     metadata_columns = [x for x in df.columns if 'iter' not in x]
 

docs/images/beta_3d_plot-2.png

@@ -24,10 +24,14 @@ def beta_2d_plot(
 
     Parameters
     ----------
-    artifact : str or qiime2.Artifact
+    artifact : str, qiime2.Artifact, or pandas.DataFrame
         Artifact file or object from the q2-diversity plugin with the
         semantic type ``PCoAResults`` or
-        ``PCoAResults % Properties('biplot')``.
+        ``PCoAResults % Properties('biplot')``. If you are importing
+        data from a software tool other than QIIME 2, then you can provide a
+        :class:`pandas.DataFrame` object in which the row index is sample
+        names and the first and second columns indicate the first and second
+        PCoA axes, respectively.
     metadata : str or qiime2.Metadata, optional
         Metadata file or object.
     hue : str, optional
@@ -81,6 +85,12 @@ def beta_2d_plot(
                            figsize=(5, 5))
         plt.tight_layout()
 
+    .. code-block:: text
+
+        # Explained proportions computed by QIIME 2:
+        # 33.94% for Axis 1
+        # 25.90% for Axis 2
+
     .. image:: images/beta_2d_plot-1.png
 
     We can color the datapoints with ``hue``. We can also change the
@@ -120,43 +130,52 @@ def beta_2d_plot(
             ax.legend(loc='upper left')
         plt.tight_layout()
 
+    .. code-block:: text
+
+        # 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
+
     .. image:: images/beta_2d_plot-2.png
     """
-    if isinstance(artifact, str):
-        _pcoa_results = Artifact.load(artifact)
+    if isinstance(artifact, pd.DataFrame):
+        df = artifact
     else:
-        _pcoa_results = artifact
-
-    ordination_results = _pcoa_results.view(OrdinationResults)
-
-    df1 = ordination_results.samples.iloc[:, :2]
-    df1.columns = ['A1', 'A2']
+        if isinstance(artifact, str):
+            _pcoa_results = Artifact.load(artifact)
+        else:
+            _pcoa_results = artifact
+        ordination_results = _pcoa_results.view(OrdinationResults)
+        df = ordination_results.samples.iloc[:, :2]
+        props = ordination_results.proportion_explained
+        print('# Explained proportions computed by QIIME 2:')
+        print(f'# {props[0]*100:.2f}% for Axis 1')
+        print(f'# {props[1]*100:.2f}% for Axis 2')
+
+    df.columns = ['Axis 1', 'Axis 2']
 
     if metadata is None:
-        df2 = df1
+        pass
     else:
         mf = common.get_mf(metadata)
-        df2 = pd.concat([df1, mf], axis=1, join='inner')
-
-    props = ordination_results.proportion_explained
+        df = pd.concat([df, mf], axis=1, join='inner')
 
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
 
-    sns.scatterplot(data=df2,
-                    x='A1',
-                    y='A2',
-                    hue=hue,
-                    hue_order=hue_order,
-                    style=style,
-                    style_order=style_order,
-                    size=size,
-                    ax=ax,
-                    s=s,
-                    alpha=alpha,
-                    legend=legend)
-
-    ax.set_xlabel(f'Axis 1 ({props[0]*100:.2f} %)')
-    ax.set_ylabel(f'Axis 2 ({props[1]*100:.2f} %)')
+    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
+    )
 
     return ax