Updating plotting documentation - adding new gallery (#143)

* updates to documentation for additional gallery

* testing changes

* pycodestyle

* pycodestyle

* try new matplotlib

* add plot type example files for gallery

* pycodestyle

* update plots markdown

* histograms/histogram.py

* update order and remove examples

* add subsection order

* one last fix

* Delete galleries/examples/line_plots/Untitled.ipynb

* Delete docs/sphinxext/gallery_order.py

* Delete docs/sphinxext/__init__.py

docs/conf.py

@@ -17,7 +17,7 @@
 sys.path.insert(0, str(Path(__file__).parent.resolve()))
 
 import matplotlib
-from sphinx_gallery.sorting import ExampleTitleSortKey, ExplicitOrder
+from sphinx_gallery.sorting import ExplicitOrder
 
 import emcpy
 
@@ -44,33 +44,49 @@
 ]
 
 
+# Sphinx gallery configuration
+# gallery_order.py from the sphinxext folder provides the classes that
+# allow custom ordering of sections and subsections of the gallery
+from sphinxext.gallery_order import (
+    sectionorder as gallery_order_sectionorder,
+    subsectionorder as gallery_order_subsectionorder)
+
+# Create gallery dirs
+gallery_dirs = ["examples", "plot_types"]
+example_dirs = []
+for gd in gallery_dirs:
+    gd = gd.replace('gallery', 'examples')
+    example_dirs += [f'../galleries/{gd}']
+
 # Sphinx gallery configuration
 subsection_order = ExplicitOrder([
-    '../examples/line_plots',
-    '../examples/scatter_plots',
-    '../examples/histograms',
-    '../examples/map_plots'
+    '../galleries/plot_types/basic',
+    '../galleries/plot_types/statistical',
+    '../galleries/plot_types/gridded',
+    '../galleries/plot_types/map',
+    '../galleries/examples/line_plots',
+    '../galleries/examples/scatter_plots',
+    '../galleries/examples/histograms',
+    '../galleries/examples/map_plots'
 ])
 
 sphinx_gallery_conf = {
     'capture_repr': (),
     'filename_pattern': '^((?!skip_).)*$',
-    'examples_dirs': ['../examples'],   # path to example scripts
-    'gallery_dirs': ['gallery'],  # path to where to save gallery generated output
+    'examples_dirs': ['../galleries/examples', '../galleries/plot_types'],
+    'gallery_dirs': ['examples', 'plot_types'],  # path to where to save gallery generated output
     'backreferences_dir': '../build/backrefs',
     'subsection_order': subsection_order,
-    'within_subsection_order': ExampleTitleSortKey,
-    'matplotlib_animations': True,
+    'matplotlib_animations': True
 }
 
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '.ipynb']
 
 
 # -- Options for HTML output -------------------------------------------------

docs/getting_started/plots.md

@@ -1,3 +1,18 @@
 ## Plots
 
-Coming soon!
+The plotting section of EMCPy is the most mature and is used as the backend plotting for [eva](https://github.com/JCSDA-internal/eva). It uses declarative, object-oriented programming approach to handle complex plotting routines under the hood to simplify the experience for novice users while remaining robust so more experienced users can utilize higher-level applications.
+
+### Design
+The design was inspired by Unidata's [MetPy](https://github.com/Unidata/MetPy) declarative plotting syntax. The structure is broken into three different levels: plot type level, plot level, figure level
+
+#### Plot Type Level
+This is the level where users will define their plot type objects and associated plot details. This includes adding the related data the user wants to plot and how the user wants to display the data i.e: color, line style, marker style, labels, etc.
+
+#### Plot Level
+This level is where users design how they want the overall subplot to look. Users can add multiple plot type objects and define titles, x and y labels, colorbars, legends, etc. 
+
+#### Figure Level
+This level where users defines high-level specifics about the actual figure itself. These include figure size, layout, defining information about subplot layouts like rows and columns, saving the figure, etc. 
+
+
+For the current available plot types in EMCPy, see [Plot Types](../plot_types/index.rst).

docs/index.rst

@@ -10,7 +10,8 @@ EMCPy
     :hidden:
 
     getting_started/index
-    gallery/index
+    plot_types/index
+    examples/index
     installing
 
 

examples/README.txt → galleries/examples/README.txt

@@ -1,6 +1,8 @@
-Gallery
--------
+.. _examples:
+
+Examples
+--------
 
 The following examples show off the functionality of EMCPy. The examples
 give reference to what can be done with these collection of tools. Please
-do not hesitate to issue a pull request to add further examples!
+do not hesitate to issue a pull request to add further examples!

galleries/plot_types/README.txt

@@ -0,0 +1,6 @@
+.. _plot-types:
+
+Plot Types
+----------
+
+Here is a collection of the plot types that are currently available using EMCPy.

galleries/plot_types/basic/README.txt

@@ -0,0 +1,4 @@
+.. _basic:
+
+Basic
+=====

galleries/plot_types/basic/bar.py

@@ -0,0 +1,54 @@
+"""
+Bar Plot
+--------
+
+Below is an example of how to plot a bar
+plot using EMCPy's plotting method.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from emcpy.plots.plots import BarPlot
+from emcpy.plots.create_plots import CreatePlot, CreateFigure
+
+
+def main():
+    # Create bar plot
+
+    # Grab sample bar plot data
+    x_pos, heights = _getBarData()
+
+    # Create bar plot object
+    bar = BarPlot(x_pos, heights)
+    bar.color = 'tab:red'
+
+    # Create plot object and add features
+    plot1 = CreatePlot()
+    plot1.plot_layers = [bar]
+    plot1.add_xlabel(xlabel='X Axis Label')
+    plot1.add_ylabel(ylabel='Y Axis Label')
+    plot1.add_title("Bar Plot")
+
+    # Create figure
+    fig = CreateFigure()
+    fig.plot_list = [plot1]
+    fig.create_figure()
+
+    plt.show()
+
+
+def _getBarData():
+    # Generate test data for bar graphs
+
+    x = ['a', 'b', 'c', 'd', 'e', 'f']
+    heights = [5, 6, 15, 22, 24, 8]
+
+    x_pos = [i for i, _ in enumerate(x)]
+
+    return x_pos, heights
+
+
+if __name__ == '__main__':
+    main()

galleries/plot_types/basic/horizontal_bar.py

@@ -0,0 +1,54 @@
+"""
+Horizontal Bar Plot
+-------------------
+
+Below is an example of how to plot a horizontal
+bar plot using EMCPy's plotting method.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from emcpy.plots.plots import HorizontalBar
+from emcpy.plots.create_plots import CreatePlot, CreateFigure
+
+
+def main():
+    # Create horizontal bar plot
+
+    # Grab sample bar plot data
+    y_pos, widths = _getBarData()
+
+    # Create horizontal bar plot object
+    bar = HorizontalBar(y_pos, widths)
+    bar.color = 'tab:green'
+
+    # Create plot object and add features
+    plot1 = CreatePlot()
+    plot1.plot_layers = [bar]
+    plot1.add_xlabel(xlabel='X Axis Label')
+    plot1.add_ylabel(ylabel='Y Axis Label')
+    plot1.add_title("Horizontal Bar Plot")
+
+    # Create figure
+    fig = CreateFigure()
+    fig.plot_list = [plot1]
+    fig.create_figure()
+
+    plt.show()
+
+
+def _getBarData():
+    # Generate test data for bar graphs
+
+    x = ['a', 'b', 'c', 'd', 'e', 'f']
+    heights = [5, 6, 15, 22, 24, 8]
+
+    x_pos = [i for i, _ in enumerate(x)]
+
+    return x_pos, heights
+
+
+if __name__ == '__main__':
+    main()

galleries/plot_types/basic/horizontal_line.py

@@ -0,0 +1,45 @@
+"""
+Horizontal Line Plot
+--------------------
+
+Below is an example of how to plot a horizontal
+line using EMCPy's plotting method.
+
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from emcpy.plots.plots import HorizontalLine
+from emcpy.plots.create_plots import CreatePlot, CreateFigure
+
+
+def main():
+
+    y = 5
+
+    # Create vertical line plot object
+    hlp = HorizontalLine(y)
+    hlp.label = 'Horizontal Line'
+
+    # Add vertical line plot object to list
+    plt_list = [hlp]
+
+    # Create plot object and add features
+    plot1 = CreatePlot()
+    plot1.plot_layers = [hlp]
+    plot1.add_title('Horizontal Line Plot')
+    plot1.add_xlabel('X Axis Label')
+    plot1.add_ylabel('Y Axis Label')
+    plot1.add_legend(loc='upper right')
+
+    # Create figure
+    fig = CreateFigure()
+    fig.plot_list = [plot1]
+    fig.create_figure()
+
+    plt.show()
+
+
+if __name__ == '__main__':
+    main()

examples/line_plots/line_plot.py → galleries/plot_types/basic/line.py

@@ -1,6 +1,6 @@
 """
-Creating a simple line plot
----------------------------
+Line Plot
+---------
 
 Below is an example of how to plot a basic
 line plot using EMCPy's plotting method.
@@ -29,12 +29,12 @@ def main():
     # Create plot object and add features
     plot1 = CreatePlot()
     plot1.plot_layers = [lp]
-    plot1.add_title('Test Line Plot')
+    plot1.add_title('Line Plot')
     plot1.add_xlabel('X Axis Label')
     plot1.add_ylabel('Y Axis Label')
     plot1.add_legend(loc='upper right')
 
-    # Create figure and save as png
+    # Create figure
     fig = CreateFigure()
     fig.plot_list = [plot1]
     fig.create_figure()

examples/scatter_plots/scatter.py → galleries/plot_types/basic/scatter.py

@@ -1,6 +1,6 @@
 """
-Creating a simple scatter plot
-------------------------------
+Scatter Plot
+------------
 
 Below is an example of how to plot a basic
 scatter plot using EMCPy's plotting method.
@@ -15,18 +15,15 @@
 
 
 def main():
-    # Create test data
-    rng = np.random.RandomState(0)
-    x = rng.randn(100)
-    y = rng.randn(100)
 
-    # Create Scatter object
-    sctr1 = Scatter(x, y)
+    # Create scatter plot object
+    x1, y1, x2, y2 = _getScatterData()
+    sctr1 = Scatter(x1, y1)
 
     # Create plot object and add features
     plot1 = CreatePlot()
     plot1.plot_layers = [sctr1]
-    plot1.add_title(label='Test Scatter Plot')
+    plot1.add_title(label='Scatter Plot')
     plot1.add_xlabel(xlabel='X Axis Label')
     plot1.add_ylabel(ylabel='Y Axis Label')
 
@@ -38,5 +35,19 @@ def main():
     plt.show()
 
 
+def _getScatterData():
+    # Generate test data for scatter plots
+
+    rng = np.random.RandomState(0)
+    x1 = rng.randn(100)
+    y1 = rng.randn(100)
+
+    rng = np.random.RandomState(0)
+    x2 = rng.randn(30)
+    y2 = rng.randn(30)
+
+    return x1, y1, x2, y2
+
+
 if __name__ == '__main__':
     main()