Beginner’s Guide¶

Beginner’s Guide to Plotting with sattoolbox¶

This Guide is best viewed in your IDE (VSCode), in Gitlab directly or as pdf.

How to get started¶

Download the latest release from https://gitlab.uni-kassel.de/sat/sat-private/sattoolbox/-/releases
Unpack the .zip file to a location of your choice on your machine. Suggestion: Put it into a folder called “local_packages” that is placed where you also keep your other “python stuff”.
Add the library to the PYTHONPATH.
The easiest way is to add the following code to the script where you want to use sattoolbox. Remember to change the “path/to/sattoolbox” to the folder where you saved it on your machine.
```
import sys
sys.path.append('C:/path/to/sattoolbox-v0.x.y')
# Keep the last sattoolbox (with the version or branch name)
```
Check for necessary 3rd-party packages requirements and install or update them via your python package manager (conda / Anaconda / pip)
Run the plots.example() in script_examples. It is normal that this yields many warnings, but it should finish without errors.

How to plot¶

Prepare your data
The data needs to be in a pd.DataFrame. You can create the Dataframe from scratch (see Example below) or read it from a .csv file (pd.read_csv(…))

Example Data

 # import the pandas package
 import pandas as pd
 # Create a sample DataFrame
 data_list = list(range(48))
 data = {'T_1': data_list,
         'T_2': [sqrt(x) for x in data_list],
         'XY1' : [2*x for x in data_list],
         'm_flow': [10+x for x in data_list],}
 hours = pd.date_range(start="2023-01-01", end="2023-01-02 23:00", freq="1h")
 df = pd.DataFrame(data, index=hours)

Import sattolbox.plots
This makes the sattoolbox available within your python file (something.py). Usually this is done at the top of your script. Remember to change the “path/to/sattoolbox” to where you saved it.
```
import sys
sys.path.append('C:/path/to/sattoolbox-v0.x.y')
from sattoolbox.plots import plots
```
Create a Plotter object
The Plotter object allows to make plots with the same style settings (e.g. with presentation style-default).
```
plotter = plots.Plotter(style_default='presentation')
```
Use the plotter to plot your data (df)
This command returns the figure (fig) and axis (ax) object that were created, so that you can do more stuff with it (fine tuning, save the plot…). This step can be done many times with the same plotter.
```
# This will plot all columns of df in a line plot
fig, ax = plotter.plot(df)
```
Resulting Plot

Customize your plot with Parameters (More on Parameters)

fig, axs = plotter.plot(df, kind='line',
                    ycols=['T_1','T_2'], ylabel='Temperature in °C',
                    xcols='m_flow', xlabel='Mass Flow Rate in kg/h',
                    sec_ycols='XY1', sec_ylabel='XY',
                    sec_ylim = (0, 100),
                    legend_loc='outside upper right',
                    linestyle=['solid','dotted', 'dashed'])

Note that now a primary and secondary axis are used and thus the plotter.plot() method returns the figure and a tuple of ax-objects. Thus, it is good practice to save this in a variable called “axs” (instead of ax) to remember later on, that this is a tuple of primary and secondary axes.

Resulting Plot

Use the returned fig and ax objects to do adjustments as necessary

axs[0].set_ylim(-50,50)
axs[1].set_ylim(0, 150)
axs[0].set_ylabel('Temperature in °C', color='blue')
axs[1].set_ylabel('XY', color='red')

Resulting Plot

Customizing your Plots with Parameters¶

See the docs for a general description of the parameters of the plot()-method.
sattoolbox builds upon pandas.DataFrame.plot() and matplotlib. All parameters that can be passed to pandas.DataFrame.plot() as well as all matplotlib.rcParams can be passed into the plot()-method.
See the example plots for many examples using various parameters for various different plot kinds.

Most important Parameters¶

kind: What kind of plot to create
Available Plots
- line
- bar
- barh
- hist
- box
- kde
- density
- area
- pie
- scatter
- hexbin
- multi_scatter
- R2_scatter
- R2_hexbin
- check plotter.plot_kinds_pd and plotter.plot_kinds_custom for potentially further plot types that were implemented but forgotten to list here.
xcols: Which column(s) to use for the x-axis (default is index)
xlabel: Label for the x-axis
ycols: Which column(s) to use for the y-axis (default is all columns)
ylabel: Label for the y-axis
ax, fig: Pass both to plot onto an already existing plot
style: Style-sheet to use. All matplotlib styles as well as custom styles and SAT-specific styles can be used.
Available SAT styles
- paper
- paper_half
- paper_full
- bw_paper
- bw_paper_half
- bw_paper_full
- screen
- presentation
- presentation_half
color: The color(s) in which to display individual lines (or bars, points, areas, …).
- Single color (as string): All lines are plotted in this color
- list-like of colors: The plotter will cycle through the list for each line
- ‘cycle’: The default color-cycle will be used (default for color)
  (The same concept works for all line properties like linestyle, marker, linewidth, …)

Parameter Groups¶

Some parameters are treated separately if they have a special prefix. Generally, this means that those parameters are not passed to pandas.DataFrame.plot(), they are instead handled separately or passed to the corresponding matplotlib-method. Currently this applies to secondary y-axis and legend parameters.

Secondary y-axis¶

prefix: ‘sec_’ or ‘secondary_’
Those parameters are all used for a secondary y-axis on the same plot. Passing at least ‘sec_ycols’ will create a secondary yaxis with ax2 = ax1.twinx(). All parameters with the ‘sec’-prefix will override the parameters without prefix for the secondary axis. Other parameters are kept.

Example

fig, axs = plotter.plot(df, ycols=['T_1','T_2'], color='red',
                    sec_ycols='XY1', sec_color='blue',
                    sec_ylim = (0, 100), linestyle='dashed'
                    )

The color ‘red’ of the primary axis is overridden by the ‘sec_color’ ‘blue’, while the linestyle ‘dashed’ is applied to both axis. A list of colors (or any line-property) passed to the primary axis would be continued on the secondary axis (see below).

fig, axs = plotter.plot(df, ycols=['T_1','T_2'],
                        color=['red', 'blue', 'green'],
                        sec_ycols='XY1', sec_ylim = (0, 100))

Legend Parameters¶

prefix: ‘legend_’ or ‘leg_’
matplotlib-method: ax.legend()/fig.legend
The sattoolbox legend-creation offers the following enhancements over the matplotlib legend()-methods:

legend placement outside of the diagram area

prefix ‘outside’ before matplotlib location identifiers

‘legend_loc’: keyword argument to place the legend

Location Identifiers

  - 'best' (default)
  - 'upper right'
  - 'upper left'
  - 'lower left'
  - 'lower right'
  - 'right'
  - 'center left'
  - 'center right'
  - 'lower center'
  - 'upper center'
  - 'center'
  - 'outside upper right'
  - 'outside upper left'
  - 'outside upper center'
  - 'outside lower left'
  - 'outside lower right'
  - 'outside lower center'
  - 'outside right upper'
  - 'outside left upper'
  - 'outside left center'
  - 'outside left lower'
  - 'outside right lower'
  - 'outside right center'

Combined legend for first and secondary y-axis
- The entries of both axes are put into a single legend separated by legend subtitles ‘Left axis:’, ‘Right axis:’ (can be modified with legend_title = (‘subtitle left’, ‘subtitle_right’))
- The right axis and left axis entries are distributed (usefully) into separate legend columns (‘legend_ncols’-Parameter)
Changing the legend entries
- The legend entries can be changed from the default (the column names)
1. Passing a list with new legend labels to ‘legend_labels’ (in the same order and length as the plotted columns)
2. Passing a dictionary to rename specific lables. ‘legend_labels’={‘old_label’ : ‘new_label’} (Any length and order. Only existing labels are updated)

Using Style Sheets¶

General information about matploblib and style sheets can be found here. Style sheets can be integrated by passing them during the creation of the plotter object.

plotter = plots.Plotter(style_default='style sheet name')

or during plot-method call (this will be used instead of the style-default for this method-call only)

plotter.plot(df, ..., style='style sheet name')

All style sheets that are in the matplotlib installation can be used (plt.style.available), own style sheets can be used by passing the path to that style sheet. SAT-style sheets can be used by using their names. SAT custom styles are available for different use cases (screen, presentation, paper). The styles all use the sat_base style and extend or ovveride from that. The base style mostly defines the default color cycle, and the setup of the axis and ticks.

Presentation Styles: (Optimized size and fontsize (18) for presentations)
- ‘presentation’: style for plots filling the whole width of the presentation slide.
- ‘presentation_half’: style for plots filling half the width (2 plots or plot plus text)
Paper style sheets:
- Reduced font size: 10
- Linewidth, Markersize and ticks-size reduced
- Various Paper Styles:
  - Sizes: regular (1.5 col –> 5.5 inch), half –> 5.5 inch, full –> 7.4 inch (see Elsevier author guidelines)
  - Black&White Paper (bw_paper): Color (3 shades of grey/black) and Linestyle Cycle, Grid turned off
Screen Style:
- Size fitted to be almost fullscreen on a Full HD Screen
- Facecolor: White
- Fontsize: 20
- Both minor and Major Grid activated
Available styles are:
- paper
- paper_half
- paper_full
- bw_paper
- bw_paper_half
- bw_paper_full
- screen
- presentation
- presentation_half

Improving this Guide¶

Hopefully, this guide helped you to start with plotting with sattoolbox. Please let us know (personally or through an issue on gitlab), if something did not work, if explanations need improvement or if important questions were left open.