Update Heatscatter Docs and add example

docs/examples/plotting/heatscatter.py

@@ -0,0 +1,35 @@
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+from pyrolite.plot import pyroplot
+
+# %% Minimal Example -------------------------------------------------------------------
+# create some example data
+from pyrolite.util.synthetic import test_df, random_cov_matrix
+
+df = test_df(
+    index_length=1000,
+    cov=random_cov_matrix(sigmas=np.random.rand(4) * 2, dim=4, seed=12),
+    seed=12,
+)
+
+fig, ax = plt.subplots(1, 3, sharex=True, sharey=True, figsize=(12, 4))
+
+df.loc[:, ["SiO2", "MgO"]].pyroplot.scatter(ax=ax[0], c="k", s=10, alpha=0.3)
+df.loc[:, ["SiO2", "MgO"]].pyroplot.density(ax=ax[1])
+df.loc[:, ["SiO2", "MgO"]].pyroplot.heatscatter(ax=ax[2], s=10, alpha=0.3)
+# %% Save Figure
+from pyrolite.util.plot import save_figure
+
+for t, a in zip(["Scatter", "Density", "Heatscatter"], ax):
+    a.set_title(t)
+save_figure(fig, save_at="../../source/_static", name="heatscatter_compare")
+
+# %% Density Ternary -------------------------------------------------------------------
+fig, ax = plt.subplots(1, 3, sharex=True, sharey=True, figsize=(14, 5))
+
+df.loc[:, ["SiO2", "CaO", "MgO"]].pyroplot.scatter(ax=ax[0], c="k", s=10, alpha=0.1)
+df.loc[:, ["SiO2", "CaO", "MgO"]].pyroplot.density(ax=ax[1], bins=100)
+df.loc[:, ["SiO2", "CaO", "MgO"]].pyroplot.heatscatter(ax=ax[2], s=5, alpha=0.3)
+# %% Save Figure
+save_figure(fig, save_at="../../source/_static", name="heatscatter_ternary")

docs/source/usage/eg/geochem/normalisation.rst

@@ -3,20 +3,6 @@ Normalisation
 
 A selection of reference compositions are included:
 
-.. code-block:: python
-
-  >>> from pyrolite.geochem.norm import ReferenceCompositions
-  >>> refcomp = ReferenceCompositions()
-  >>> refcomp
-  {
-   'BCC_RG2003': Model of BulkContinentalCrust (Rudnick & Gao 2003),
-   'BCC_RG2014': Model of BulkContinentalCrust (Rudnick & Gao 2014),
-   'Chondrite_MS95': Model of Chondrite (McDonough & Sun 1995),
-   ...
-   'UCC_RG2014': Model of UpperContinentalCrust (Rudnick & Gao 2014)
-  }
-
-
 .. code-block:: python
 
   >>> CH = refcomp['Chondrite_PON']

docs/source/usage/eg/plotting/density.rst

@@ -126,3 +126,4 @@ are specified:
 
 .. seealso:: `Ternary Plots <../plotting/ternary.html>`__,
              `Spider Density Diagrams <conditionaldensity.html>`__,
+             `Heatmapped Scatter Plots <heatscatter.html>`__,

docs/source/usage/eg/plotting/heatscatter.rst

@@ -0,0 +1,43 @@
+Heatscatter Plots
+==================================
+
+While :func:`~pyrolite.plot.pyroplot.density` plots are useful summary visualizations
+for large datasets, scatterplots are more precise and retain all spatial information
+(although they can get crowded).
+
+A scatter plot where individual points are coloured by data density in some respects
+represents the best of both worlds. A version inspired by similar existing
+visualisations is implemented with :func:`~pyrolite.plot.pyroplot.heatscatter`.
+
+.. literalinclude:: ../../../../examples/plotting/heatscatter.py
+   :language: python
+   :end-before: # %% Minimal Example
+
+We can compare a minimal :func:`~pyrolite.plot.pyroplot.heatscatter` plot to other
+visualisations for the same data:
+
+.. literalinclude:: ../../../../examples/plotting/heatscatter.py
+   :language: python
+   :start-after: # %% Minimal Example
+   :end-before: # %% Save Figure
+
+.. image:: ../../../_static/heatscatter_compare.png
+   :width: 100%
+   :align: center
+   :alt: Comparison of bivariate scatter plots, density plots and heatscatter plots.
+
+We can use the same interface for ternary diagrams:
+
+.. literalinclude:: ../../../../examples/plotting/heatscatter.py
+   :language: python
+   :start-after: # %% Density Ternary
+   :end-before: # %% Save Figure
+
+.. image:: ../../../_static/heatscatter_ternary.png
+   :width: 100%
+   :align: center
+   :alt: Comparison of ternary scatter plots, density plots and heatscatter plots.
+
+.. seealso:: `Ternary Plots <../plotting/ternary.html>`__,
+             `Density Plots <../plotting/density.html>`__,
+             `Spider Density Diagrams <conditionaldensity.html>`__

docs/source/usage/eg/plotting/ternary.rst

@@ -29,4 +29,5 @@ change in the near future as needs change, but works well for scatter plots.
    :align: center
    :alt: Two ternary plots placed on separate axes by specifying a pre-existing axis.
 
-.. seealso:: `Density Plots <../plotting/density.html>`__
+.. seealso:: `Density Plots <../plotting/density.html>`__,
+             `Heatmapped Scatter Plots <heatscatter.html>`__