flixopt.plotting

This module contains the plotting functionality of the flixopt framework. It provides high level functions to plot data with plotly and matplotlib. It's meant to be used in results.py, but is designed to be used by the end user as well.

Attributes

ColorType module-attribute

ColorType = Union[str, List[str], Dict[str, str]]

Identifier for the colors to use. Use the name of a colorscale, a list of colors or a dictionary of labels to colors. The colors must be valid color strings (HEX or names). Depending on the Engine used, other formats are possible. See also: - https://htmlcolorcodes.com/color-names/ - https://matplotlib.org/stable/tutorials/colors/colormaps.html - https://plotly.com/python/builtin-colorscales/

PlottingEngine module-attribute

PlottingEngine = Literal['plotly', 'matplotlib']

Identifier for the plotting engine to use.

Classes

ColorProcessor

ColorProcessor(engine: PlottingEngine = 'plotly', default_colormap: str = 'viridis')

Class to handle color processing for different visualization engines.

Initialize the color processor.

Parameters:

Name	Type	Description	Default
engine	PlottingEngine	The plotting engine to use ('plotly' or 'matplotlib')	'plotly'
default_colormap	str	Default colormap to use if none is specified	'viridis'

Functions

process_colors

process_colors(colors: ColorType, labels: List[str], return_mapping: bool = False) -> Union[List[Any], Dict[str, Any]]

Process colors for the specified labels.

Parameters:

Name	Type	Description	Default
colors	ColorType	Color specification (colormap name, list of colors, or label-to-color mapping)	required
labels	List[str]	List of data labels that need colors assigned	required
return_mapping	bool	If True, returns a dictionary mapping labels to colors; if False, returns a list of colors in the same order as labels	False

Returns:

Type	Description
Union[List[Any], Dict[str, Any]]	Either a list of colors or a dictionary mapping labels to colors

Functions

with_plotly

with_plotly(data: DataFrame, mode: Literal['bar', 'line', 'area'] = 'area', colors: ColorType = 'viridis', title: str = '', ylabel: str = '', xlabel: str = 'Time in h', fig: Optional[Figure] = None) -> go.Figure

Plot a DataFrame with Plotly, using either stacked bars or stepped lines.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame containing the data to plot, where the index represents time (e.g., hours), and each column represents a separate data series.	required
mode	Literal['bar', 'line', 'area']	The plotting mode. Use 'bar' for stacked bar charts, 'line' for stepped lines, or 'area' for stacked area charts.	'area'
colors	ColorType	Color specification, can be: - A string with a colorscale name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping column names to colors (e.g., {'Column1': '#ff0000'})	'viridis'
title	str	The title of the plot.	''
ylabel	str	The label for the y-axis.	''
fig	Optional[Figure]	A Plotly figure object to plot on. If not provided, a new figure will be created.	None

Returns:

Type	Description
Figure	A Plotly figure object containing the generated plot.

with_matplotlib

with_matplotlib(data: DataFrame, mode: Literal['bar', 'line'] = 'bar', colors: ColorType = 'viridis', title: str = '', ylabel: str = '', xlabel: str = 'Time in h', figsize: Tuple[int, int] = (12, 6), fig: Optional[Figure] = None, ax: Optional[Axes] = None) -> Tuple[plt.Figure, plt.Axes]

Plot a DataFrame with Matplotlib using stacked bars or stepped lines.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame containing the data to plot. The index should represent time (e.g., hours), and each column represents a separate data series.	required
mode	Literal['bar', 'line']	Plotting mode. Use 'bar' for stacked bar charts or 'line' for stepped lines.	'bar'
colors	ColorType	Color specification, can be: - A string with a colormap name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping column names to colors (e.g., {'Column1': '#ff0000'})	'viridis'
title	str	The title of the plot.	''
ylabel	str	The ylabel of the plot.	''
xlabel	str	The xlabel of the plot.	'Time in h'
figsize	Tuple[int, int]	Specify the size of the figure	(12, 6)
fig	Optional[Figure]	A Matplotlib figure object to plot on. If not provided, a new figure will be created.	None
ax	Optional[Axes]	A Matplotlib axes object to plot on. If not provided, a new axes will be created.	None

Returns:

Type	Description
Tuple[Figure, Axes]	A tuple containing the Matplotlib figure and axes objects used for the plot.

Notes

• If mode is 'bar', bars are stacked for both positive and negative values. Negative values are stacked separately without extra labels in the legend.
• If mode is 'line', stepped lines are drawn for each data series.
• The legend is placed below the plot to accommodate multiple data series.

heat_map_matplotlib

heat_map_matplotlib(data: DataFrame, color_map: str = 'viridis', title: str = '', xlabel: str = 'Period', ylabel: str = 'Step', figsize: Tuple[float, float] = (12, 6)) -> Tuple[plt.Figure, plt.Axes]

Plots a DataFrame as a heatmap using Matplotlib. The columns of the DataFrame will be displayed on the x-axis, the index will be displayed on the y-axis, and the values will represent the 'heat' intensity in the plot.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame containing the data to be visualized. The index will be used for the y-axis, and columns will be used for the x-axis. The values in the DataFrame will be represented as colors in the heatmap.	required
color_map	str	The colormap to use for the heatmap. Default is 'viridis'. Matplotlib supports various colormaps like 'plasma', 'inferno', 'cividis', etc.	'viridis'
figsize	Tuple[float, float]	The size of the figure to create. Default is (12, 6), which results in a width of 12 inches and a height of 6 inches.	(12, 6)

Returns:

Type	Description
Figure	A tuple containing the Matplotlib Figure and Axes objects. The Figure contains the overall plot, while the Axes is the area
Axes	where the heatmap is drawn. These can be used for further customization or saving the plot to a file.

Notes

• The y-axis is flipped so that the first row of the DataFrame is displayed at the top of the plot.
• The color scale is normalized based on the minimum and maximum values in the DataFrame.
• The x-axis labels (periods) are placed at the top of the plot.
• The colorbar is added horizontally at the bottom of the plot, with a label.

heat_map_plotly

heat_map_plotly(data: DataFrame, color_map: str = 'viridis', title: str = '', xlabel: str = 'Period', ylabel: str = 'Step', categorical_labels: bool = True) -> go.Figure

Plots a DataFrame as a heatmap using Plotly. The columns of the DataFrame will be mapped to the x-axis, and the index will be displayed on the y-axis. The values in the DataFrame will represent the 'heat' in the plot.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame with the data to be visualized. The index will be used for the y-axis, and columns will be used for the x-axis. The values in the DataFrame will be represented as colors in the heatmap.	required
color_map	str	The color scale to use for the heatmap. Default is 'viridis'. Plotly supports various color scales like 'Cividis', 'Inferno', etc.	'viridis'
categorical_labels	bool	If True, the x and y axes are treated as categorical data (i.e., the index and columns will not be interpreted as continuous data). Default is True. If False, the axes are treated as continuous, which may be useful for time series or numeric data.	True
show		Wether to show the figure after creation. (This includes saving the figure)	required
save		Wether to save the figure after creation (without showing)	required
path		Path to save the figure.	required

Returns:

Type	Description
Figure	A Plotly figure object containing the heatmap. This can be further customized and saved
Figure	or displayed using fig.show().

Notes

The color bar is automatically scaled to the minimum and maximum values in the data. The y-axis is reversed to display the first row at the top.

reshape_to_2d

reshape_to_2d(data_1d: ndarray, nr_of_steps_per_column: int) -> np.ndarray

Reshapes a 1D numpy array into a 2D array suitable for plotting as a colormap.

The reshaped array will have the number of rows corresponding to the steps per column (e.g., 24 hours per day) and columns representing time periods (e.g., days or months).

Parameters:

Name	Type	Description	Default
data_1d	ndarray	A 1D numpy array with the data to reshape.	required
nr_of_steps_per_column	int	The number of steps (rows) per column in the resulting 2D array. For example, this could be 24 (for hours) or 31 (for days in a month).	required

Returns:

Type	Description
ndarray	The reshaped 2D array. Each internal array corresponds to one column, with the specified number of steps.
ndarray	Each column might represents a time period (e.g., day, month, etc.).

heat_map_data_from_df

heat_map_data_from_df(df: DataFrame, periods: Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min'], steps_per_period: Literal['W', 'D', 'h', '15min', 'min'], fill: Optional[Literal['ffill', 'bfill']] = None) -> pd.DataFrame

Reshapes a DataFrame with a DateTime index into a 2D array for heatmap plotting, based on a specified sample rate. If a non-valid combination of periods and steps per period is used, falls back to numerical indices

Parameters:

Name	Type	Description	Default
df	DataFrame	A DataFrame with a DateTime index containing the data to reshape.	required
periods	Literal['YS', 'MS', 'W', 'D', 'h', '15min', 'min']	The time interval of each period (columns of the heatmap), such as 'YS' (year start), 'W' (weekly), 'D' (daily), 'h' (hourly) etc.	required
steps_per_period	Literal['W', 'D', 'h', '15min', 'min']	The time interval within each period (rows in the heatmap), such as 'YS' (year start), 'W' (weekly), 'D' (daily), 'h' (hourly) etc.	required
fill	Optional[Literal['ffill', 'bfill']]	Method to fill missing values: 'ffill' for forward fill or 'bfill' for backward fill.	None

Returns:

Type	Description
DataFrame	A DataFrame suitable for heatmap plotting, with rows representing steps within each period
DataFrame	and columns representing each period.

plot_network

plot_network(node_infos: dict, edge_infos: dict, path: Optional[Union[str, Path]] = None, controls: Union[bool, List[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']]] = True, show: bool = False) -> Optional[pyvis.network.Network]

Visualizes the network structure of a FlowSystem using PyVis, using info-dictionaries.

Parameters:

Name	Type	Description	Default
path	Optional[Union[str, Path]]	Path to save the HTML visualization. False: Visualization is created but not saved. str or Path: Specifies file path (default: 'results/network.html').	None
controls	Union[bool, List[Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']]]	UI controls to add to the visualization. True: Enables all available controls. List: Specify controls, e.g., ['nodes', 'layout']. Options: 'nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer'. You can play with these and generate a Dictionary from it that can be applied to the network returned by this function. network.set_options() https://pyvis.readthedocs.io/en/latest/tutorial.html	True
show	bool	Whether to open the visualization in the web browser. The calculation must be saved to show it. If no path is given, it defaults to 'network.html'.	False

Returns: The Network instance representing the visualization, or None if pyvis is not installed.

Notes: - This function requires pyvis. If not installed, the function prints a warning and returns None. - Nodes are styled based on type (e.g., circles for buses, boxes for components) and annotated with node information.

pie_with_plotly

pie_with_plotly(data: DataFrame, colors: ColorType = 'viridis', title: str = '', legend_title: str = '', hole: float = 0.0, fig: Optional[Figure] = None) -> go.Figure

Create a pie chart with Plotly to visualize the proportion of values in a DataFrame.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame containing the data to plot. If multiple rows exist, they will be summed unless a specific index value is passed.	required
colors	ColorType	Color specification, can be: - A string with a colorscale name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping column names to colors (e.g., {'Column1': '#ff0000'})	'viridis'
title	str	The title of the plot.	''
legend_title	str	The title for the legend.	''
hole	float	Size of the hole in the center for creating a donut chart (0.0 to 1.0).	0.0
fig	Optional[Figure]	A Plotly figure object to plot on. If not provided, a new figure will be created.	None

Returns:

Type	Description
Figure	A Plotly figure object containing the generated pie chart.

Notes

• Negative values are not appropriate for pie charts and will be converted to absolute values with a warning.
• If the data contains very small values (less than 1% of the total), they can be grouped into an "Other" category for better readability.
• By default, the sum of all columns is used for the pie chart. For time series data, consider preprocessing.

pie_with_matplotlib

pie_with_matplotlib(data: DataFrame, colors: ColorType = 'viridis', title: str = '', legend_title: str = 'Categories', hole: float = 0.0, figsize: Tuple[int, int] = (10, 8), fig: Optional[Figure] = None, ax: Optional[Axes] = None) -> Tuple[plt.Figure, plt.Axes]

Create a pie chart with Matplotlib to visualize the proportion of values in a DataFrame.

Parameters:

Name	Type	Description	Default
data	DataFrame	A DataFrame containing the data to plot. If multiple rows exist, they will be summed unless a specific index value is passed.	required
colors	ColorType	Color specification, can be: - A string with a colormap name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping column names to colors (e.g., {'Column1': '#ff0000'})	'viridis'
title	str	The title of the plot.	''
legend_title	str	The title for the legend.	'Categories'
hole	float	Size of the hole in the center for creating a donut chart (0.0 to 1.0).	0.0
figsize	Tuple[int, int]	The size of the figure (width, height) in inches.	(10, 8)
fig	Optional[Figure]	A Matplotlib figure object to plot on. If not provided, a new figure will be created.	None
ax	Optional[Axes]	A Matplotlib axes object to plot on. If not provided, a new axes will be created.	None

Returns:

Type	Description
Tuple[Figure, Axes]	A tuple containing the Matplotlib figure and axes objects used for the plot.

Notes

• Negative values are not appropriate for pie charts and will be converted to absolute values with a warning.
• If the data contains very small values (less than 1% of the total), they can be grouped into an "Other" category for better readability.
• By default, the sum of all columns is used for the pie chart. For time series data, consider preprocessing.

dual_pie_with_plotly

dual_pie_with_plotly(data_left: Series, data_right: Series, colors: ColorType = 'viridis', title: str = '', subtitles: Tuple[str, str] = ('Left Chart', 'Right Chart'), legend_title: str = '', hole: float = 0.2, lower_percentage_group: float = 5.0, hover_template: str = '%{label}: %{value} (%{percent})', text_info: str = 'percent+label', text_position: str = 'inside') -> go.Figure

Create two pie charts side by side with Plotly, with consistent coloring across both charts.

Parameters:

Name	Type	Description	Default
data_left	Series	Series for the left pie chart.	required
data_right	Series	Series for the right pie chart.	required
colors	ColorType	Color specification, can be: - A string with a colorscale name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping category names to colors (e.g., {'Category1': '#ff0000'})	'viridis'
title	str	The main title of the plot.	''
subtitles	Tuple[str, str]	Tuple containing the subtitles for (left, right) charts.	('Left Chart', 'Right Chart')
legend_title	str	The title for the legend.	''
hole	float	Size of the hole in the center for creating donut charts (0.0 to 100).	0.2
lower_percentage_group	float	Whether to group small segments (below percentage (0...1)) into an "Other" category.	5.0
hover_template	str	Template for hover text. Use %{label}, %{value}, %{percent}.	'%{label}: %{value} (%{percent})'
text_info	str	What to show on pie segments: 'label', 'percent', 'value', 'label+percent', 'label+value', 'percent+value', 'label+percent+value', or 'none'.	'percent+label'
text_position	str	Position of text: 'inside', 'outside', 'auto', or 'none'.	'inside'

Returns:

Type	Description
Figure	A Plotly figure object containing the generated dual pie chart.

dual_pie_with_matplotlib

dual_pie_with_matplotlib(data_left: Series, data_right: Series, colors: ColorType = 'viridis', title: str = '', subtitles: Tuple[str, str] = ('Left Chart', 'Right Chart'), legend_title: str = '', hole: float = 0.2, lower_percentage_group: float = 5.0, figsize: Tuple[int, int] = (14, 7), fig: Optional[Figure] = None, axes: Optional[List[Axes]] = None) -> Tuple[plt.Figure, List[plt.Axes]]

Create two pie charts side by side with Matplotlib, with consistent coloring across both charts. Leverages the existing pie_with_matplotlib function.

Parameters:

Name	Type	Description	Default
data_left	Series	Series for the left pie chart.	required
data_right	Series	Series for the right pie chart.	required
colors	ColorType	Color specification, can be: - A string with a colormap name (e.g., 'viridis', 'plasma') - A list of color strings (e.g., ['#ff0000', '#00ff00']) - A dictionary mapping category names to colors (e.g., {'Category1': '#ff0000'})	'viridis'
title	str	The main title of the plot.	''
subtitles	Tuple[str, str]	Tuple containing the subtitles for (left, right) charts.	('Left Chart', 'Right Chart')
legend_title	str	The title for the legend.	''
hole	float	Size of the hole in the center for creating donut charts (0.0 to 1.0).	0.2
lower_percentage_group	float	Whether to group small segments (below percentage) into an "Other" category.	5.0
figsize	Tuple[int, int]	The size of the figure (width, height) in inches.	(14, 7)
fig	Optional[Figure]	A Matplotlib figure object to plot on. If not provided, a new figure will be created.	None
axes	Optional[List[Axes]]	A list of Matplotlib axes objects to plot on. If not provided, new axes will be created.	None

Returns:

Type	Description
Tuple[Figure, List[Axes]]	A tuple containing the Matplotlib figure and list of axes objects used for the plot.

export_figure

export_figure(figure_like: Union[Figure, Tuple[Figure, Axes]], default_path: Path, default_filetype: Optional[str] = None, user_path: Optional[Path] = None, show: bool = True, save: bool = False) -> Union[plotly.graph_objs.Figure, Tuple[plt.Figure, plt.Axes]]

Export a figure to a file and or show it.

Parameters:

Name	Type	Description	Default
figure_like	Union[Figure, Tuple[Figure, Axes]]	The figure to export. Can be a Plotly figure or a tuple of Matplotlib figure and axes.	required
default_path	Path	The default file path if no user filename is provided.	required
default_filetype	Optional[str]	The default filetype if the path doesnt end with a filetype.	None
user_path	Optional[Path]	An optional user-specified file path.	None
show	bool	Whether to display the figure (default: True).	True
save	bool	Whether to save the figure (default: False).	False

Raises:

Type	Description
ValueError	If no default filetype is provided and the path doesn't specify a filetype.
TypeError	If the figure type is not supported.