Plotting API
This describes the plotting API which is a part of the relax library.
Packages
The flow of execution for plotting XY-type data in relax is:
- The user function definition in the user_functions.grace module (in the future the user_functions.plotting module).
- The pipe_control.plotting.write_xy() function.
- The lib.plotting functions write_xy_header() and write_xy_data().
Package: user_functions
The user interface for plotting are generally the user functions. Currently this consists of the grace.write and dx.map user functions. However in the future a software independent interface will be gradually implemented via a new plotting user function class. An idea would be to have one user function per graph type, for example:
- plotting.write_2D
- plotting.write_iso3D
- plotting.write_2D_fitted_curves
The user_functions package consists of definitions that are used to construct the prompt or graphical UI and to set up automated argument checking.
Package: pipe_control
The user functions provide a simple interface to the relax backend. For plotting and most functionality, this is in the pipe_control package which is used primarily to read and write data to the relax data store. However power-users can bypass the user function interface and directly use the backend code for greater functionality. This also allows for the implementation of new features without modifying the user interface. To use the backend code, for example for plotting XY-type data, one needs to import:
from pipe_control.plotting import write_xy
The write_xy() function will assemble the data from the relax data store via the assemble_data() function. It will then call the plotting API functions write_xy_header() and write_xy_data().
Package: lib
The plotting API is located in the lib.plotting relax library package. The API is defined within the lib.plotting.api module. This consists of a collection of plotting functions, each of which accepts the 'format' argument. The format argument is then used to determine which function in which module in lib.plotting will be called. For example see the correlation_matrix() function.
To implement a new plotting feature for a certain software package, for example for Gnuplot, an equivalent function should be provided in the lib.plotting.gnuplot module. This should have the same name as the API function and accept exactly the same arguments, excluding the format argument.
Development
To add a new plotting feature, the following steps are required:
- For a new software type, a new module in lib.plotting must be created.
- For a new graph type, a new function should be added to the lib.plotting.api module. The first function argument should be 'format'.
- Implement the plotting function in the software specific module. This should have identical arguments to the lib.plotting.api function, but without the initial 'format' argument.
- Register the software specific function in the API by adding it to the software independent function in lib.plotting.api.