bs_altair module

Some Altair plots.

• alt_lineplot, alt_superposed_lineplot, alt_superposed_faceted_lineplot
• alt_plot_fun: plots a function
• alt_density, alt_faceted_densities: plots the density of x, or of x conditional on a category
• alt_superposed_faceted_densities: plots the density of x superposed by f and faceted by g
• alt_scatterplot, alt_scatterplot_with_histo, alt-linked_scatterplots: variants of scatter plots
• alt_histogram_by, alt_histogram_continuous: histograms of x by y, and of a continuous x
• alt_stacked_area,alt_stacked_area_facets: stacked area plots
• plot_parameterized_estimates: plots densities of estimates of coefficients, with the true values, as a function of a parameter
• plot_true_sim_facets, plot_true_sim2_facets: plot two simulated values and the true values of statistics as a function of a parameter
• alt_tick_plots: vertically arranged tick plots of variables
• alt_matrix_heatmap: plots a heatmap of a matrix.

alt_boxes(df, continuous_var, discrete_var, group_var, max_cols=3, title=None, save=None)

horizontal boxplots of df[continuous_var] by df[discrete_var] and df[group_var]

Parameters:

Name	Type	Description	Default
df	DataFrame	datframe with the three variables	required
continuous_var	str	name of the continuous variable	required
discrete_var	str	name of the discrete variable	required
group_var	str	name of the grouping variable	required
max_cols	int	maximum number of columns. Defaults to 3.	3
title	str | None	a plot title. Defaults to None.	None
save	str | None	the name of a file to save to (HTML extension will be added). Defaults to None.	None

Returns:

Type	Description
Chart	the chart.

Source code in bs_python_utils/bs_altair.py

def alt_boxes(
    df: pd.DataFrame,
    continuous_var: str,
    discrete_var: str,
    group_var: str,
    max_cols: int = 3,
    title: str | None = None,
    save: str | None = None,
) -> alt.Chart:
    """horizontal boxplots of `df[continuous_var]` by `df[discrete_var]` and `df[group_var]`

    Args:
        df: datframe with the three variables
        continuous_var: name of the continuous variable
        discrete_var: name of the discrete variable
        group_var: name of the grouping variable
        max_cols: maximum number of columns. Defaults to 3.
        title: a plot title. Defaults to None.
        save: the name of a file to save to (HTML extension will be added). Defaults to None.

    Returns:
        the chart.
    """
    boxes = (
        (
            alt.Chart(df)
            .mark_boxplot()
            .encode(
                x=f"{continuous_var}:Q", y=f"{discrete_var}:O", color=f"{group_var}:N"
            )
            .properties(width=180, height=180)
        )
        .facet(f"{group_var}:N", columns=max_cols)
        .resolve_scale(y="independent")
    )
    if title:
        boxes = boxes.properties(title=title)
    _maybe_save(boxes, save)
    return cast(alt.Chart, boxes)

alt_density(df, str_x, save=None)

Plots the density of df[str_x].

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x variable	required
str_x	str	the name of a continuous column	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_density(df: pd.DataFrame, str_x: str, save: str | None = None) -> alt.Chart:
    """Plots the density of `df[str_x]`.

    Args:
        df: the data with the `str_x` variable
        str_x: the name of a continuous column
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    ch = (
        alt.Chart(df)
        .transform_density(
            str_x,
            as_=[str_x, "Density"],
        )
        .mark_area(opacity=0.4)
        .encode(
            x=f"{str_x}:Q",
            y="Density:Q",
        )
    )

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_faceted_densities(df, str_x, str_f, legend_title=None, save=None, max_cols=4)

Plots the density of df[str_x] by df[str_f] in column facets

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x and str_f variables	required
str_x	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
legend_title	str | None	a title for the legend	None
save	str | None	the name of a file to save to (HTML extension will be added)	None
max_cols	int | None	we wrap after that number of columns	4

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_faceted_densities(
    df: pd.DataFrame,
    str_x: str,
    str_f: str,
    legend_title: str | None = None,
    save: str | None = None,
    max_cols: int | None = 4,
) -> alt.Chart:
    """
    Plots the density of `df[str_x]` by `df[str_f]` in column facets

    Args:
        df: the data with the `str_x` and `str_f` variables
        str_x: the name of a continuous column
        str_f: the name of a categorical column
        legend_title: a title for the legend
        save: the name of a file to save to (HTML extension will be added)
        max_cols: we wrap after that number of columns

    Returns:
        the `alt.Chart` object.
    """
    our_legend_title = str_f if legend_title is None else legend_title
    ch = (
        alt.Chart(df)
        .transform_density(
            str_x,
            groupby=[str_f],
            as_=[str_x, "Density"],
        )
        .mark_area(opacity=0.4)
        .encode(
            x=f"{str_x}:Q",
            y="Density:Q",
            color=alt.Color(f"{str_f}:N", title=our_legend_title),
        )
        .facet(f"{str_f}:N", columns=max_cols)
    )

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_histogram_by(df, str_x, str_y, str_agg='mean', save=None)

Plots a histogram of a statistic of str_y by str_x

Parameters:

Name	Type	Description	Default
df	DataFrame	a dataframe with columns str_x and str_y	required
str_x	str	a categorical variable	required
str_y	str	a continuous variable	required
str_agg	str | None	how we aggregate the values of str_y by str_x	'mean'
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the Altair chart.

Source code in bs_python_utils/bs_altair.py

def alt_histogram_by(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    str_agg: str | None = "mean",
    save: str | None = None,
) -> alt.Chart:
    """
    Plots a histogram of a statistic of `str_y` by `str_x`

    Args:
        df: a dataframe with columns `str_x` and `str_y`
        str_x: a categorical variable
        str_y: a continuous variable
        str_agg: how we aggregate the values of `str_y` by `str_x`
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the Altair chart.
    """
    ch = (
        alt.Chart(df)
        .mark_bar()
        .encode(x=str_x, y=f"{str_agg}({str_y}):Q")
        .properties(height=300, width=400)
    )
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_histogram_continuous(df, str_x, save=None)

Histogram of a continuous variable df[str_x]

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x, str_y, and str_f variables	required
str_x	str	the name of a continuous column	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_histogram_continuous(
    df: pd.DataFrame, str_x: str, save: str | None = None
) -> alt.Chart:
    """
    Histogram of a continuous variable `df[str_x]`

    Args:
        df: the data with the `str_x`, `str_y`, and `str_f` variables
        str_x: the name of a continuous column
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    ch = alt.Chart(df).mark_bar().encode(alt.X(str_x, bin=True), y="count()")
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_lineplot(df, str_x, str_y, time_series=False, save=None, aggreg=None, **kwargs)

Scatterplot of df[str_x] vs df[str_y]

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with columns str_x and str_y	required
str_x	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
time_series	bool	True if x is a time series	False
save	str | None	the name of a file to save to (HTML extension will be added)	None
aggreg	str | None	the name of an aggregating function for y	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_lineplot(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    time_series: bool = False,
    save: str | None = None,
    aggreg: str | None = None,
    **kwargs,
) -> alt.Chart:
    """
    Scatterplot of `df[str_x]` vs `df[str_y]`

    Args:
        df: the data with columns `str_x` and `str_y`
        str_x: the name of a continuous column
        str_y: the name of a continuous column
        time_series: `True` if x is a time series
        save: the name of a file to save to (HTML extension will be added)
        aggreg: the name of an aggregating function for `y`

    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    var_y = f"{aggreg}({str_y}):Q" if aggreg is not None else str_y

    ch = alt.Chart(df).mark_line().encode(x=f"{str_x}:{type_x}", y=var_y)
    if "title" in kwargs:
        ch = ch.properties(title=kwargs["title"])
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_linked_scatterplots(df, str_x1, str_x2, str_y, str_f, save=None)

Creates two scatterplots: of df[str_x1] vs df[str_y] and of df[str_x2] vs df[str_y], both with color as per df[str_f]. Selecting an interval in one shows up in the other.

Parameters:

Name	Type	Description	Default
df	DataFrame		required
str_x1	str	the name of a continuous column	required
str_x2	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_linked_scatterplots(
    df: pd.DataFrame,
    str_x1: str,
    str_x2: str,
    str_y: str,
    str_f: str,
    save: str | None = None,
) -> alt.Chart:
    """
    Creates two scatterplots: of `df[str_x1]` vs `df[str_y]` and of `df[str_x2]` vs `df[str_y]`,
    both with color as per `df[str_f]`. Selecting an interval in one shows up in the other.

    Args:
        df:
        str_x1: the name of a continuous column
        str_x2: the name of a continuous column
        str_y: the name of a continuous column
        str_f: the name of a categorical column
        save: the name of a file to save to (HTML extension will be added)

    Returns:
          the `alt.Chart` object.
    """
    interval = alt.selection_interval()

    base = (
        alt.Chart(df)
        .mark_point()
        .encode(
            y=f"{str_y}:Q", color=alt.condition(interval, str_f, alt.value("lightgray"))
        )
        .add_params(interval)
    )

    ch = base.encode(x=f"{str_x1}:Q") | base.encode(x=f"{str_x2}:Q")

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_matrix_heatmap(mat, str_format, multiple=1.0, title=None, str_rows='Row', str_cols='Column', save=None)

Plots a heatmap of a matrix

Parameters:

Name	Type	Description	Default
mat	ndarray	the matrix to plot	required
str_format	str	the string to format the values, e.g. "d" or ".3f"	required
multiple	float	increases the size of the circles	1.0
title	str | None	a title, if any	None
str_rows	str | None	the name of the variable in the rows	'Row'
str_cols	str | None	the name of the variable in the columns	'Column'
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the heatmap

Source code in bs_python_utils/bs_altair.py

def alt_matrix_heatmap(
    mat: np.ndarray,
    str_format: str,
    multiple: float = 1.0,
    title: str | None = None,
    str_rows: str | None = "Row",
    str_cols: str | None = "Column",
    save: str | None = None,
) -> alt.Chart:
    """Plots a heatmap of a matrix

    Args:
        mat: the matrix to plot
        str_format: the string to format the values, e.g. "d" or ".3f"
        multiple: increases the size of the circles
        title: a title, if any
        str_rows: the name of the variable in the rows
        str_cols: the name of the variable in the columns
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the heatmap
    """
    n_rows, n_cols = check_matrix(mat)
    mat_arr = np.empty((mat.size, 4))
    type_vals = "float"
    if "d" in str_format:  # integer values
        mat = np.round(mat)
        type_vals = "int"
    mat_min = np.min(mat)
    i = 0
    for ix in range(n_rows):
        for iy in range(n_cols):
            m = mat[ix, iy]
            s = m - mat_min + 1
            mat_arr[i, :] = np.array([ix, iy, m, s])
            i += 1

    mat_df = pd.DataFrame(mat_arr, columns=[str_rows, str_cols, "Value", "Size"])
    if type_vals == "int":
        mat_df = mat_df.astype(
            dtype={str_rows: int, str_cols: int, "Value": int, "Size": float}
        )
    else:
        mat_df = mat_df.astype(
            dtype={str_rows: int, str_cols: int, "Value": float, "Size": float}
        )
    base = alt.Chart(mat_df).encode(
        x=f"{str_rows}:O", y=alt.Y(f"{str_cols}:O", sort="descending")
    )
    mat_map = base.mark_circle(opacity=0.4).encode(
        size=alt.Size(
            "Size:Q",
            legend=None,
            scale=alt.Scale(range=[1000 * multiple, 10000 * multiple]),
        )
    )
    text = base.mark_text(baseline="middle", fontSize=16).encode(
        text=alt.Text("Value:Q", format=str_format),
    )
    if title is None:
        both = (mat_map + text).properties(width=500, height=500)
    else:
        both = (mat_map + text).properties(title=title, width=400, height=400)

    _maybe_save(both, save)
    return cast(alt.Chart, both)

alt_plot_fun(f, start, end, npoints=100, save=None)

Plots the function f from start to end.

Parameters:

Name	Type	Description	Default
f	Callable	returns a Numpy array from a Numpy array	required
start	float	first point on x axis	required
end	float	last point on x axis	required
npoints	int	number of points	100
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_plot_fun(
    f: Callable,
    start: float,
    end: float,
    npoints: int = 100,
    save: str | None = None,
) -> alt.Chart:
    """
    Plots the function `f` from `start` to `end`.

    Args:
        f: returns a Numpy array from a Numpy array
        start: first point on `x` axis
        end: last point on `x` axis
        npoints: number of points
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    step = (end - start) / npoints
    points = np.arange(start, end + step, step)
    fun_data = pd.DataFrame({"x": points, "y": f(points)})

    ch = (
        alt.Chart(fun_data)
        .mark_line()
        .encode(
            x="x:Q",
            y="y:Q",
        )
    )

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_scatterplot(df, str_x, str_y, time_series=False, save=None, xlabel=None, ylabel=None, size=30, title=None, color=None, aggreg=None, selection=False)

Scatterplot of df[str_x] vs df[str_y].

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with columns for x, y	required
str_x	str	the name of a continuous x column	required
str_y	str	the name of a continuous y column	required
time_series	bool	True if x is a time series	False
xlabel	str | None	label for the horizontal axis	None
ylabel	str | None	label for the vertical axis	None
title	str | None	title for the graph	None
size	int | None	radius of the circles	30
color	str | None	variable that determines the color of the circles	None
selection	bool	if True, the user can select interactively from the color legend, if any	False
save	str | None	the name of a file to save to (HTML extension will be added)	None
aggreg	str | None	the name of an aggregating function for y	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_scatterplot(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    time_series: bool = False,
    save: str | None = None,
    xlabel: str | None = None,
    ylabel: str | None = None,
    size: int | None = 30,
    title: str | None = None,
    color: str | None = None,
    aggreg: str | None = None,
    selection: bool = False,
) -> alt.Chart:
    """
    Scatterplot of `df[str_x]` vs `df[str_y]`.

    Args:
        df: the data with columns for x, y
        str_x: the name of a continuous x column
        str_y: the name of a continuous y column
        time_series: `True` if x is a time series
        xlabel: label for the horizontal axis
        ylabel: label for the vertical axis
        title: title for the graph
        size: radius of the circles
        color: variable that determines the color of the circles
        selection: if `True`, the user can select interactively from the `color` legend, if any
        save: the name of a file to save to (HTML extension will be added)
        aggreg: the name of an aggregating function for `y`

    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    var_x = alt.X(f"{str_x}:{type_x}")

    if xlabel is not None:
        if isinstance(xlabel, str):
            var_x = alt.X(f"{str_x}:{type_x}", axis=alt.Axis(title=xlabel))
        else:
            bs_error_abort(f"xlabel must be a string, not {xlabel}")

    var_y = f"{aggreg}({str_y}):Q" if aggreg is not None else str_y

    if ylabel is not None:
        if isinstance(ylabel, str):
            var_y_lab = alt.Y(var_y, axis=alt.Axis(title=ylabel))
        else:
            bs_error_abort(f"ylabel must be a string, not {ylabel}")

    if isinstance(size, int):
        circles_size = size
    else:
        bs_error_abort(f"size must be an integer, not {size}")

    if color is not None:
        if isinstance(color, str):
            if selection:
                selection_criterion = alt.selection_multi(fields=[color], bind="legend")
                ch = (
                    alt.Chart(df)
                    .mark_circle(size=circles_size)
                    .encode(
                        x=var_x,
                        y=var_y if ylabel is None else var_y_lab,
                        color=color,
                        opacity=alt.condition(
                            selection_criterion, alt.value(1), alt.value(0.1)
                        ),
                    )
                    .add_params(selection_criterion)
                )
            else:
                ch = (
                    alt.Chart(df)
                    .mark_circle(size=circles_size)
                    .encode(x=var_x, y=var_y, color=color)
                )
        else:
            bs_error_abort(f"color must be a string, not {color}")
    else:
        ch = alt.Chart(df).mark_circle(size=circles_size).encode(x=var_x, y=var_y)

    ch = _add_title(ch, title)
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_scatterplot_with_histo(df, str_x, str_y, str_f, save=None)

Scatterplot of df[str_x] vs df[str_y] with colors as per df[str_f] allows to select an interval and histograns the counts of df[str_f] in the interval.

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x and str_f variables	required
str_x	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_scatterplot_with_histo(
    df: pd.DataFrame, str_x: str, str_y: str, str_f: str, save: str | None = None
) -> alt.Chart:
    """
    Scatterplot of `df[str_x]` vs `df[str_y]` with colors as per `df[str_f]`
    allows to select an interval and histograns the counts of `df[str_f]` in the interval.

    Args:
        df: the data with the `str_x` and `str_f` variables
        str_x: the name of a continuous column
        str_y: the name of a continuous column
        str_f: the name of a categorical column
        save: the name of a file to save to (HTML extension will be added)

    Returns:
          the `alt.Chart` object.
    """
    interval = alt.selection_interval()

    points = (
        alt.Chart(df)
        .mark_point()
        .encode(
            x=f"{str_x}:Q",
            y=f"{str_y}:Q",
            color=alt.condition(interval, str_f, alt.value("lightgray")),
        )
        .add_params(interval)
    )

    histogram = (
        alt.Chart(df)
        .mark_bar()
        .encode(
            x="count()",
            y=str_f,
            color=str_f,
        )
        .transform_filter(interval)
    )

    ch = points & histogram

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_stacked_area(df, str_x, str_y, str_f, time_series=False, title=None, save=None)

Normalized stacked lineplots of df[str_x] vs df[str_y] by df[str_f]

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with columns for str_x, str_y, and str_f	required
str_x	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
time_series	bool	True if str_x is a time series	False
title	str | None	a title for the plot	None
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_stacked_area(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    str_f: str,
    time_series: bool = False,
    title: str | None = None,
    save: str | None = None,
) -> alt.Chart:
    """
    Normalized stacked lineplots of `df[str_x]` vs `df[str_y]` by `df[str_f]`

    Args:
        df: the data with columns for `str_x`, `str_y`, and `str_f`
        str_x: the name of a continuous column
        str_y: the name of a continuous column
        str_f: the name of a categorical column
        time_series: `True` if `str_x` is a time series
        title: a title for the plot
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    ch = (
        alt.Chart(df)
        .mark_area()
        .encode(
            x=f"{str_x}:{type_x}",
            y=alt.Y(f"{str_y}:Q", stack="normalize"),
            color=f"{str_f}:N",
        )
    )
    if title is not None:
        ch = ch.properties(title=title)

    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_stacked_area_facets(df, str_x, str_y, str_f, str_g, time_series=False, max_cols=5, title=None, save=None)

Normalized stacked lineplots of df[str_x] vs df[str_y] by df[str_f], faceted by df[str_g]

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with columns for str_x, str_y, and str_f	required
str_x	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
str_g	str	the name of a categorical column	required
time_series	bool	True if str_x is a time series	False
title	str | None	a title for the plot	None
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_stacked_area_facets(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    str_f: str,
    str_g: str,
    time_series: bool = False,
    max_cols: int | None = 5,
    title: str | None = None,
    save: str | None = None,
) -> alt.Chart:
    """
    Normalized stacked lineplots of `df[str_x]` vs `df[str_y]` by `df[str_f]`, faceted by `df[str_g]`

    Args:
        df: the data with columns for `str_x`, `str_y`, and `str_f`
        str_x: the name of a continuous column
        str_y: the name of a continuous column
        str_f: the name of a categorical column
        str_g: the name of a categorical column
        time_series: `True` if `str_x` is a time series
        title: a title for the plot
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    ch = (
        alt.Chart(df)
        .mark_area()
        .encode(
            x=f"{str_x}:{type_x}",
            y=alt.Y(f"{str_y}:Q", stack="normalize"),
            color=f"{str_f}:N",
            facet=(
                alt.Facet(f"{str_g}:N", columns=max_cols)
                if max_cols is not None
                else alt.Facet(f"{str_g}:N")
            ),
        )
    )
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_superposed_faceted_densities(df, str_x, str_f, str_g, max_cols=4, save=None)

Creates density plots of df[str_x] by df[str_f] and df[str_g] with color as per df[str_f] and faceted by df[str_g]. that is: facets by str_g, with densities conditional on str_f superposed.

Parameters:

Name	Type	Description	Default
df	DataFrame	a Pandas dataframe wity columns str_x, str_f, str_g	required
str_x	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
str_g	str	the name of a categorical column	required
max_cols	int | None	the number of columns after whcih we wrap	4
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_superposed_faceted_densities(
    df: pd.DataFrame,
    str_x: str,
    str_f: str,
    str_g: str,
    max_cols: int | None = 4,
    save: str | None = None,
) -> alt.Chart:
    """
    Creates density plots of `df[str_x]` by `df[str_f]` and `df[str_g]`
    with color as per `df[str_f]` and faceted by `df[str_g]`.
    that is: facets by `str_g`, with densities conditional on `str_f` superposed.

    Args:
        df: a Pandas dataframe wity columns `str_x`, `str_f`, `str_g`
        str_x: the name of a continuous column
        str_f: the name of a categorical column
        str_g: the name of a categorical column
        max_cols: the number of columns after whcih we wrap
        save: the name of a file to save to (HTML extension will be added)

    Returns:
          the `alt.Chart` object.
    """
    densities = (
        alt.Chart(df)
        .transform_density(
            str_x,
            groupby=[str_f, str_g],
            as_=[str_x, "Density"],
        )
        .mark_line()
        .encode(
            x=f"{str_x}:Q",
            y="Density:Q",
            color=f"{str_f}:N",
        )
        .facet(column=f"{str_g}:N", columns=max_cols)
        .resolve_scale(x="independent", y="independent")
    )
    _maybe_save(densities, save)

    return cast(alt.Chart, densities)

alt_superposed_faceted_lineplot(df, str_x, str_y, str_f, str_g, time_series=False, legend_title=None, max_cols=5, save=None)

Plots df[str_x] vs df[str_y] superposed by df[str_f] and faceted by df[str_g]

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x, str_y, and str_f variables	required
str_x	str	the name of a continuous column	required
str_y	str	the name of a continuous column	required
str_f	str	the name of a categorical column	required
str_g	str	the name of a categorical column	required
time_series	bool	True if str_x is a time series	False
legend_title	str | None	a title for the legend	None
save	str | None	the name of a file to save to (HTML extension will be added)	None
max_cols	int | None	we wrap after that number of columns	5

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_superposed_faceted_lineplot(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    str_f: str,
    str_g: str,
    time_series: bool = False,
    legend_title: str | None = None,
    max_cols: int | None = 5,
    save: str | None = None,
) -> alt.Chart:
    """
    Plots `df[str_x]` vs `df[str_y]` superposed by `df[str_f]` and faceted by `df[str_g]`

    Args:
        df: the data with the `str_x`, `str_y`, and `str_f` variables
        str_x: the name of a continuous column
        str_y: the name of a continuous column
        str_f: the name of a categorical column
        str_g: the name of a categorical column
        time_series: `True` if `str_x` is a time series
        legend_title: a title for the legend
        save: the name of a file to save to (HTML extension will be added)
        max_cols: we wrap after that number of columns


    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    our_title = str_f if legend_title is None else legend_title
    ch = (
        alt.Chart(df)
        .mark_line()
        .encode(
            x=f"{str_x}:{type_x}",
            y=f"{str_y}:Q",
            color=alt.Color(f"{str_f}:N", title=our_title),
            facet=(
                alt.Facet(f"{str_g}:N", columns=max_cols)
                if max_cols is not None
                else alt.Facet(f"{str_g}:N")
            ),
        )
    )
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_superposed_lineplot(df, str_x, str_y, str_f, time_series=False, legend_title=None, save=None)

Plots df[str_x] vs df[str_y] by df[str_f] on one plot

Parameters:

Name	Type	Description	Default
df	DataFrame	the data with the str_x, str_y, and str_f variables	required
str_x	str	the name of a continuous x column	required
str_y	str	the name of a continuous y column	required
str_f	str	the name of a categorical f column	required
time_series	bool	True if str_x is a time series	False
legend_title	str | None	a title for the legend	None
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_superposed_lineplot(
    df: pd.DataFrame,
    str_x: str,
    str_y: str,
    str_f: str,
    time_series: bool = False,
    legend_title: str | None = None,
    save: str | None = None,
) -> alt.Chart:
    """
    Plots `df[str_x]` vs `df[str_y]` by `df[str_f]` on one plot

    Args:
        df: the data with the `str_x`, `str_y`, and `str_f` variables
        str_x: the name of a continuous `x` column
        str_y: the name of a continuous `y` column
        str_f: the name of a categorical `f` column
        time_series: `True` if `str_x` is a time series
        legend_title: a title for the legend
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    type_x = "T" if time_series else "Q"
    our_legend_title = str_f if legend_title is None else legend_title
    ch = (
        alt.Chart(df)
        .mark_line()
        .encode(
            x=f"{str_x}:{type_x}",
            y=f"{str_y}:Q",
            color=alt.Color(f"{str_f}:N", title=our_legend_title),
        )
    )
    _maybe_save(ch, save)
    return cast(alt.Chart, ch)

alt_tick_plots(df, list_vars, save=None)

Creates a tick plot of the variables in list_vars ofdf, arranged vertically.

Parameters:

Name	Type	Description	Default
df	DataFrame	a dataframe with the variables in list_vars	required
list_vars	str | list[str]	the name of a column of df, or a list of names	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def alt_tick_plots(
    df: pd.DataFrame, list_vars: str | list[str], save: str | None = None
) -> alt.Chart:
    """
    Creates a tick plot of the variables in `list_vars` of`df`, arranged vertically.

    Args:
        df: a dataframe with the variables in `list_vars`
        list_vars: the name of a column of `df`, or a list of names
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    if isinstance(list_vars, str):
        varname = list_vars
        ch = alt.Chart(df).encode(x=varname).mark_tick()
    else:
        ch = (
            alt.Chart(df)
            .encode(alt.X(alt.repeat("row"), type="quantitative"))
            .mark_tick()
            .repeat(row=list_vars)
            .resolve_scale(y="independent")
        )

    _maybe_save(ch, save)

    return cast(alt.Chart, ch)

plot_parameterized_estimates(parameter_name, parameter_values, coeff_names, true_values, estimate_names, estimates, colors, save=None)

Plots estimates of coefficients, with the true values, as a function of a parameter; one facet per coefficient

Parameters:

Name	Type	Description	Default
parameter_name	str	the name of the parameter	required
parameter_values	ndarray	a vector of n_vals values for the parameter	required
coeff_names	str | list[str]	the names of the n_coeffs coefficients	required
true_values	ndarray	their true values, depending on the parameter or not	required
estimate_names	str | list[str]	names of the estimates	required
estimates	ndarray	their values	required
colors	list[str]	colors for the various estimates	required
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def plot_parameterized_estimates(
    parameter_name: str,
    parameter_values: np.ndarray,
    coeff_names: str | list[str],
    true_values: np.ndarray,
    estimate_names: str | list[str],
    estimates: np.ndarray,
    colors: list[str],
    save: str | None = None,
) -> alt.Chart:
    """
    Plots estimates of coefficients, with the true values,  as a function of a parameter; one facet per coefficient

    Args:
        parameter_name: the name of the parameter
        parameter_values: a vector of `n_vals` values for the parameter
        coeff_names: the names of the `n_coeffs` coefficients
        true_values: their true values, depending on the parameter or not
        estimate_names: names of the estimates
        estimates: their values
        colors: colors for the various estimates
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    n_vals = check_vector(parameter_values)
    n_coeffs = 1 if isinstance(coeff_names, str) else len(coeff_names)
    if n_coeffs == 1:
        n_true = check_vector(true_values, "plot_parameterized_estimates")
        if n_true != n_vals:
            bs_error_abort(
                f"plot_parameterized_estimates: we have {n_true} values and"
                f" {n_vals} parameter values."
            )
        df = pd.DataFrame({parameter_name: parameter_values, "True value": true_values})
        df1, ordered_estimates = _stack_estimates(estimate_names, estimates, df)
        df1m = pd.melt(df1, parameter_name, var_name="Estimate")
        ch = (
            alt.Chart(df1m)
            .mark_line()
            .encode(
                x=f"{parameter_name}:Q",
                y="value:Q",
                strokeDash=alt.StrokeDash("Estimate:N", sort=ordered_estimates),
                color=alt.Color(
                    "Estimate:N",
                    sort=estimate_names,
                    scale=alt.Scale(domain=ordered_estimates, range=colors),
                ),
            )
        )
    else:
        n_true, n_c = check_matrix(true_values, "plot_parameterized_estimates")
        if n_true != n_vals:
            bs_error_abort(
                f"plot_parameterized_estimates: we have {n_true} true values and"
                f" {n_vals} parameter values."
            )
        if n_c != n_coeffs:
            bs_error_abort(
                f"plot_parameterized_estimates: we have {n_c} columns of true values"
                f" and {n_coeffs} coefficients."
            )
        df1 = [None] * n_coeffs
        for i_coeff, coeff in enumerate(coeff_names):
            df_i = pd.DataFrame(
                {
                    parameter_name: parameter_values,
                    "True value": true_values[:, i_coeff],
                }
            )
            df1[i_coeff], ordered_estimates = _stack_estimates(
                estimate_names, estimates[..., i_coeff], df_i
            )
            df1[i_coeff]["Coefficient"] = coeff

        df2 = pd.concat(df1[i_coeff] for i_coeff in range(n_coeffs))
        ordered_colors = colors
        df2m = pd.melt(df2, [parameter_name, "Coefficient"], var_name="Estimate")
        ch = (
            alt.Chart(df2m)
            .mark_line()
            .encode(
                x=f"{parameter_name}:Q",
                y="value:Q",
                strokeDash=alt.StrokeDash("Estimate:N", sort=ordered_estimates),
                color=alt.Color(
                    "Estimate:N",
                    sort=ordered_estimates,
                    scale=alt.Scale(domain=ordered_estimates, range=ordered_colors),
                ),
            )
            .facet(alt.Facet("Coefficient:N", sort=coeff_names))
            .resolve_scale(y="independent")
        )

    _maybe_save(ch, save)

    return cast(alt.Chart, ch)

plot_true_sim2_facets(parameter_name, parameter_values, stat_names, stat_true, stat_sim1, stat_sim2, colors, stat_title='Statistic', subtitle='True vs estimated', ncols=3, save=None)

Plots simulated values for two methods and true values of statistics as a function of a parameter; one facet per coefficient

Parameters:

Name	Type	Description	Default
parameter_name	str	the name of the parameter	required
parameter_values	ndarray	a vector of n_vals values for the parameter	required
stat_names	list[str]	the names of the n statistics	required
stat_true	ndarray	their true values, (n_vals, n)	required
stat_sim1	ndarray	their simulated values, method 1	required
stat_sim2	ndarray	their simulated values, method 2	required
colors	list[str]	colors for the various estimates	required
stat_title	str | None	main title	'Statistic'
subtitle	str | None	subtitle	'True vs estimated'
ncols	int | None	wrap after ncols columns	3
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def plot_true_sim2_facets(
    parameter_name: str,
    parameter_values: np.ndarray,
    stat_names: list[str],
    stat_true: np.ndarray,
    stat_sim1: np.ndarray,
    stat_sim2: np.ndarray,
    colors: list[str],
    stat_title: str | None = "Statistic",
    subtitle: str | None = "True vs estimated",
    ncols: int | None = 3,
    save: str | None = None,
) -> alt.Chart:
    """
    Plots simulated values for two methods and true values of statistics as a function of a parameter;
    one facet per coefficient

    Args:
        parameter_name: the name of the parameter
        parameter_values: a vector of `n_vals` values for the parameter
        stat_names: the names of the `n` statistics
        stat_true: their true values, `(n_vals, n)`
        stat_sim1: their simulated values, method 1
        stat_sim2: their simulated values, method 2
        colors: colors for the various estimates
        stat_title: main title
        subtitle: subtitle
        ncols: wrap after `ncols` columns
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    n_stats = len(stat_names)
    nvals = check_vector(parameter_values, "plot_true_sim2_facets")
    nv_true, n_stat_true = check_matrix(stat_true, "plot_true_sim2_facets")
    if nv_true != nvals:
        bs_error_abort(f"we have {nvals} parameter values and {nv_true} for stat_true.")
    if n_stat_true != n_stats:
        bs_error_abort(f"we have {n_stats} names for {n_stat_true} true statistics.")

    nv_est1, n_stat_est1 = check_matrix(stat_sim1, "plot_true_sim2_facets")
    if nv_est1 != nvals:
        bs_error_abort(f"we have {nvals} parameter values and {nv_est1} for stat_sim1.")
    if n_stat_est1 != n_stats:
        bs_error_abort(
            f"we have {n_stats} names for {n_stat_est1} estimated statistics."
        )
    nv_est2, n_stat_est2 = check_matrix(stat_sim2, "plot_true_sim2_facets")
    if nv_est2 != nvals:
        bs_error_abort(f"we have {nvals} parameter values and {nv_est2} for stat_sim2.")
    if n_stat_est2 != n_stats:
        bs_error_abort(
            f"we have {n_stats} names for {n_stat_est2} estimated statistics."
        )

    df = pd.DataFrame(
        {
            parameter_name: parameter_values,
            "True value": stat_true[:, 0],
            "Estimated1": stat_sim1[:, 0],
            "Estimated2": stat_sim2[:, 0],
            stat_title: stat_names[0],
        }
    )
    for i_stat in range(1, n_stats):
        df_i = pd.DataFrame(
            {
                parameter_name: parameter_values,
                "True value": stat_true[:, i_stat],
                "Estimated1": stat_sim1[:, i_stat],
                "Estimated2": stat_sim2[:, i_stat],
                stat_title: stat_names[i_stat],
            }
        )
        df = pd.concat((df, df_i))
    sub_order = ["True value", "Estimated1", "Estimated2"]
    dfm = pd.melt(df, [parameter_name, stat_title], var_name=subtitle)
    ch = (
        alt.Chart(dfm)
        .mark_line()
        .encode(
            x=f"{parameter_name}:Q",
            y="value:Q",
            strokeDash=alt.StrokeDash(f"{subtitle}:N", sort=sub_order),
            color=alt.Color(
                f"{subtitle}:N",
                sort=sub_order,
                scale=alt.Scale(domain=sub_order, range=colors),
            ),
            facet=(
                alt.Facet(f"{stat_title}:N", sort=stat_names, columns=ncols)
                if ncols is not None
                else alt.Facet(f"{stat_title}:N", sort=stat_names)
            ),
        )
        .resolve_scale(y="independent")
    )

    _maybe_save(ch, save)

    return cast(alt.Chart, ch)

plot_true_sim_facets(parameter_name, parameter_values, stat_names, stat_true, stat_sim, colors, stat_title='Statistic', subtitle='True vs estimated', ncols=3, save=None)

Plots simulated and true values of statistics as a function of a parameter; one facet per coefficient

Parameters:

Name	Type	Description	Default
parameter_name	str	the name of the parameter	required
parameter_values	ndarray	a vector of n_vals values for the parameter	required
stat_names	list[str]	the names of the n statistics	required
stat_true	ndarray	their true values, (n_vals, n)	required
stat_sim	ndarray	their simulated values	required
colors	list[str]	colors for the various estimates	required
stat_title	str | None	main title	'Statistic'
subtitle	str | None	subtitle	'True vs estimated'
ncols	int | None	wrap after ncols columns	3
save	str | None	the name of a file to save to (HTML extension will be added)	None

Returns:

Type	Description
Chart	the alt.Chart object.

Source code in bs_python_utils/bs_altair.py

def plot_true_sim_facets(
    parameter_name: str,
    parameter_values: np.ndarray,
    stat_names: list[str],
    stat_true: np.ndarray,
    stat_sim: np.ndarray,
    colors: list[str],
    stat_title: str | None = "Statistic",
    subtitle: str | None = "True vs estimated",
    ncols: int | None = 3,
    save: str | None = None,
) -> alt.Chart:
    """
    Plots simulated and true values of statistics as a function of a parameter; one facet per coefficient

    Args:
        parameter_name: the name of the parameter
        parameter_values: a vector of `n_vals` values for the parameter
        stat_names: the names of the `n` statistics
        stat_true: their true values, `(n_vals, n)`
        stat_sim: their simulated values
        colors: colors for the various estimates
        stat_title: main title
        subtitle: subtitle
        ncols: wrap after `ncols` columns
        save: the name of a file to save to (HTML extension will be added)

    Returns:
        the `alt.Chart` object.
    """
    n_stats = len(stat_names)
    nvals = check_vector(parameter_values, "plot_true_sim_facets")
    nv_true, n_stat_true = check_matrix(stat_true, "plot_true_sim_facets")
    if nv_true != nvals:
        bs_error_abort(
            f"plot_true_sim_facets: we have {nvals} parameter values and {nv_true} for"
            " stat_true."
        )
    nv_est, n_stat_est = check_matrix(stat_sim, "plot_true_sim_facets")
    if nv_est != nvals:
        bs_error_abort(
            f"plot_true_sim_facets: we have {nvals} parameter values and {nv_est} for"
            " stat_sim."
        )
    if n_stat_true != n_stats:
        bs_error_abort(
            f"plot_true_sim_facets: we have {n_stats} names for {n_stat_true} true"
            " statistics."
        )
    if n_stat_est != n_stats:
        bs_error_abort(
            f"plot_true_sim_facets: we have {n_stats} names for {n_stat_est} estimated"
            " statistics."
        )
    df = pd.DataFrame(
        {
            parameter_name: parameter_values,
            "True value": stat_true[:, 0],
            "Estimated": stat_sim[:, 0],
            stat_title: stat_names[0],
        }
    )
    for i_stat in range(1, n_stats):
        df_i = pd.DataFrame(
            {
                parameter_name: parameter_values,
                "True value": stat_true[:, i_stat],
                "Estimated": stat_sim[:, i_stat],
                stat_title: stat_names[i_stat],
            }
        )
        df = pd.concat((df, df_i))
    sub_order = ["True value", "Estimated"]
    dfm = pd.melt(df, [parameter_name, stat_title], var_name=subtitle)
    ch = (
        alt.Chart(dfm)
        .mark_line()
        .encode(
            x=f"{parameter_name}:Q",
            y="value:Q",
            strokeDash=alt.StrokeDash(f"{subtitle}:N", sort=sub_order),
            color=alt.Color(
                f"{subtitle}:N",
                sort=sub_order,
                scale=alt.Scale(domain=sub_order, range=colors),
            ),
            facet=(
                alt.Facet(f"{stat_title}:N", sort=stat_names, columns=ncols)
                if ncols is not None
                else alt.Facet(f"{stat_title}:N", sort=stat_names)
            ),
        )
        .resolve_scale(y="independent")
    )

    _maybe_save(ch, save)

    return cast(alt.Chart, ch)