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.

Functions

with_plotly

with_plotly(data: DataFrame, mode: Literal['bar', 'line', 'area'] = 'area', colors: Union[List[str], str] = 'viridis', title: str = '', ylabel: str = '', fig: Optional[Figure] = None, show: bool = False, save: bool = False, path: Union[str, Path] = 'temp-plot.html') -> 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`	`(bar, line)`	The plotting mode. Use 'bar' for stacked bar charts or 'line' for stepped lines.	`'bar'`
`colors`	`(List[str], str)`	A List of colors (as str) or a name of a colorscale (e.g., 'viridis', 'plasma') to use for coloring the data series.	`'viridis'`
`title`	`str`	The title of the plot.	`''`
`ylabel`	`str`	The label for the y-axis.	`''`
`fig`	`Figure`	A Plotly figure object to plot on. If not provided, a new figure will be created.	`None`
`show`	`bool`	Wether to show the figure after creation. (This includes saving the figure)	`False`
`save`	`bool`	Wether to save the figure after creation (without showing)	`False`
`path`	`Union[str, Path]`	Path to save the figure.	`'temp-plot.html'`

Returns:

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

Notes

If mode is 'bar', bars are stacked for each data series.
If mode is 'line', a stepped line is drawn for each data series.
The legend is positioned below the plot for a cleaner layout when many data series are present.

Examples:

>>> fig = with_plotly(data, mode='bar', colorscale='plasma')
>>> fig.show()

with_matplotlib

with_matplotlib(data: DataFrame, mode: Literal['bar', 'line'] = 'bar', colors: Union[List[str], str] = 'viridis', figsize: Tuple[int, int] = (12, 6), fig: Optional[Figure] = None, ax: Optional[Axes] = None, show: bool = False, path: Optional[Union[str, Path]] = 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`	`(bar, line)`	Plotting mode. Use 'bar' for stacked bar charts or 'line' for stepped lines.	`'bar'`
`colors`	`(List[str], str)`	A List of colors (as str) or a name of a colorscale (e.g., 'viridis', 'plasma') to use for coloring the data series.	`'viridis'`
`figsize`	`Tuple[int, int]`	Specify the size of the figure	`(12, 6)`
`fig`	`Figure`	A Matplotlib figure object to plot on. If not provided, a new figure will be created.	`None`
`ax`	`Axes`	A Matplotlib axes object to plot on. If not provided, a new axes will be created.	`None`
`show`	`bool`	Wether to show the figure after creation.	`False`
`path`	`Optional[Union[str, Path]]`	Path to save the figure to.	`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.

Examples:

>>> fig, ax = with_matplotlib(data, mode='bar', colorscale='plasma')
>>> plt.show()

heat_map_matplotlib

heat_map_matplotlib(data: DataFrame, color_map: str = 'viridis', figsize: Tuple[float, float] = (12, 6), show: bool = False, path: Optional[Union[str, Path]] = None) -> 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 of 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)`
`show`	`bool`	Wether to show the figure after creation.	`False`
`path`	`Optional[Union[str, Path]]`	Path to save the figure to.	`None`

Returns:

Type	Description
`tuple of (plt.Figure, plt.Axes)`	A tuple containing the Matplotlib `Figure` and `Axes` objects. The `Figure` contains the overall plot, while the `Axes` is the area 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 = 'Periods', ylabel: str = 'Step', categorical_labels: bool = True, show: bool = False, save: bool = False, path: Union[str, Path] = 'temp-plot.html') -> 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`	`bool`	Wether to show the figure after creation. (This includes saving the figure)	`False`
`save`	`bool`	Wether to save the figure after creation (without showing)	`False`
`path`	`Union[str, Path]`	Path to save the figure.	`'temp-plot.html'`

Returns:

Type	Description
`Figure`	A Plotly figure object containing the heatmap. This can be further customized and saved 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. 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`	`str`	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`	`str`	The time interval within each period (rows in the heatmap), such as 'YS' (year start), 'W' (weekly), 'D' (daily), 'h' (hourly) etc.	required
`fill`	`str`	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 and columns representing each period.

visualize_network

visualize_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 = True) -> Optional[pyvis.network.Network]

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

Parameters: - path (Union[bool, str, pathlib.Path], default='results/network.html'): Path to save the HTML visualization. - False: Visualization is created but not saved. - str or Path: Specifies file path (default: 'results/network.html').

controls (Union[bool, List[str]], default=True): 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
show (bool, default=True): 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'.

Returns: - Optional[pyvis.network.Network]: The Network instance representing the visualization, or None if pyvis is not installed.

Usage: - Visualize and open the network with default options:

self.visualize_network()

Save the visualization without opening:

self.visualize_network(show=False)
Visualize with custom controls and path:

self.visualize_network(path='output/custom_network.html', controls=['nodes', 'layout'])

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.