Merge pull request #13 from Pennycook/plot-objects

Enable customization of plots

case-studies/babelstream/plot_babelstream_cascade.py

@@ -22,7 +22,6 @@
 
 # import libraries
 import pandas as pd
-import matplotlib.pyplot as plt
 import p3
 
 #sphinx_gallery_start_ignore
@@ -75,9 +74,8 @@
 # Generate a Cascade Plot
 # -----------------------
 
-fig = plt.figure(figsize=(6, 5))
-ax = p3.plot.cascade(effs) 
-plt.savefig("cascade.png", bbox_inches="tight")
+cascade = p3.plot.cascade(effs)
+cascade.save("cascade.png")
 
 # %%
 # The plot shows the *application efficiency* (line chart, left) and

case-studies/babelstream/plot_babelstream_navchart.py

@@ -18,7 +18,6 @@
 
 # import libraries
 import pandas as pd
-import matplotlib.pyplot as plt
 import p3
 
 #sphinx_gallery_start_ignore
@@ -104,9 +103,8 @@
 # Generate a Navigation Chart
 # ---------------------------
 
-fig = plt.figure(figsize=(5, 5))
-ax = p3.plot.navchart(pp, div)
-plt.savefig("navchart.png")
+navchart = p3.plot.navchart(pp, div)
+navchart.save("navchart.png")
 
 # %%
 # The plot shows the performance portability and code convergence values for

docs/source/conf.py

@@ -43,6 +43,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
     'sphinx_gallery.gen_gallery',
+    'sphinx.ext.intersphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -198,3 +199,7 @@ def __call__(self, *args, **kwargs):
      'gallery_dirs': ['examples','case-studies'],
      'image_scrapers': (tight_scraper(), ),
 }
+
+intersphinx_mapping = {
+    "matplotlib": ('https://matplotlib.org/stable/', None),
+}

docs/source/modules.rst

@@ -0,0 +1,7 @@
+p3
+==
+
+.. toctree::
+   :maxdepth: 4
+
+   p3

docs/source/p3.data.rst

@@ -5,6 +5,6 @@ Module contents
 ---------------
 
 .. automodule:: p3.data
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/p3.metrics.rst

@@ -5,6 +5,6 @@ Module contents
 ---------------
 
 .. automodule:: p3.metrics
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/p3.plot.backend.rst

@@ -0,0 +1,21 @@
+p3.plot.backend package
+=======================
+
+Submodules
+----------
+
+p3.plot.backend.matplotlib module
+---------------------------------
+
+.. automodule:: p3.plot.backend.matplotlib
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: p3.plot.backend
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/p3.plot.rst

@@ -1,10 +1,18 @@
 p3.plot package
 ===============
 
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   p3.plot.backend
+
 Module contents
 ---------------
 
 .. automodule:: p3.plot
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/p3.report.rst

@@ -5,6 +5,6 @@ Module contents
 ---------------
 
 .. automodule:: p3.report
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/p3.rst

@@ -5,16 +5,17 @@ Subpackages
 -----------
 
 .. toctree::
+   :maxdepth: 4
 
-    p3.data
-    p3.metrics
-    p3.plot
-    p3.report
+   p3.data
+   p3.metrics
+   p3.plot
+   p3.report
 
 Module contents
 ---------------
 
 .. automodule:: p3
-    :members:
-    :undoc-members:
-    :show-inheritance:
+   :members:
+   :undoc-members:
+   :show-inheritance:

examples/cascade/plot_customized_cascade.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# Copyright (c) 2023 Intel Corporation
+# SPDX-License-Identifier: 0BSD
+"""
+Customized Cascade
+==================
+
+A customized cascade plot.
+
+In this example, we show how to customize a cascade plot by changing the limits
+of the y-axis. Although the default limit (of 1) is useful for comparing many
+plots side-by-side, in practice it is often useful to be able to zoom-in on
+specific regions of data. For example, when dealing with applications that do
+not achieve very high levels of architectural efficiency, setting a lower
+maximum value for the y-axis can improve readability.
+
+Instead of trying to expose all possible customization options as arguments to
+:py:func:`p3.plot.cascade`, the function returns a
+:py:class:`p3.plot.CascadePlot` object that provides direct access to library
+internals. When using the :py:mod:`matplotlib` backend it is possible to
+access the :py:class:`matplotlib.axes.Axes` that were used and subsequently
+call any number of :py:mod:`matplotlib` functions. In our example, we can
+use :py:meth:`matplotlib.axes.Axes.set_ylim` to update the y-axis.
+
+.. NOTE::
+   :py:mod:`matplotlib` is currently the only backend supported by the P3
+   Analysis Library, but this is subject to change.
+
+.. TIP::
+   If you have any trouble customizing a plot, or the
+   :py:class:`~p3.plot.backend.CascadePlot` object does not provide access to
+   the internals you are looking for, then please `open an issue
+   <https://github.com/intel/p3-analysis-library/issues/new/choose>`_.
+"""
+
+import pandas as pd
+
+import p3
+
+# Initialize synthetic performance efficiency data
+# (not shown, but available in script download)
+# sphinx_gallery_start_ignore
+from collections import defaultdict
+
+data = defaultdict(list)
+for (i, platform) in enumerate(["A", "B", "C", "D", "E", "F", "G", "H", "I", "J"]):
+    data["problem"] += ["Synthetic"] * 6
+    data["platform"] += [platform] * 6
+    data["application"] += [
+        "Unportable",
+        "Single Target",
+        "Multi-Target",
+        "Consistent (3%)",
+        "Consistent (7%)",
+        "Inconsistent",
+    ]
+    eff = [0] * 6
+    eff[0] = 0.1 if i == 0 else 0
+    eff[1] = 0.1 if i == 0 else 0.01
+    eff[2] = 0.01 if i % 2 else 0.1
+    eff[3] = 0.03
+    eff[4] = 0.07
+    eff[5] = (i + 1) * 0.01
+    data["arch eff"] += eff
+# sphinx_gallery_end_ignore
+
+# Read performance efficiency data into pandas DataFrame
+df = pd.DataFrame(data)
+
+# Generate a cascade plot with custom style options
+legend = p3.plot.Legend(loc="center left", bbox_to_anchor=(0.91, 0.225), ncols=2)
+pstyle = p3.plot.PlatformStyle(colors="GnBu")
+astyle = p3.plot.ApplicationStyle(markers=["x", "s", "p", "h", "H", "v"])
+cascade = p3.plot.cascade(df, size=(6, 5), platform_legend=legend, platform_style=pstyle, application_style=astyle)
+
+# Further customize the cascade plot using matplotlib
+# In this example, we adjust the range of the y-axis to improve readability
+# This may be necessary for studies using architectural efficiency
+cascade.get_axes("eff").set_ylim([0, 0.12])
+cascade.get_axes("pp").set_ylim([0, 0.12])
+
+cascade.save("customized-cascade.png")

examples/cascade/plot_simple_cascade.py

@@ -32,8 +32,6 @@
 .. _Interpreting and Visualizing Performance Portability Metrics: https://doi.org/10.1109/P3HPC51967.2020.00007
 """
 
-import matplotlib as mpl
-import matplotlib.pyplot as plt
 import pandas as pd
 
 import p3
@@ -71,6 +69,5 @@
 df = pd.DataFrame(data)
 
 # Generate a cascade plot
-fig = plt.figure(figsize=(6, 5))
-ax = p3.plot.cascade(df)
-plt.savefig("cascade.png", bbox_inches="tight")
+cascade = p3.plot.cascade(df, size=(6, 5))
+cascade.save("cascade.png")

examples/navchart/plot_customized_navchart.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+# Copyright (c) 2023 Intel Corporation
+# SPDX-License-Identifier: 0BSD
+"""
+Customized Navigation Chart
+===========================
+
+A customized navigation chart.
+
+In this example, we show how to customize a navigation chart by increasing the
+number of axis ticks and by annotating one of the datapoints. Adjusting the
+number of axis ticks can improve a reader's ability to discern between two
+similar values, while annotations can be useful to draw attention to certain
+points and/or provide some additional context.
+
+Instead of trying to expose all possible customization options as arguments to
+:py:func:`p3.plot.navchart`, the function returns a
+:py:class:`p3.plot.NavChart` object that provides direct access to library
+internals. When using the :py:mod:`matplotlib` backend it is possible to
+access the :py:class:`matplotlib.axes.Axes` that were used and subsequently
+call any number of :py:mod:`matplotlib` functions. In our example, we can
+use :py:meth:`matplotlib.axes.Axes.set_xticks` and
+:py:meth:`matplotlib.axes.Axes.set_yticks` to control the ticks, and can use
+:py:meth:`matplotlib.axes.Axes.annotate` for annotations.
+
+.. NOTE::
+   :py:mod:`matplotlib` is currently the only backend supported by the P3
+   Analysis Library, but this is subject to change.
+
+.. TIP::
+   If you have any trouble customizing a navigation chart, or the
+   :py:class:`~p3.plot.backend.NavChart` object does not provide access to the
+   internals you are looking for, then please `open an issue
+   <https://github.com/intel/p3-analysis-library/issues/new/choose>`_.
+"""
+
+import matplotlib.pyplot as plt
+import pandas as pd
+
+import p3
+
+# Initialize synthetic data
+# (not shown, but available in script download)
+# sphinx_gallery_start_ignore
+from collections import defaultdict
+
+pp_data = defaultdict(list)
+cd_data = defaultdict(list)
+for data in [pp_data, cd_data]:
+    data["problem"] += ["Synthetic"] * 5
+    data["application"] += [
+        "Unportable",
+        "Ideal",
+        "Per-Platform Source",
+        "Portability Framework",
+        "Specialized",
+    ]
+pp_data["app pp"] += [0, 1, 1, 0.5, 0.7]
+cd_data["divergence"] += [1, 0, 1, 0, 0.3]
+# sphinx_gallery_end_ignore
+
+# Read performance portability and code divergence data into pandas DataFrame
+pp = pd.DataFrame(pp_data)
+cd = pd.DataFrame(cd_data)
+
+# Generate a navigation chart with custom style options
+legend = p3.plot.Legend(loc="center left", bbox_to_anchor=(1.0, 0.5))
+astyle = p3.plot.ApplicationStyle(markers=["x", "*", "s", "o", "P"])
+navchart = p3.plot.navchart(pp, cd, size=(5, 5), legend=legend, style=astyle)
+
+# Further customize the navigation chart using matplotlib
+# In this example, we add a label and adjust the ticks
+ax = navchart.get_axes()
+ax.annotate("Balances performance and code re-use.",
+            xy=(0.7, 0.7),
+            xytext=(0.2, 0.55),
+            arrowprops=dict(facecolor='black', shrink=0.05))
+ax.set_xticks([x * 0.1 for x in range(0, 11)])
+ax.set_yticks([y * 0.1 for y in range(0, 11)])
+
+navchart.save("customized-navchart.png")

examples/navchart/plot_simple_navchart.py

@@ -25,7 +25,6 @@
 of the P3 space and reasoning about how to reach development goals.
 """
 
-import matplotlib.pyplot as plt
 import pandas as pd
 
 import p3
@@ -55,6 +54,5 @@
 cd = pd.DataFrame(cd_data)
 
 # Generate a navigation chart
-fig = plt.figure(figsize=(5, 5))
-ax = p3.plot.navchart(pp, cd)
-plt.savefig("navchart.png")
+navchart = p3.plot.navchart(pp, cd, size=(5, 5))
+navchart.save("navchart.png")

p3/__init__.py

@@ -6,4 +6,4 @@
 import p3.plot
 import p3.report
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

p3/plot/__init__.py

@@ -3,5 +3,12 @@
 
 from p3.plot._cascade import cascade
 from p3.plot._navchart import navchart
+from p3.plot._common import Legend, ApplicationStyle, PlatformStyle
 
-__all__ = ["cascade", "navchart"]
+__all__ = [
+    "cascade",
+    "navchart",
+    "Legend",
+    "ApplicationStyle",
+    "PlatformStyle",
+]