Plotting Tutorial

This tutorial demonstrates how to use the plotting capabilities of the AFL.double_agent package to visualize compositional and scattering data.

Introduction

The AFL.double_agent.plotting module provides a variety of plotting functions for visualizing materials data. It supports:

• Compositional data visualization (scatter and surface plots)

• Small-angle scattering data visualization

• Both 2D and 3D plots

• Ternary plots for three-component systems

• Multiple backends (Matplotlib and Plotly)

In this tutorial, we’ll explore these capabilities using example datasets.

Google Colab Setup

Only uncomment and run the next cell if you are running this notebook in Google Colab or if don’t already have the AFL-agent package installed.

# !pip install git+https://github.com/usnistgov/AFL-agent.git

General Setup

First, let’s import the necessary modules and load our example dataset:

import numpy as np
import matplotlib.pyplot as plt
import xarray as xr

# Import the plotting module
from AFL.double_agent.plotting import plot, plot_scatter_mpl, plot_surface_mpl, plot_sas_mpl
from AFL.double_agent.plotting import plot_scatter_plotly, plot_surface_plotly, plot_sas_plotly

# Load the example dataset
from AFL.double_agent.data import example_dataset1

import plotly.io as pio
pio.renderers.default = "iframe_connected"
# pio.renderers.default = "plotly_mimetype"

# Load the dataset
ds = example_dataset1()

# Display the dataset structure
ds

<xarray.Dataset> Size: 164kB
Dimensions:              (sample: 100, component: 2, x: 150, grid: 2500)
Coordinates:
  * component            (component) <U1 8B 'A' 'B'
  * x                    (x) float64 1kB 0.001 0.001047 0.001097 ... 0.9547 1.0
Dimensions without coordinates: sample, grid
Data variables:
    composition          (sample, component) float64 2kB ...
    ground_truth_labels  (sample) int64 800B ...
    measurement          (sample, x) float64 120kB ...
    composition_grid     (grid, component) float64 40kB ...

xarray.Dataset

• Dimensions:
  • sample: 100
  • component: 2
  • x: 150
  • grid: 2500
• Coordinates: (2)
  • component
    (component)
    <U1
    'A' 'B'

    array(['A', 'B'], dtype='<U1')

  • x
    (x)
    float64
    0.001 0.001047 ... 0.9547 1.0

    array([0.001   , 0.001047, 0.001097, 0.001149, 0.001204, 0.001261, 0.001321,
           0.001383, 0.001449, 0.001518, 0.00159 , 0.001665, 0.001744, 0.001827,
           0.001914, 0.002005, 0.0021  , 0.002199, 0.002304, 0.002413, 0.002527,
           0.002647, 0.002773, 0.002905, 0.003042, 0.003187, 0.003338, 0.003496,
           0.003662, 0.003836, 0.004018, 0.004209, 0.004409, 0.004618, 0.004837,
           0.005066, 0.005307, 0.005559, 0.005822, 0.006099, 0.006388, 0.006691,
           0.007009, 0.007341, 0.00769 , 0.008055, 0.008437, 0.008837, 0.009256,
           0.009696, 0.010156, 0.010638, 0.011142, 0.011671, 0.012225, 0.012805,
           0.013413, 0.014049, 0.014716, 0.015414, 0.016146, 0.016912, 0.017714,
           0.018555, 0.019435, 0.020358, 0.021324, 0.022335, 0.023395, 0.024505,
           0.025668, 0.026886, 0.028162, 0.029498, 0.030898, 0.032364, 0.0339  ,
           0.035509, 0.037194, 0.038959, 0.040807, 0.042744, 0.044772, 0.046897,
           0.049122, 0.051453, 0.053894, 0.056452, 0.059131, 0.061936, 0.064875,
           0.067954, 0.071179, 0.074556, 0.078094, 0.0818  , 0.085681, 0.089747,
           0.094006, 0.098467, 0.103139, 0.108033, 0.11316 , 0.118529, 0.124154,
           0.130045, 0.136216, 0.14268 , 0.14945 , 0.156542, 0.16397 , 0.171751,
           0.179901, 0.188438, 0.197379, 0.206746, 0.216556, 0.226832, 0.237596,
           0.24887 , 0.26068 , 0.27305 , 0.286006, 0.299578, 0.313794, 0.328684,
           0.344281, 0.360618, 0.37773 , 0.395654, 0.414429, 0.434094, 0.454693,
           0.476269, 0.498869, 0.522542, 0.547337, 0.57331 , 0.600514, 0.62901 ,
           0.658858, 0.690122, 0.72287 , 0.757172, 0.793102, 0.830736, 0.870156,
           0.911447, 0.954697, 1.      ])

• Data variables: (4)
  • composition
    (sample, component)
    float64
    ...

    [200 values with dtype=float64]

  • ground_truth_labels
    (sample)
    int64
    ...

    [100 values with dtype=int64]

  • measurement
    (sample, x)
    float64
    ...

    [15000 values with dtype=float64]

  • composition_grid
    (grid, component)
    float64
    ...

    [5000 values with dtype=float64]

• Indexes: (2)
  • component
    PandasIndex

    PandasIndex(Index(['A', 'B'], dtype='object', name='component'))

  • x
    PandasIndex

    PandasIndex(Index([                0.001, 0.0010474522360006332, 0.0010971561867027272,
           0.0011492187010036998, 0.0012037516980200685, 0.0012608724076806808,
            0.001320703622736631, 0.0013833739627296209,  0.001449018150486198,
           0.0015177773017322714,
           ...
              0.6588581861506815,    0.6901224802908528,    0.7228703350949566,
                0.75717214883374,    0.7931016603333051,    0.8307361074919352,
              0.8701563933188907,    0.9114472598521185,    0.9546974703287516,
                             1.0],
          dtype='float64', name='x', length=150))

• Attributes: (0)

The example dataset contains compositional data and measurements that we can use for our plots.

Compositional Data Visualization

Scatter Plots

Let’s start with a simple scatter plot of our compositional data using Matplotlib:

# Create a scatter plot using Matplotlib
plt.figure(figsize=(8, 6))
artists = plot_scatter_mpl(
    dataset=ds,
    component_variable='composition',
    labels='ground_truth_labels',
    discrete_labels=True
)
plt.title('Composition Scatter Plot (Matplotlib)')
plt.show()

<Figure size 800x600 with 0 Axes>

We can also create the same plot using the unified plot function:

# Create a scatter plot using the unified plot function
plt.figure(figsize=(8, 6))
artists = plot(
    dataset=ds,
    kind='scatter',
    backend='mpl',
    component_variable='composition',
    labels='ground_truth_labels',
    discrete_labels=True
)
plt.title('Composition Scatter Plot (Unified API)')
plt.show()

<Figure size 800x600 with 0 Axes>

Now, let’s create an interactive scatter plot using Plotly.

# Create a scatter plot using Plotly
fig = plot_scatter_plotly(
    dataset=ds,
    component_variable='composition',
    labels='ground_truth_labels',
    discrete_labels=True
)
fig.update_layout(title='Composition Scatter Plot (Plotly)')
fig.show()

Surface Plots

Surface plots are useful for visualizing continuous fields over compositional space:

# Create a surface plot using Matplotlib
plt.figure(figsize=(8, 6))
artists = plot_surface_mpl(
    dataset=ds,
    component_variable='composition',
    labels='ground_truth_labels'
)
plt.colorbar(artists)
plt.title('Composition Surface Plot (Matplotlib)')
plt.show()

<Figure size 800x600 with 0 Axes>

And with Plotly:

# Create a surface plot using Plotly
fig = plot_surface_plotly(
    dataset=ds,
    component_variable='composition',
    labels='ground_truth_labels'
)
fig.update_layout(title='Composition Surface Plot (Plotly)')
fig.show()

Small-Angle Scattering Data Visualization

The measurement variable in our dataset can be treated as scattering data for demonstration purposes.

Log-Log Plots

Log-log plots are commonly used for scattering data:

# Create a log-log plot using Matplotlib
plt.figure(figsize=(8, 6))
artists = plot_sas_mpl(
    dataset=ds,
    plot_type='loglog',
    x='x',
    y='measurement',
    xlabel='q (Å⁻¹)',
    ylabel='Intensity (a.u.)',
    legend=False,
)
plt.title('Scattering Data Log-Log Plot (Matplotlib)')
plt.show()

And with Plotly:

# Create a log-log plot using Plotly
fig = plot_sas_plotly(
    dataset=ds,
    plot_type='loglog',
    x='x',
    y='measurement',
    xlabel='q (Å⁻¹)',
    ylabel='Intensity (a.u.)'
)
fig.update_layout(title='Scattering Data Log-Log Plot (Plotly)')
fig.show()

Waterfall Plots

Waterfall plots are useful for comparing multiple scattering curves:

# Create a log waterfall plot using Matplotlib
plt.figure(figsize=(10, 8))
artists = plot_sas_mpl(
    dataset=ds,
    plot_type='logwaterfall',
    x='x',
    y='measurement',
    xlabel='q (Å⁻¹)',
    ylabel='Intensity (a.u.)',
    base=5, # Separation factor between curves
    legend=False,
)
plt.title('Scattering Data Log Waterfall Plot (Matplotlib)')
plt.show()

And with Plotly:

# Create a log waterfall plot using Plotly
fig = plot_sas_plotly(
    dataset=ds,
    plot_type='logwaterfall',
    x='x',
    y='measurement',
    xlabel='q (Å⁻¹)',
    ylabel='Intensity (a.u.)',
    base=5  # Separation factor between curves
)
fig.update_layout(title='Scattering Data Log Waterfall Plot (Plotly)')
fig.show()

Linear Plots

For some data, linear plots might be more appropriate. This is often used when the data has been log-scaled already.

# Create a linear plot using Matplotlib

plt.figure(figsize=(8, 6))
artists = plot_sas_mpl(
    dataset=ds,
    plot_type='linlin',
    x='x',
    y='measurement',
    xlabel='q (Å⁻¹)',
    ylabel='Intensity (a.u.)'
)
plt.title('Scattering Data Linear Plot (Matplotlib)')
plt.show()

Advanced Features

3D Plots for Three-Component Systems

For three-component systems, we can create 3D plots:

# Create a synthetic three-component dataset
n_samples = 100
components = np.random.random((n_samples, 3))
# Normalize to sum to 1
components = components / components.sum(axis=1, keepdims=True)

# Create labels
labels = np.zeros(n_samples)
labels[components[:, 0] > 0.6] = 1
labels[components[:, 1] > 0.6] = 2

# Create the dataset
three_comp_ds = xr.Dataset(
    data_vars={
        'compositions': (['sample', 'component'], components)
    },
    coords={
        'component': ['A', 'B', 'C'],
        'labels': (['sample'], labels)
    }
)

# Create a 3D scatter plot (non-ternary)
fig = plot_scatter_plotly(
    dataset=three_comp_ds,
    component_variable='compositions',
    labels='labels',
    discrete_labels=True,
    ternary=False  # Use 3D Cartesian plot instead of ternary
)
fig.update_layout(title='Three-Component Scatter Plot (3D)')
fig.show()

Ternary Plots

For three-component systems, ternary plots are often more intuitive:

fig = plot_scatter_plotly(
    dataset=three_comp_ds,
    component_variable='compositions',
    labels='labels',
    discrete_labels=True,
    ternary=True  # Use ternary plot
)
fig.update_layout(title='Three-Component Scatter Plot (Ternary)')
fig.show()

Conclusion

In this tutorial, we’ve explored the plotting capabilities of the AFL.double_agent package. We’ve seen how to:

• Create scatter and surface plots for compositional data

• Visualize small-angle scattering data with various plot types

• Work with both 2D and 3D plots

• Create ternary plots for three-component systems

• Use both Matplotlib and Plotly backends

• Customize plots to suit specific needs

The unified plot function provides a convenient interface to all these capabilities, making it easy to switch between plot types and backends.

For more details on the available plotting functions and their parameters, refer to the API documentation.