Download This Notebook: Introduction.ipynb

Introduction

This tutorial provides a brief overview of the key features of the GrAF format and demonstrates how to interact with GrAF files in Python.

Interacting with a GrAF file

Creating a GrAF file

The easiest way to create a GrAF file in Python is to convert a matplotlib figure directly to a Graf object. The Graf class then provides functions for saving it to a file.

from graf.base import *
import matplotlib.pyplot as plt

# Example data
x1 = [1,2,3,4,5,6,7,8,9,10]
y1 = [7,3,7,6,5,7,2,1,9, 0]

# Make the plot in matplotlib
fig1, ax1 = plt.subplots(nrows=1)
ax1.plot(x1, y1, marker='o', linestyle=':', color=(0.8, 0, 0.4))
ax1.set_xlabel("X-axis")
ax1.set_ylabel("Y-axis")
fig1.suptitle("GrAF Example 1")
ax1.grid(True)

# Now we make the GrAF object. It accepts a matplotlib figure as an optional
# parameter which we're using here to initialize the object with our desired
# plot.
graf_fig1 = Graf(fig1)

# Now save it to a file!
graf_fig1.save_hdf("ex1_fig1.graf")

#NOTE: It's really important that you don't call plt.show() before passing the
# matplotlib figure to GrAF! Otherwise, once you close the figure, the figure
# handle will point to an empty figure and your GrAF file won't contain any
# useful data!
plt.show()

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[1], line 1
----> 1 from graf.base import *
      2 import matplotlib.pyplot as plt
      3
      4 # Example data

File ~/checkouts/readthedocs.org/user_builds/graf/envs/latest/lib/python3.12/site-packages/graf/base.py:6
      4 import matplotlib.pyplot as plt
      5 from abc import ABC, abstractmethod
----> 6 from jarnsaxa import hdf_to_dict, dict_to_hdf
      7 from pylogfile.base import *
      8 import copy

ModuleNotFoundError: No module named 'jarnsaxa'

Reading a GrAF file

Reading in the file is similarly easy…

# Make the GrAF object. Note that we aren't initializing the object with any
# data. That's because we're going to overwrite everything inside this object
# with the contents of our GrAF file.
graf2 = Graf()

# Read the file
graf2.load_hdf("ex1_fig1.graf")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[2], line 4
      1 # Make the GrAF object. Note that we aren't initializing the object with any
      2 # data. That's because we're going to overwrite everything inside this object
      3 # with the contents of our GrAF file.
----> 4 graf2 = Graf()
      5
      6 # Read the file
      7 graf2.load_hdf("ex1_fig1.graf")

NameError: name 'Graf' is not defined

Now the figure data is saved in our Graf object. To plot the data, we can use to_fig(), which creates a matplotlib graph from the figure data.

# Create a matplotlib figure
fig2 = graf2.to_fig()

# Show the figure
plt.show()

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[3], line 2
      1 # Create a matplotlib figure
----> 2 fig2 = graf2.to_fig()
      3
      4 # Show the figure
      5 plt.show()

NameError: name 'graf2' is not defined

Great! We just saved a plot to disk using a GrAF file and read it back!

Accessing the Underlying Data

One of the most powerful features of GrAF is that saving and restoring graphs isn’t all it can do; it also aims to make it easy to access the underlying data. From here, you can merge multiple graphs together, reanalyze data, or whatever else your heart desires <3.

# To directly access the underlying data, we have to specify which axes (Ax0)
# and which trace (Tr0) we want to look at.
extracted_x_data = graf2.axes['Ax0'].traces['Tr0'].x_data
extracted_y_data = graf2.axes['Ax0'].traces['Tr0'].y_data

print(f"Extracted data:")
print(f"    x: {extracted_x_data}")
print(f"    y: {extracted_y_data}")

---------------------------------------------------------------------------
NameError                                 Traceback (most recent call last)
Cell In[4], line 3
      1 # To directly access the underlying data, we have to specify which axes (Ax0)
      2 # and which trace (Tr0) we want to look at.
----> 3 extracted_x_data = graf2.axes['Ax0'].traces['Tr0'].x_data
      4 extracted_y_data = graf2.axes['Ax0'].traces['Tr0'].y_data
      5
      6 print(f"Extracted data:")

NameError: name 'graf2' is not defined