zensvi.visualization

Functions

plot_hist(, dpi, font_size, dark_mode, ...)

Plots hist (Kernel Density Estimate) plots for specified columns from a CSV file

plot_image(→ Tuple[matplotlib.pyplot.Figure, ...)

Generates a grid of images based on specified parameters and optionally annotates

plot_kde(, dpi, font_size, dark_mode, ...)

Plots KDE (Kernel Density Estimate) plots for specified columns from a CSV file

plot_map(, dpi, font_size, dark_mode, ...)

Plots a geographic map from data points, with options for line or hexagonal

Package Contents

zensvi.visualization.plot_hist(dir_input: str | pathlib.Path, columns: List[str], csv_file_pattern: str = '*.csv', path_output: str | pathlib.Path = None, legend: bool = True, title: str = None, legend_title: str = None, fig_size: Tuple[int, int] = (10, 10), dpi: int = 300, font_size: int = 30, dark_mode: bool = False, **kwargs) → Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]

Plots hist (Kernel Density Estimate) plots for specified columns from a CSV file using Seaborn.

Parameters:

  • dir_input (Union[str, Path]) – Path to the CSV file.

  • columns (List[str]) – List of column names to plot hists for.

  • path_output (Union[str, Path], optional) – Path where the plotted figure will be saved. Defaults to None.

  • legend (bool) – Whether to add a legend to the plot. Defaults to True.

  • title (str, optional) – Title of the plot. Defaults to None.

  • legend_title (str, optional) – Title for the legend. Defaults to None.

  • dpi (int) – Dots per inch (resolution) of the output image. Defaults to 300.

  • font_size (int) – Font size for titles and legend. Defaults to 30.

  • dark_mode (bool) – Whether to use a dark theme for the plot. Defaults to False.

  • **kwargs – Additional keyword arguments passed to seaborn.histplot.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

zensvi.visualization.plot_image(dir_image_input: str | pathlib.Path, n_row: int, n_col: int, subplot_width: int = 3, subplot_height: int = 3, dir_csv_input: str | pathlib.Path = None, csv_file_pattern: str = '*.csv', image_file_pattern: str = None, sort_by: str = 'random', ascending: bool = True, use_all: bool = False, title: str = None, path_output: str | pathlib.Path = None, random_seed: int = 42, font_size: int = 30, dark_mode: bool = False, dpi: int = 300) → Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]

Generates a grid of images based on specified parameters and optionally annotates them using data from a CSV file. Images can be displayed in a random or sorted order according to metadata provided in a CSV file.

Parameters:

  • dir_image_input (Union[str, Path]) – Directory path containing image files.

  • n_row (int) – Number of rows in the image grid.

  • n_col (int) – Number of columns in the image grid.

  • subplot_width (int, optional) – Width of each subplot. Defaults to 3.

  • subplot_height (int, optional) – Height of each subplot. Defaults to 3.

  • dir_csv_input (Union[str, Path], optional) – Directory path containing CSV files with metadata. Defaults to None.

  • csv_file_pattern (str, optional) – Pattern to match CSV files in the directory. Defaults to None.

  • image_file_pattern (str, optional) – Pattern to match image files in the directory. Defaults to None.

  • sort_by (str, optional) – Column name to sort the images by; set to “random” for random order. Defaults to “random”.

  • ascending (bool, optional) – Sort order. True for ascending, False for descending. Defaults to True.

  • use_all (bool, optional) – If True, use all available images, otherwise use only a subset to fit the grid. Defaults to False.

  • title (str, optional) – Title of the plot. Defaults to None.

  • path_output (Union[str, Path], optional) – Path to save the output plot. Defaults to None.

  • random_seed (int, optional) – Seed for random operations to ensure reproducibility. Defaults to 42.

  • font_size (int, optional) – Font size for the plot title. Defaults to 30.

  • dark_mode (bool, optional) – Set to True to use a dark theme for the plot. Defaults to False.

  • dpi (int, optional) – Resolution in dots per inch for saving the image. Defaults to 300.

Returns:

A tuple containing the matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

Raises:

  • ValueError – If the specified number of rows and columns does not match the available number of images.

  • KeyError – If the ‘sort_by’ column is not found in the provided CSV files.

zensvi.visualization.plot_kde(dir_input: str | pathlib.Path, columns: List[str], csv_file_pattern: str = '*.csv', path_output: str | pathlib.Path = None, legend: bool = True, title: str = None, legend_title: str = None, fig_size: Tuple[int, int] = (10, 10), dpi: int = 300, font_size: int = 30, dark_mode: bool = False, **kwargs) → Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]

Plots KDE (Kernel Density Estimate) plots for specified columns from a CSV file using Seaborn.

Parameters:

  • dir_input (Union[str, Path]) – Path to the CSV file.

  • columns (List[str]) – List of column names to plot KDEs for.

  • path_output (Union[str, Path], optional) – Path where the plotted figure will be saved. Defaults to None.

  • legend (bool) – Whether to add a legend to the plot. Defaults to True.

  • title (str, optional) – Title of the plot. Defaults to None.

  • legend_title (str, optional) – Title for the legend. Defaults to None.

  • dpi (int) – Dots per inch (resolution) of the output image. Defaults to 300.

  • font_size (int) – Font size for titles and legend. Defaults to 30.

  • dark_mode (bool) – Whether to use a dark theme for the plot. Defaults to False.

  • **kwargs – Additional keyword arguments passed to seaborn.kdeplot.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

zensvi.visualization.plot_map(path_pid: str | pathlib.Path, pid_column: str = 'panoid', dir_input: str | pathlib.Path = None, csv_file_pattern: str = '*.csv', variable_name: str = None, plot_type: str = 'point', path_output: str | pathlib.Path = None, resolution: int = 7, cmap: str = 'viridis', legend: bool = True, title: str = None, legend_title: str = None, basemap_source: Any = ctx.providers.CartoDB.PositronNoLabels, figure_size: Tuple[int, int] = (10, 10), dpi: int = 300, font_size: int = 30, dark_mode: bool = False, **kwargs) → Tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes][source]

Plots a geographic map from data points, with options for line or hexagonal aggregations, coloring by variables, and using different base maps.

Parameters:

  • path_pid (Union[str, Path]) – Path to the CSV file containing longitude and latitude and other metadata.

  • pid_column (str, optional) – Column name in CSV that acts as a primary key or identifier. Defaults to “panoid”.

  • dir_input (Union[str, Path], optional) – Directory path where additional CSV data files are stored, matched by pattern. Defaults to None.

  • csv_file_pattern (str, optional) – Pattern to match CSV files in the directory. Defaults to None.

  • variable_name (str, optional) – Name of the variable in CSV to use for coloring and aggregation. Defaults to None.

  • plot_type (str, optional) – Type of plot to generate: ‘point’, ‘line’, or ‘hexagon’. Defaults to “point”.

  • path_output (Union[str, Path], optional) – Path where the plotted figure will be saved. Defaults to None.

  • resolution (int, optional) – Resolution level for H3 hexagonal tiling. Defaults to 7.

  • cmap (str, optional) – Colormap for the plot. Defaults to “viridis”.

  • legend (bool, optional) – Whether to add a color legend to the plot. Defaults to True.

  • title (str, optional) – Title of the plot. Defaults to None.

  • legend_title (str, optional) – Title for the legend. Defaults to None.

  • basemap_source (Any, optional) – Contextily basemap source. Defaults to ctx.providers.CartoDB.PositronNoLabels.

  • dpi (int, optional) – Dots per inch (resolution) of the output image file. Defaults to 300.

  • font_size (int, optional) – Font size for titles and legend. Defaults to 30.

  • dark_mode (bool, optional) – Whether to use a dark theme for the plot. Defaults to False.

  • **kwargs – Additional keyword arguments passed to GeoPandas plot function.

Returns:

A tuple containing the Matplotlib figure and axes objects.

Return type:

Tuple[plt.Figure, plt.Axes]

Raises:

ValueError – If an invalid plot_type is provided.