isimip_utils.plot

Plotting utilities using Altair for ISIMIP data visualization.

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(index_path)

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
index_path	Path	Path where the index.html file will be saved.	required

format_title(permutation)

Create a plot title from a permutation tuple.

Parameters:

Name	Type	Description	Default
permutation	tuple	Tuple of strings to join as title.	required

Returns:

Type	Description
dict	Dictionary with Altair title configuration.

plot_line(df, x_field=None, x_label=None, x_type=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='Legend', 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
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').	'Legend'
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_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_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_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.