docs(example): Adds Confidence Interval Ellipses

[dangotbanned]

Will close #3715

Description

Adds an example inspired by (ggplot2|plotnine).stat_ellipse().

As can be seen in the first commit, this PR began by rebasing a closed PR from almost 7 years ago.

• Deviation ellipses example #514

Relevant info from (#3715 (comment)):

I believe plotnine.stat_ellipse would be an example of implementing this with numpy, scipy.
Source code

I also found an old closed PR (#514 by @essicolo) that would have added an example for this.
The blocker at the time is no longer an issue as (#3202 by @joelostblom) added scipy as a docs dependency.

Example

Tasks

• Fix sphinxext.altairgallery parsing (CI Run)
  • (4944b80)
  • (7cd2a77)
• Finish tidying up from (1983ede)
  • numpy and scipy
  • pandas (see thread)
• Add examples_methods_syntax version
  • Only alt.(X|Y) changed to chain .scale(zero=False)
• docs: rename to 'Confidence Interval Ellipses'
• Provide more detail in the description (62927af)
  • Reference plotnine.stat_ellipse
  • Attributing author of original PR Serge-Étienne Parent (@essicolo)

Future Work

I think a more generalized version of this would be a good fit for https://github.com/vega/altair_ally.
An issue might be the scipy dependency, which I really was hoping to be able to avoid here.
The dendrogram example shows some kind of inlining from scipy - but I have no idea if that is possible for:

• https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.rv_continuous.ppf.html#scipy.stats.rv_continuous.ppf
• https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.f.html#scipy-stats-f

[dangotbanned]

Cannot express how relieved I am to see the CI finally green 😅
be087d2

[dangotbanned]

TODO

• Figure out a more ergonomic way of applying the function to each group

[dangotbanned]

@MarcoGorelli not an urgent one.

Do you know of a more idiomatic way to write this pandas code?

Based on this from 7 years ago:

altair/tests/examples_arguments_syntax/deviation_ellipses.py

Lines 37 to 45 in a22e8dc

	columns = ['petalLength', 'petalWidth']
	petal_ellipse = []
	for species in iris.species.unique():
	ell_df = pd.DataFrame(ellipse(X=iris.loc[iris.species == species, columns].as_matrix()),
	columns = columns)
	ell_df['species'] = species
	petal_ellipse.append(ell_df)
	petal_ellipse = pd.concat(petal_ellipse, axis=0).reset_index()

---

Personally I'd rather use polars, but the pandas dependency is already there due to https://github.com/altair-viz/vega_datasets

[dangotbanned]

polars version

Could probably be reduced a bit further.

• Using pl.DataFrame.partition_by works
  • But needing to handle dict[tuple[str, ...], pl.DataFrame] for a single key seems like a code smell

def pl_ellipse(
    df: pl.DataFrame, col_x: str, col_y: str, col_group: str
) -> pl.DataFrame:
    parts = df.select(col_x, col_y, col_group).partition_by(
        col_group, as_dict=True, include_key=False
    )
    return pl.concat(
        pl.DataFrame(np_ellipse(group.to_numpy()), [col_x, col_y])
        .with_columns(pl.lit(k[0]).alias(col_group))
        .with_row_index()
        for k, group in parts.items()
    )

[MarcoGorelli]

hey - i haven't looked into ellipse, but the pattern of creating a list of dataframes and then concatenating is what pandas recommends (as opposed to continuously concatenating in the for loop)

[dangotbanned]

hey - i haven't looked into ellipse, but the pattern of creating a list of dataframes and then concatenating is what pandas recommends (as opposed to continuously concatenating in the for loop)

Thanks @MarcoGorelli
I mean - if nothing jumped out at you as a pandas anti-pattern - then that's a good sign at least 🙂

Re: (ellipse|np_ellipse) the only relevant parts would be the signature:

from typing import TypeAlias
import numpy as np

_2DArray: TypeAlias = np.ndarray[tuple[int, int], np.dtype[np.float64]]

def np_ellipse(arr: _2DArray, segments: int = 50) -> _2DArray: ...

The segments parameter controls the number of rows (elements) returned.
So there's a potential for changing shape before/after numpy

[dangotbanned]

Suggested change

	groups = []
	# TODO: Rewrite in a more readable way
	categories = df[col_group].unique()
	groups = []
	categories = df[col_group].unique()