isimip_utils.plot

Plotting utilities using Altair for ISIMIP data visualization.

check_plots(plots, path)

Check whether a set of plots is small enough for Vega to render.

The limit is empirical: 1,036,800 rows (4 global 0.5-degree grids) renders, 1,296,000 (5 grids) does not.

Parameters:

Name	Type	Description	Default
plots	dict	Dictionary mapping permutation tuples to Chart objects.	required
path	str | Path	Output file path, used only for the log message.	required

Returns:

Type	Description
bool	True if the plots can safely be rendered, False if the file should be skipped.

save_plot(chart, path, *args, **kwargs)

Save an Altair chart to a file.

Parameters:

Name	Type	Description	Default
chart	Chart	Altair chart to save.	required
path	str | Path	Output file path.	required
*args	Any	Additional positional arguments for chart.save().	()
**kwargs	Any	Additional keyword arguments for chart.save().	{}

save_index(parent_path, paths)

Save an HTML index file for browsing plot images.

Creates an interactive HTML page for viewing SVG/PNG files in a directory.

Parameters:

Name	Type	Description	Default
parent_path	Path	Directory where the index.html file will be saved.	required
paths	list	Paths which are included in the index.html.	required

format_title(text, fontSize=16, dy=-10, **kwargs)

Format the plot title.

Parameters:

Name	Type	Description	Default
text	str	Title text. A list of strings can be passed instead to render the title across multiple lines.	required
fontSize	int	Font size of the title, in pixels (default: 16).	16
dy	int	Vertical offset of the title from its anchor, in pixels; negative values move it up (default: -10).	-10
**kwargs	Any	Additional Altair title properties.	{}

Returns:

Type	Description
dict	Dictionary with Altair title configuration.

format_legend(symbolStrokeWidth=2, labelFontSize=14, titleFontSize=14, labelLimit=0, symbolLimit=0, direction='vertical', orient='right', columns=1, **kwargs)

Format the plot legend.

Parameters:

Name	Type	Description	Default
symbolStrokeWidth	int	Stroke width of the legend symbols, in pixels (default: 2).	2
labelFontSize	int	Font size of the entry labels, in pixels (default: 14).	14
titleFontSize	int	Font size of the legend title, in pixels (default: 14).	14
labelLimit	int	Maximum width of an entry label, in pixels; longer labels are truncated with an ellipsis. 0 means no limit (default: 0).	0
symbolLimit	int	Maximum number of entries to show; 0 means no limit (default: 0).	0
direction	str	Layout direction, either 'vertical' or 'horizontal' (default: 'vertical').	'vertical'
orient	str	Position relative to the chart, e.g. 'left', 'right', 'top', 'bottom', 'top-left', or 'none' to place it manually (default: 'right').	'right'
columns	int	Number of columns used to lay out symbol legends; ignored for gradient legends (default: 1).	1
**kwargs	Any	Additional Altair legend properties.	{}

Returns:

Type	Description
dict	Dictionary with Altair legend configuration.

plot_line(df, x_field=None, x_label=None, x_type=None, x_format=None, y_field=None, y_label=None, y_type=None, y_format=None, color_field=None, color_type=None, color_domain=None, color_range=None, color_scheme=None, color_title=None, legend=True, empty=False, **mark_kwargs)

Create a line plot from a DataFrame.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame to plot.	required
x_field	str | None	Column name for x-axis (default: auto-detect from attrs).	None
x_label	str | None	Label for x-axis (default: auto-detect from attrs).	None
x_type	str | None	Altair type for x-axis (default: 'T' for time, 'Q' for quantitative).	None
x_format	str | None	Format string for x-axis values.	None
y_field	str | None	Column name for y-axis (default: auto-detect from attrs).	None
y_label	str | None	Label for y-axis (default: auto-detect from attrs).	None
y_type	str | None	Altair type for y-axis (default: 'Q').	None
y_format	str | None	Format string for y-axis values.	None
color_field	str | None	Column name for color encoding (default: 'label').	None
color_type	str | None	Altair type for color (default: 'N').	None
color_domain	list | None	Custom color domain.	None
color_range	list | None	Custom color range for scale.	None
color_scheme	str | None	Custom color scheme for scale.	None
color_title	str | None	Title for color (default: 'Legend').	None
legend	bool	Whether to show legend (default: True).	True
empty	bool	Whether to create an empty plot with NaN values (default: False).	False
**mark_kwargs	Any	Additional keyword arguments for mark_line().	{}

Returns:

Type	Description
Chart	Altair Chart object with line plot (and optional area for lower/upper bounds).

plot_map(df, color_field=None, color_type=None, color_scale=None, color_domain=None, color_range=None, color_scheme=None, color_label=None, color_format=None, bin_size=1, legend=True, empty=False)

Create a geographic map plot from a DataFrame with lat/lon coordinates.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame with 'lat' and 'lon' columns.	required
color_field	str | None	Column name for color encoding (default: auto-detect from attrs).	None
color_type	str | None	Altair type for color (default: 'Q').	None
color_scale	list | None	Custom type for the color scale.	None
color_domain	list | None	Custom domain for the color scale.	None
color_range	list | None	Custom range for color scale.	None
color_scheme	str | None	Custom scheme for color scale.	None
color_label	str | None	Label for color legend (default: auto-detect from attrs).	None
color_format	str | None	Format string for color legend values.	None
bin_size	int	Bin size for aggregating grid cells (default: 1).	1
legend	bool	Whether to show legend (default: True).	True
empty	bool	Whether to create an empty plot (default: False).	False

Returns:

Type	Description
Chart	Altair Chart object with rectangular heatmap.

plot_grid(grid_permutations, plot_permutations, plots, empty_plot, x='shared', y='shared', color='shared')

Create a grid of plots organized by parameter permutations.

Parameters:

Name	Type	Description	Default
grid_permutations	list	List the permutations (with tuples of parameters) which span the grid.	required
plot_permutations	list	List the permutations (with tuples of parameters) for each plot.	required
plots	dict	Dictionary mapping permutation tuples to Chart objects.	required
empty_plot	Chart	Chart to use when a permutation has no data.	required
x	str	Scale resolution for x-axis ('shared', 'independent', default: 'shared').	'shared'
y	str	Scale resolution for y-axis ('shared', 'independent', default: 'shared').	'shared'
color	str	Scale resolution for color ('shared', 'independent', default: 'shared').	'shared'

Returns:

Type	Description
Chart	Altair Chart object with grid layout.