Basic charts

Scatter, regression, box, bar, violin, pie / donut and radar. Usage with worked inputs: Visualization.

AeroViz.plot.scatter.scatter

scatter(df: DataFrame, x: str, y: str, c: str | None = None, color: str | None = '#7a97c9', s: str | None = None, cmap='jet', regression=False, regression_line_color: str | None = xkcd_rgb['denim blue'], diagonal=False, ax: Axes | None = None, **kwargs) -> tuple[Figure, Axes]

Creates a scatter plot with optional color and size encoding.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	The DataFrame containing the data to plot.	required
`x`	`str`	The column name for the x-axis values.	required
`y`	`str`	The column name for the y-axis values.	required
`c`	`str`	The column name for c encoding. Default is None.	`None`
`color`	`str`	The column name for color encoding. Default is None.	`'#7a97c9'`
`s`	`str`	The column name for size encoding. Default is None.	`None`
`cmap`	`str`	The colormap to use for the color encoding. Default is 'jet'.	`'jet'`
`regression`	`bool`	If True, fits and plots a linear regression line. Default is False.	`False`
`regression_line_color`	`str`	The color of the regression line. Default is 'sns.xkcd_rgb["denim blue"]'.	`xkcd_rgb['denim blue']`
`diagonal`	`bool`	If True, plots a 1:1 diagonal line. Default is False.	`False`
`ax`	`Axes`	The matplotlib Axes to plot on. If not provided, a new figure and axes are created.	`None`
`**kwargs`	`Any`	Additional keyword arguments passed to customize the plot, such as `fig_kws` for figure creation and `xlabel`, `ylabel`, `xlim`, `ylim`, `title` for axis labeling and limits.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure`	The matplotlib Figure object.
`ax`	`Axes`	The matplotlib Axes object with the scatter plot.

Notes

If both c and s are provided, the scatter plot will encode data points using both color and size.
If only c is provided, data points will be color-coded according to the values in the c column.
If only s is provided, data points will be sized according to the values in the s column.
If neither c nor s is provided, a basic scatter plot is created.
The regression option will add a linear regression line and display the equation on the plot.
The diagonal option will add a 1:1 reference line to the plot.

Examples:

>>> import pandas as pd
>>> from AeroViz.plot import scatter
>>> df = pd.DataFrame({
>>>     'x': [1, 2, 3, 4],
>>>     'y': [1.1, 2.0, 2.9, 4.1],
>>>     'color': [10, 20, 30, 40],
>>>     'size': [100, 200, 300, 400]
>>> })
>>> fig, ax = scatter(df, x='x', y='y', c='color', s='size', regression=True, diagonal=True)

AeroViz.plot.regression.linear_regression

linear_regression(df: DataFrame, x: str | list[str], y: str | list[str], labels: str | list[str] = None, ax: Axes | None = None, diagonal=False, positive: bool = True, fit_intercept: bool = True, **kwargs) -> tuple[Figure, Axes]

Create a scatter plot with regression lines for the given data.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Input DataFrame containing the data.	required
`x`	`str or list of str`	Column name(s) for the x-axis variable(s). If a list, only the first element is used.	required
`y`	`str or list of str`	Column name(s) for the y-axis variable(s).	required
`labels`	`str or list of str`	Labels for the y-axis variable(s). If None, column names are used as labels. Default is None.	`None`
`ax`	`Axes`	Matplotlib Axes object to use for the plot. If None, a new subplot is created. Default is None.	`None`
`diagonal`	`bool`	If True, a diagonal line (1:1 line) is added to the plot. Default is False.	`False`
`positive`	`bool`	Whether to constrain the regression coefficients to be positive. Default is True.	`True`
`fit_intercept`	`bool`	Whether to calculate the intercept for this model. Default is True.	`True`
`**kwargs`		Additional keyword arguments for plot customization.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure`	The matplotlib Figure object.
`ax`	`Axes`	The matplotlib Axes object with the scatter plot.

Notes

The function creates a scatter plot with optional regression lines.
The regression line is fitted for each y variable.
Customization options are provided via **kwargs.

Examples:

>>> from AeroViz import plot
>>>
>>> plot.linear_regression(df, x='X', y=['Y1', 'Y2'], labels=['Label1', 'Label2'],
...                        diagonal=True, xlim=(0, 10), ylim=(0, 20),
...                        xlabel="X-axis", ylabel="Y-axis", title="Scatter Plot with Regressions")

AeroViz.plot.regression.multiple_linear_regression

multiple_linear_regression(df: DataFrame, x: str | list[str], y: str | list[str], labels: str | list[str] = None, ax: Axes | None = None, diagonal=False, positive: bool = True, fit_intercept: bool = True, **kwargs) -> tuple[Figure, Axes]

Perform multiple linear regression analysis and plot the results.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	Input DataFrame containing the data.	required
`x`	`str or list of str`	Column name(s) for the independent variable(s). Can be a single string or a list of strings.	required
`y`	`str or list of str`	Column name(s) for the dependent variable(s). Can be a single string or a list of strings.	required
`labels`	`str or list of str`	Labels for the dependent variable(s). If None, column names are used as labels. Default is None.	`None`
`ax`	`Axes`	Matplotlib Axes object to use for the plot. If None, a new subplot is created. Default is None.	`None`
`diagonal`	`bool`	Whether to include a diagonal line (1:1 line) in the plot. Default is False.	`False`
`positive`	`bool`	Whether to constrain the regression coefficients to be positive. Default is True.	`True`
`fit_intercept`	`bool`	Whether to calculate the intercept for this model. Default is True.	`True`
`**kwargs`		Additional keyword arguments for plot customization.	`{}`

Returns:

Type	Description
`tuple[Figure, Axes]`	The Figure and Axes containing the regression plot.

Notes

This function performs multiple linear regression analysis using the input DataFrame. It supports multiple independent variables and can plot the regression results.

Examples:

>>> from AeroViz import plot
>>>
>>> plot.multiple_linear_regression(df, x=['X1', 'X2'], y='Y', labels=['Y1', 'Y2'],
...                                 diagonal=True, fit_intercept=True,
...                                 xlabel="X-axis", ylabel="Y-axis", title="Multiple Linear Regression Plot")

AeroViz.plot.box.box

box(df: DataFrame, x: str, y: str, x_bins: list | ndarray = None, add_scatter: bool = True, ax: Axes | None = None, **kwargs) -> tuple[Figure, Axes]

Grouped box plot of y against x.

Two modes, chosen automatically:

Categorical — when x is non-numeric (e.g. a 'season' column) or x_bins is omitted: one box per unique x value.
Binned — when x is numeric and x_bins is given: x is cut into the supplied bin edges (any width, integer or float) and one box is drawn per bin.

AeroViz.plot.bar.bar

bar(data_set: DataFrame | dict, data_std: DataFrame | None, labels: list[str], unit: str, style: Literal['stacked', 'dispersed'] = 'dispersed', orientation: Literal['va', 'ha'] = 'va', ax: Axes | None = None, symbol=True, **kwargs) -> tuple[Figure, Axes]

Parameters:

Name	Type	Description	Default
`data_set`	`DataFrame or dict`	A mapping from category names to a list of species mean or a DataFrame with columns as categories and values as means.	required
`data_std`	`DataFrame or None`	A DataFrame with standard deviations corresponding to data_set, or None if standard deviations are not provided.	required
`labels`	`list of str`	The species names.	required
`unit`	`str`	The unit for the values.	required
`style`	`(stacked, dispersed)`	Whether to display the bars stacked or dispersed.	`'stacked'`
`orientation`	`(va, ha)`	The orientation of the bars, 'va' for vertical and 'ha' for horizontal.	`'va'`
`ax`	`Axes or None`	The Axes object to plot on. If None, a new figure and Axes are created.	`None`
`symbol`	`bool`	Whether to display values for each bar.	`True`
`kwargs`	`dict`	Additional keyword arguments passed to the barplot function.	`{}`

Returns:

Type	Description
`Axes`	The Axes object containing the plot.

AeroViz.plot.violin.violin

violin(df: DataFrame | dict, unit: str, ax: Axes | None = None, **kwargs) -> tuple[Figure, Axes]

Generate a violin plot for multiple data sets.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame or dict`	A mapping from category names to pandas DataFrames containing the data.	required
`unit`	`str`	The unit for the data being plotted.	required
`ax`	`Axes`	The Axes object to draw the plot onto. If not provided, a new figure will be created.	`None`
`**kwargs`	`dict`	Additional keyword arguments to be passed to the violinplot function.	`{}`

Returns:

Name	Type	Description
`fig`	`Figure`	The matplotlib Figure object.
`ax`	`Axes`	The matplotlib Axes object with the scatter plot.

AeroViz.plot.pie.pie

pie(data_set: DataFrame | dict, labels: list[str], unit: str, style: Literal['pie', 'donut'], ax: Axes | None = None, symbol: bool = True, **kwargs) -> tuple[Figure, Axes]

Create a pie or donut chart based on the provided data.

Parameters:

Name	Type	Description	Default
`data_set`	`DataFrame \| dict`	A pandas DataFrame or dictionary mapping category names to a list of species. If a DataFrame is provided, the index represents the categories, and each column contains species data. If a dictionary is provided, it maps category names to lists of species data. It is assumed that all lists or DataFrame columns contain the same number of entries as the labels list.	required
`labels`	`list of str`	The labels for each category.	required
`unit`	`str`	The unit to display in the center of the donut chart.	required
`style`	`Literal['pie', 'donut']`	The style of the chart, either 'pie' for a standard pie chart or 'donut' for a donut chart.	required
`ax`	`Axes or None`	The Axes object to plot the chart onto. If None, a new figure and Axes will be created.	`None`
`symbol`	`bool`	Whether to display values for each species in the chart.	`True`
`**kwargs`		Additional keyword arguments to be passed to the plotting function.	`{}`

Returns:

Type	Description
`Axes`	The Axes object containing the violin plot.

Notes

If data_set is a dictionary, it should contain lists of species that correspond to each category in labels.
The length of each list in data_set or the number of columns in the DataFrame should match the length of the labels list.

Examples:

>>> data_set = {'Category 1': [10, 20, 30], 'Category 2': [15, 25, 35]}
>>> labels = ['Species 1', 'Species 2', 'Species 3']
>>> pie(data_set, labels, unit='kg', style='pie', symbol=True)

AeroViz.plot.pie.donuts

donuts(data_set: DataFrame | dict, labels: list[str], unit: str, ax: Axes | None = None, symbol=True, **kwargs) -> tuple[Figure, Axes]

Plot a donut chart based on the data set.

Parameters:

Name	Type	Description	Default
`data_set`	`DataFrame \| dict`	A pandas DataFrame or a dictionary mapping category names to a list of species. If a DataFrame is provided, the index represents the categories, and each column contains species data. If a dictionary is provided, it maps category names to lists of species data. It is assumed that all lists or DataFrame columns contain the same number of entries as the labels list.	required
`labels`	`list of str`	The category labels.	required
`unit`	`str`	The unit to be displayed in the center of the donut chart.	required
`ax`	`Axes`	The axes to plot on. If None, the current axes will be used (default).	`None`
`symbol`	`bool`	Whether to display values for each species (default is True).	`True`
`**kwargs`	`dict`	Additional keyword arguments to pass to the matplotlib pie chart function.	`{}`

Returns:

Type	Description
`Axes`	The axes containing the donut chart.

AeroViz.plot.radar.radar

radar(data, labels=None, legend_labels=None, **kwargs) -> tuple[Figure, Axes]

Creates a radar chart based on the provided data.

Parameters:

Name	Type	Description	Default
`data`	`list of list`	A 2D list where each inner list represents a factor, and each element within the inner lists represents a value for a species. Shape: (n_factors, n_species) Example: [[0.88, 0.01, 0.03, ...], [0.07, 0.95, 0.04, ...], ...]	required
`labels`	`list`	A list of strings representing the names of species (variables). If provided, it should have the same length as the number of elements in each inner list of `data`. Example: ['Sulfate', 'Nitrate', 'EC', 'OC1', 'OC2', 'OP', 'CO', 'O3']	`None`
`legend_labels`	`list`	A list of strings for labeling each factor in the legend. If provided, it should have the same length as the number of inner lists in `data`.	`None`
`**kwargs`	`dict`	Additional keyword arguments to be passed to the plotting function. This may include 'title' for setting the chart title.	`{}`

Returns:

Type	Description
`tuple[Figure, Axes]`	A tuple containing the Figure and Axes objects of the created plot.

Example

data = [[0.88, 0.01, 0.03, 0.03, 0.00, 0.06, 0.01, 0.00], [0.07, 0.95, 0.04, 0.05, 0.00, 0.02, 0.01, 0.00], [0.01, 0.02, 0.85, 0.19, 0.05, 0.10, 0.00, 0.00], [0.02, 0.01, 0.07, 0.01, 0.21, 0.12, 0.98, 0.00], [0.01, 0.01, 0.02, 0.71, 0.74, 0.70, 0.30, 0.20]] labels = ['Sulfate', 'Nitrate', 'EC', 'OC1', 'OC2', 'OP', 'CO', 'O3'] fig, ax = radar(data, labels=labels, title='Basecase')

Note

The first dimension of data represents each factor, while the second dimension represents each species.