Merge pull request #293 from MontgomeryLab/issue-285

tiny-plot: sort classes in class_charts by natural order

Author: taimontgomery

README.md

@@ -161,7 +161,7 @@ At the core of tinyRNA is tiny-count, a highly flexible counting utility that al
 A wrapper R script for DESeq2 facilitates DGE analysis of counted sample files.
 
 ### `tiny-plot`
-The results of feature counting and DGE analysis are visualized with high resolution plot PDFs. User-defined plot styles are also supported via a Matplotlib stylesheet. 
+The results of feature counting and DGE analysis are visualized with high resolution plot PDFs. User-defined plot styles are also supported via a Matplotlib style sheet. 
 
 [Full documentation for tiny-plot can be found here.](doc/tiny-plot.md)
 

doc/Configuration.md

@@ -32,9 +32,9 @@ To make it simple to specify your fastq files and their locations, along with as
 
 Small RNAs can often be classified by sequence characteristics, such as length, strandedness, and 5' nucleotide. We provide a Features Sheet (`features.csv`) in which you can define selection rules to more accurately capture counts for the small RNAs of interest. [More info](#features-sheet-details).
 
-#### Plot Stylesheet
+#### Plot Style Sheet
 
-Plot styles can be optionally overridden using a matplotlibrc stylesheet. [More info](#plot-stylesheet-details).
+Plot styles can be optionally overridden using a matplotlibrc style sheet. [More info](#plot-style-sheet-details).
 
 ## Editing YAML Files
 The Run Config and Paths File are YAML formatted files that can be edited with a text editor. Changing values in these files is pretty straight forward, but it is useful to know a little about YAML syntax.
@@ -174,5 +174,5 @@ Examples:
 ### Case Sensitivity
 All selectors are case-insensitive.
 
-## Plot Stylesheet Details
-Matplotlib uses key-value "rc parameters" to allow for customization of its properties and styles, and one way these parameters can be specified is with a [matplotlibrc file](https://matplotlib.org/3.4.3/tutorials/introductory/customizing.html#a-sample-matplotlibrc-file), which we simply refer to as the Plot Stylesheet. You can obtain a copy of the default stylesheet used by tiny-plot with the command `tiny get-templates`. Please keep in mind that tiny-plot overrides these defaults for a few specific elements of certain plots. Feel free to reach out if there is a plot style you wish to override but find you are unable to.
+## Plot Style Sheet Details
+Matplotlib uses key-value "rc parameters" to allow for customization of its properties and styles, and one way these parameters can be specified is with a [matplotlibrc file](https://matplotlib.org/3.5.2/tutorials/introductory/customizing.html#a-sample-matplotlibrc-file), which we simply refer to as the Plot Style Sheet. You can obtain a copy of the default style sheet used by tiny-plot with the command `tiny get-templates`, and your modified style sheet can be passed using the [plot_style_sheet parameter](Parameters.md#style-sheet). Please keep in mind that tiny-plot overrides these defaults for a few specific elements of certain plots. Feel free to reach out if there is a plot style you wish to override but find you are unable to.

doc/Parameters.md

@@ -217,7 +217,7 @@ Feature expression levels are considered significant if their P value is less th
 |----------------|-------------------|--------------------------|
 |                | plot_style_sheet: | `--style-sheet MPLSTYLE` |
 
-The plot style sheet can be used to override the default Matplotlib styles used by tiny-plot. Unlike the other parameters, this option is found in the Paths File. See the [Plot Stylesheet documentation](Configuration.md#plot-stylesheet-details) for more information.
+The plot style sheet can be used to override the default Matplotlib styles used by tiny-plot. Unlike the other parameters, this option is found in the Paths File. The expected value for this parameter is the path to your modified style sheet. See the [Plot Style Sheet documentation](Configuration.md#plot-style-sheet-details) for more information.
 
 ### Vector Scatter
 | Run Config Key      | Commandline Argument |
@@ -241,7 +241,7 @@ The min and/or max bounds for plotted lengths can be set with this option. See [
 | plot_dge_scatter_min: | `--dge-min VALUE`    | 
 | plot_dge_scatter_max: | `--dge-max VALUE`    |
 
-The min and/or max bounds for DGE scatter plots can be set with this option. The value you provide should be a log2 count value and can be whole or fractional, e.g. `--dge-min 1.9` would produce a plot whose first tick mark is labeled 2 and would include points for feature counts as low as 3.74. Unspecified bounds are automatically calculated to fit the data, and will include the margin specified by the `axes.[x/y]margin` key in the [Plot Stylesheet](Configuration.md#plot-stylesheet-details).
+The min and/or max bounds for DGE scatter plots can be set with this option. The value you provide should be a log2 count value and can be whole or fractional, e.g. `--dge-min 1.9` would produce a plot whose first tick mark is labeled 2 and would include points for feature counts as low as 3.74. Unspecified bounds are automatically calculated to fit the data, and will include the margin specified by the `axes.[x/y]margin` key in the [Plot Style Sheet](Configuration.md#plot-style-sheet-details).
 
 ### Labels for Class-related Plots
 | Run Config Key         | Commandline Argument |

doc/tiny-plot.md

@@ -59,7 +59,7 @@ Rules are referred to by their row number in the Features Sheet and the first no
 - Alignments which do not overlap with any features
 
 #### Rule Chart Styles
-Percentage label darkness and bar colors reflect the magnitude of the rule's contribution. Magnitude is always considered on a 0-100% scale, rather than scaling down to the chart's view limits. These styles cannot be changed using a plot stylesheet.
+Percentage label darkness and bar colors reflect the magnitude of the rule's contribution. Magnitude is always considered on a 0-100% scale, rather than scaling down to the chart's view limits. These styles cannot be changed using a plot style sheet.
 
 
 
@@ -111,13 +111,25 @@ The control condition is plotted on the x-axis, but it must be specified in your
 #### View Limits
 Both the lower and upper bound of the plot's axes [can be set manually](Parameters.md#bounds-for-lendist-charts). Unspecified bounds are automatically calculated to fit the data.
 
+#### Zero-Count Features
+Due to the plot's log scale, points are not plotted for features that have 0 reads in one of the compared conditions. Zero-count features will be supported in a future release.
+
 
 
 ## sample_avg_scatter_by_dge_class
-The previous plot type can be extended to group and color differentially expressed features by class. Classes are sorted by abundance before plotting to maximize representation. You can also filter the classes displayed using [plot_class_scatter_filter](Parameters.md#filtering-classes-in-dge-class-scatter-plots)
+The previous plot type can be extended to group and color differentially expressed features by class.
 
 <p float="left" align="center">
     <img src="../images/plots/scatter_dge_class.jpg" width="100%" alt="sample_avg_scatter_by_dge_class"/>
 </p>
 
->**Tip**: if you find that two groups of interest share proximity and are too similar in color, you can change the group's color with a modified Plot Stylesheet. The groups will be colored in the same order they are listed in the legend (not including P value outgroup), e.g. changing the color of the ERGO group means changing the 5th color in the `axes.prop_cycle` color cycler. See the [config file documentation](Configuration.md#plot-stylesheet-details) for more info about the Plot Stylesheet.
+#### Filtering Classes
+You can filter which classes are displayed using [plot_class_scatter_filter](Parameters.md#filtering-classes-in-dge-class-scatter-plots).
+
+#### Zero-Count Classes
+If all features have 0 reads for a given class in one of the compared conditions, then that class is omitted from the plot and legend due to the plot's log scale. Zero-count classes will be supported in a future release.
+
+#### Customizing Group Colors
+If you find that two groups of interest share proximity and are too similar in color, you can change the group's color with a modified Plot Style Sheet. Group colors are assigned from the `axes.prop_cycle` color cycler when there are fewer groups than colors, or from the [tab20](https://matplotlib.org/3.5.2/tutorials/colors/colormaps.html#qualitative) colormap when groups outnumber colors. First, the total list of unique classes is gathered from the counts table and sorted, and the resulting list of classes is assigned colors in the order produced by the cycler. 
+
+For example, changing the color of the miRNA group in the above plot means changing the 6th color in the `axes.prop_cycle` list (assuming all classes are represented in the plot). The P value outgroup is always the same color and doesn't affect the assignment process. See the [config file documentation](Configuration.md#plot-style-sheet-details) for more info about the Plot Style Sheet.

images/plots/class_chart.jpg

@@ -18,7 +18,15 @@
 from pkg_resources import resource_filename
 
 from tiny.rna.plotterlib import plotterlib
-from tiny.rna.util import report_execution_time, make_filename, SmartFormatter, timestamp_format, add_transparent_help
+from tiny.rna.util import (
+    report_execution_time,
+    add_transparent_help,
+    timestamp_format,
+    SmartFormatter,
+    sorted_natural,
+    make_filename
+)
+
 
 aqplt: plotterlib = None
 RASTER: bool = True
@@ -185,7 +193,8 @@ def class_charts(raw_class_counts: pd.DataFrame, mapped_reads: pd.Series, out_pr
         kwargs: Additional keyword arguments to pass to pandas.DataFrame.plot()
     """
 
-    class_props = get_proportions_df(raw_class_counts, mapped_reads, class_na, scale).sort_index()
+    class_props = get_proportions_df(raw_class_counts, mapped_reads, class_na, scale)
+    class_props = class_props.reindex(sorted_natural(class_props.index))
     max_prop = class_props.max().max()
 
     for library in raw_class_counts:

images/plots/scatter_dge_class.jpg

@@ -336,7 +336,7 @@ def assign_class_colors(classes):
         else:
             colors = iter(plt.get_cmap("tab20"))
 
-        return {cls: next(colors) for cls in classes}
+        return {cls: next(colors) for cls in sorted_natural(classes)}
 
     def set_dge_class_legend_style(self):
         """Widens the "scatter" figure and moves plot to the left to accommodate legend"""
@@ -383,13 +383,13 @@ def get_scatter_view_lims(counts_df: pd.DataFrame, vmin: int = None, vmax: int =
         x0, x1 = (minpos if x0 <= 0 else x0,
                   minpos if x1 <= 0 else x1)
 
-        # Get axes margin preferences from stylesheet
+        # Get axes margin preferences from style sheet
         rc_mar = {mpl.rcParams.get(f"axes.{m}", 0)
                   for m in ('xmargin', 'ymargin')}
 
         margin = max(rc_mar)
         if len(rc_mar) != 1:
-            print("Stylesheet values for axes.xmargin and axes.ymargin differ. "
+            print("Style sheet values for axes.xmargin and axes.ymargin differ. "
                   "The larger value will be chosen for the scatter plot margin.",
                   file=sys.stderr)