docs(example): Add Faceted map using Species Habitat dataset

[dsmedia]

This commit introduces a new example to the Altair documentation showcasing choropleth maps faceted by category.

Important

This example depends on the new Species Habitat dataset being added in vega/vega-datasets#684. That PR must be merged first before this example will work correctly.

The example visualizes the distribution of suitable habitat for different species across US counties, using the proposed new Species Habitat dataset from vega-datasets (vega/vega-datasets#684).

Key features of this example:

• Shows how to create faceted maps for comparing categorical data across geographic regions.
• Demonstrates the use of alt.Chart.mark_geoshape() for geographical visualizations.
• Utilizes the transform_lookup and transform_calculate transforms for data manipulation within Altair.
• Uses a CSV data file temporarily hosted in the vega-datasets repository branch (pending dataset merge).

This example addresses issue #1711, which requested a faceted map example for the Altair documentation.

[mattijn]

Thanks for this PR! Added two comments. Is this a replacement of https://altair-viz.github.io/gallery/us_incomebrackets_by_state_facet.html? Btw, why the facet is working in that example, I thought that didn’t work yet 🧐

[dsmedia]

Thanks for this PR! Added two comments. Is this a replacement of https://altair-viz.github.io/gallery/us_incomebrackets_by_state_facet.html?

Appreciate the suggestions @mattijn and good quetsion about the existing example. This would be intended to supplement rather than replace that example.

1. The income brackets example demonstrates faceting by numerical ranges, which is still a valid and useful visualization technique.

2. The new species habitat example demonstrates faceting by distinct categories (species), which represents a common use case highlighted by @palewire in the original issue:

#1711 (comment)

In news graphics, the most common case for a faceted map is when you want
to create a set of "mini multiples" that compare quantitative values on a
shared scaled across a set of competing nominative values.

#1711 (comment)

I think facets by time series segment or by a quantitative bracket are interesting, but I'd wager that both are much less common than charts that facet by a nominative category.

Will try to address the question on faceting separately.

[dsmedia]

@dangotbanned in 387f978 I need to use the following link to bring in the dataset as it's not available in the vega_datasets package on pypi.

url = "https://cdn.jsdelivr.net/npm/vega-datasets@latest/data/species.csv"

but i notice in CONTRIBUTE.md it says:

not make any external calls to download data within the script (i.e. don't use urllib). You can define your data directly within the example file, generate your data using pandas and numpy, or you can use data available in the vega_datasets package.

How should I proceed?