From 8e19225b43d757d6764c5f7997a6e7253bdcd33b Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 19 Oct 2022 22:56:26 +0200 Subject: [PATCH 01/24] include geopandas as doc dependency --- doc/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/requirements.txt b/doc/requirements.txt index bd6db4365..0f89d39b7 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -4,3 +4,4 @@ numpydoc pillow mistune<=0.8.4 pydata-sphinx-theme +geopandas From fe0a58909aeb486260b4a68028bab99e93aece3e Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 19 Oct 2022 22:57:03 +0200 Subject: [PATCH 02/24] create structure for marks --- doc/user_guide/data.rst | 2 +- doc/user_guide/marks/index.rst | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 doc/user_guide/marks/index.rst diff --git a/doc/user_guide/data.rst b/doc/user_guide/data.rst index e85276f61..4d57152b7 100644 --- a/doc/user_guide/data.rst +++ b/doc/user_guide/data.rst @@ -442,7 +442,7 @@ data before usage in Altair using GeoPandas for example as such: self encoding - marks + marks/index transform/index interactions compound_charts diff --git a/doc/user_guide/marks/index.rst b/doc/user_guide/marks/index.rst new file mode 100644 index 000000000..f3c3c425c --- /dev/null +++ b/doc/user_guide/marks/index.rst @@ -0,0 +1,27 @@ +.. currentmodule:: altair + +.. _user-guide-mark: + +Marks +----- + +We saw in :ref:`user-guide-encoding` that the :meth:`~Chart.encode` method is +used to map columns to visual attributes of the plot. +The ``mark`` property is what specifies how exactly those attributes +should be represented on the plot. + +Altair provides a number of basic mark properties +(the mark properties column links to the Vega-Lite documentation +that allows you to interactively explore the effects of modifying each property): + +========================================= ========================================= ================================================================================ +Mark Method Description +========================================= ========================================= ================================================================================ +:ref:`user-guide-mark-geoshape` :meth:`~Chart.mark_geoshape` Visualization containing spatial data +========================================= ========================================= ================================================================================ + + +.. toctree:: + :hidden: + + geoshape \ No newline at end of file From f3cbf5b06d08dd2d02255c1c50071abf16166b84 Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 19 Oct 2022 22:57:37 +0200 Subject: [PATCH 03/24] include geoshape doc raw --- doc/user_guide/marks/geoshape.rst | 658 ++++++++++++++++++++++++++++++ 1 file changed, 658 insertions(+) create mode 100644 doc/user_guide/marks/geoshape.rst diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst new file mode 100644 index 000000000..381aefa01 --- /dev/null +++ b/doc/user_guide/marks/geoshape.rst @@ -0,0 +1,658 @@ +.. currentmodule:: altair + +.. _user-guide-mark-geoshape: + +Geoshape +~~~~~~~~~~~~~ +The ``mark_geoshape`` represents an arbitrary shapes whose geometry is determined by specified spatial data. + +Basic Map +~~~~~~~~~ +Its most convenient to use a GeoDataFrame as input. Here we load the Natural Earth dataset and create a basic map using the geoshape mark: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + import geopandas as gpd + + fp = gpd.datasets.get_path('naturalearth_lowres') + gdf_ne = gpd.read_file(fp) # shapefile + + alt.Chart(gdf_ne).mark_geoshape() + +In the example above, Altair applies a default blue color and uses a default map projection (``equalEarth``). We can customize the colors and boundary stroke widths using standard mark properties. Using the ``project`` method we can also define the map projection manually: + +.. altair-plot:: + + alt.Chart(gdf_ne).mark_geoshape( + fill='lightgray', stroke='white', strokeWidth=0.5 + ).project( + type='equalEarth' + ) + +Focus & Filtering +~~~~~~~~~~~~~~~~~ +By default Altair automatically adjusts the projection so that all the data fits within the width and height of the chart. +Multiple approaches can be used to focus on specific regions of your spatial data. + +The following examples show different approaches to focus on continental Africa: + +1. Filter the source data within your GeoDataFrame: + +.. altair-plot:: + + gdf_sel = gdf_ne[gdf_ne.continent == 'Africa'] + + alt.Chart(gdf_sel).mark_geoshape().project( + type='equalEarth' + ) + +2. Filter the source data using a ``transorm_filter``: + +.. altair-plot:: + + alt.Chart(gdf_ne).mark_geoshape().project( + type='equalEarth' + ).transform_filter( + alt.datum.continent == 'Africa' + ) + +3. Specify projection parameters, such as ``scale`` (zoom level) and ``translate`` (panning): + +.. altair-plot:: + + alt.Chart(gdf_ne).mark_geoshape().project( + type='equalEarth', + scale=200, + translate=[160, 160] # lon, lat rotation + ) + +Cartesian coordinates +~~~~~~~~~~~~~~~~~~~~~ +The default projection of Altair is ``equalEarth``. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. +Another widely used coordinate system for data visualization is the 2d cartesian coordinate system. This coordinate system does not take into account the curvature of the Earth. + +In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` transformation. We have to define the ``reflectY`` as well since Canvas and SVG treats postive ``y`` as pointing down. + +.. altair-plot:: + + alt.Chart(gdf_sel).mark_geoshape().project( + type='identity', + reflectY=True + ) + +Mapping Polygons +~~~~~~~~~~~~~~~~ +The following example maps the visual property of the ``name`` column using the ``color`` encoding. + +.. altair-plot:: + + alt.Chart(gdf_sel).mark_geoshape().encode( + color='name:N' + ).project( + type='identity', + reflectY=True + ) + +Since each country is represented by a (multi)polygon, one can separate the ``stroke`` and ``fill`` defintions as such: + +.. altair-plot:: + + alt.Chart(gdf_sel).mark_geoshape( + stroke='white', + strokeWidth=1.5 + ).encode( + fill='name:N' + ).project( + type='identity', + reflectY=True + ) + +Mapping Lines +~~~~~~~~~~~~~ +By default Altair assumes for ``mark_geoshape`` that the mark's color is used for the fill color instead of the stroke color. +This means that if your source data contain (multi)lines, you will have to explicitly define the ``filled`` value as ``False``. + +Compare: + +.. altair-plot:: + + gs_line = gpd.GeoSeries.from_wkt(['LINESTRING (0 0, 1 1, 0 2, 2 2, -1 1, 1 0)']) + alt.Chart(gs_line).mark_geoshape().project( + type='identity', + reflectY=True + ) + +With: + +.. altair-plot:: + + gs_line = gpd.GeoSeries.from_wkt(['LINESTRING (0 0, 1 1, 0 2, 2 2, -1 1, 1 0)']) + alt.Chart(gs_line).mark_geoshape( + filled=False + ).project( + type='identity', + reflectY=True + ) + +Using this approach one can also style Polygons as if they are Linestrings: + +.. altair-plot:: + + alt.Chart(gdf_sel).mark_geoshape( + filled=False, + strokeWidth=1.5 + ).encode( + stroke='name:N' + ).project( + type='identity', + reflectY=True + ) + +Mapping Points +~~~~~~~~~~~~~~ +Points can be drawn when they are defined as ``Points`` within a GeoDataFrame using ``mark_geoshape``. +We first assign the centroids of Polygons as Point geometry and plot these: + +.. altair-plot:: + + gdf_centroid = gpd.GeoDataFrame( + data=gdf_sel.drop('geometry', axis=1), + geometry=gdf_sel.geometry.centroid + ) + + alt.Chart(gdf_centroid).mark_geoshape().project( + type='identity', + reflectY=True + ) + + +But to use the ``size`` encoding for the Points you will need to use the ``mark_circle`` plus defining the ``latitude`` and ``longitude`` encoding channels. + +.. altair-plot:: + + gdf_centroid['lon'] = gdf_centroid['geometry'].x + gdf_centroid['lat'] = gdf_centroid['geometry'].y + + alt.Chart(gdf_centroid).mark_circle().encode( + latitude='lat:Q', + longitude='lon:Q', + size="pop_est:Q" + ).project( + type='identity', + reflectY=True + ) + +You could skip the extra assingment to the ``lon`` and ``lat`` column in the GeoDataFrame and use the coordinates directly. We combine the chart with a basemap to bring some perspective to the points: + +.. altair-plot:: + + basemap = alt.Chart(gdf_sel).mark_geoshape( + fill='lightgray', stroke='white', strokeWidth=0.5 + ) + + bubbles = alt.Chart(gdf_centroid).mark_circle( + stroke='black' + ).encode( + latitude='geometry.coordinates[1]:Q', + longitude='geometry.coordinates[0]:Q', + size="pop_est:Q" + ) + + (basemap + bubbles).project( + type='identity', + reflectY=True + ) + +Altair also contains expressions related to geographical features. One could for example define the ``centroids`` using a ``geoCentroid`` expression: + +.. altair-plot:: + + from altair.expr import datum, geoCentroid + + bubbles = alt.Chart(gdf_sel).transform_calculate( + centroid=geoCentroid(None, datum) + ).mark_circle( + stroke='black' + ).encode( + longitude='centroid[0]:Q', + latitude='centroid[1]:Q', + size="pop_est:Q" + ) + + (basemap + bubbles).project( + type='identity', reflectY=True + ) + +Lookup datasets +~~~~~~~~~~~~~~~ +Sometimes your data is separated in two datasets. One ``DataFrame`` with the data and one ``GeoDataFrame`` with the geometries. +In this case you can use the ``lookup`` transform to connect related information in the other dataset. + +You can use the ``lookup`` transform in two directions. + +1. Use a GeoDataFrame with geometries as source and lookup related information in another DataFrame. +2. Use a DataFrame as source and lookup related geometries in a GeoDataFrame. + +Depending on your usecase one or the other is more favorable. + +First show an example of the first approach. +Here we lookup the field ``rate`` from the ``us_unemp`` DataFrame, where the ``us_counties`` GeoDataFrame is used as source: + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + import geopandas as gpd + + us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') + us_unemp = data.unemployment() + + alt.Chart(us_counties).mark_geoshape().transform_lookup( + lookup='id', + from_=alt.LookupData(data=us_unemp, key='id', fields=['rate']) + ).encode( + alt.Color('rate:Q') + ).project( + type='albersUsa' + ) + +Next, we show an example of the second approach. +Here we lookup the geometries through the fields ``geometry`` and ``type`` from the ``us_counties`` GeoDataFrame, where the ``us_unemp`` DataFrame is used as source. + +.. altair-plot:: + + alt.Chart(us_unemp).mark_geoshape().transform_lookup( + lookup='id', + from_=alt.LookupData(data=us_counties, key='id', fields=['geometry', 'type']) + ).encode( + alt.Color('rate:Q') + ).project( + type='albersUsa' + ) + + +Chloropleth Classification +~~~~~~~~~~~~~~~~~~~~~~~~~~ +Choropleth maps provide an easy way to visualize how a variable varies across a +geographic area or show the level of variability within a region. + +Take for example the following example of unemployment statistics of 2018 of US counties +(we define a utility function (`classify()` that we will use later again): + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + import geopandas as gpd + + def classify(scale_type, breaks=None, nice=False, title=None, size='small'): + + if size =='default': + width=400 + height=300 + else: + width=200 + height=150 + + us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') + us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') + us_unemp = data.unemployment() + + if title is None: + title=scale_type + + if 'threshold' in scale_type: + scale = alt.Scale(type=scale_type, domain=breaks, scheme='turbo') + else: + scale = alt.Scale(type=scale_type, nice=nice, scheme='turbo') + + fill = alt.Fill( + 'rate:Q', + scale=scale, + legend=alt.Legend(direction='horizontal', orient='bottom', format='.1%') + ) + + distrib_square = alt.Chart( + us_unemp, + height=20, + width=width + ).mark_square( + size=3, + opacity=1 + ).encode( + x=alt.X('rate:Q', title=None, axis=alt.Axis(format='.0%')), + y=alt.Y('jitter:Q', title=None, axis=None), + fill=fill + ).transform_calculate( + jitter='random()' + ) + + distrib_geoshape = alt.Chart( + us_counties, + width=width, + height=height, + title=title + ).mark_geoshape().transform_lookup( + lookup='id', + from_=alt.LookupData(data=us_unemp, key='id', fields=['rate']) + ).encode( + fill=fill + ).project( + type='albersUsa' + ) + + states_geoshape = alt.Chart( + us_states, + width=width, + height=height + ).mark_geoshape(filled=False, stroke='white', strokeWidth=0.75).project( + type='albersUsa' + ) + + return (distrib_geoshape + states_geoshape) & distrib_square + + classify('linear', size='default') + + +We visualise the unemployment `rate` in percentage of 2018 with a linear scale range +using a `mark_geoshape()` to present the spatial patterns on a map and a _jitter_ plot +(using `mark_square()`) to visualise the distribution of the `rate` values. Each value/ +county has defined an unique color. This gives a bit of insight, but often we like to +group the distribution into classes. + +By grouping values in classes, you can classify the dataset so all values/geometries in +each class get assigned the same color. + +Here we present a number of scale methods how Altair can be used: +- _quantile_, this type will divide your dataset (`domain`) into intervals of similar +sizes. Each class contains more or less the same number of values/geometries (equal +counts). The scale definition will look as follow: + +```python +alt.Scale(type='quantile') +``` + +- _quantize_, this type will divide the extent of your dataset (`range`) in equal +intervals. Each class contains different number of values, but the step size is equal +(equal range). The scale definition will look as follow: + +```python +alt.Scale(type='quantize') +``` + +The `quantize` methode can also be used in combination with `nice`. This will "nice" +the domain before applying quantization. As such: + +```python +alt.Scale(type='quantize', nice=True) +``` + +- _threshold_, this type will divide your dataset in separate classes by manually +specifying the cut values. Each class is separated by defined classes. The scale +definition will look as follow: + +```python +alt.Scale(type='quantize', range=[0.05, 0.20]) +``` + +This definition above will create 3 classes. One class with values below `0.05`, one +class with values from `0.05` to `0.20` and one class with values higher than `0.20`. + +So which method provides the optimal data classification for chloropleths maps? As +usual, it depends. There is another popular method that aid in determining class breaks. +This method will maximize the similarity of values in a class while maximizing the +distance between the classes (natural breaks). The method is also known by as the +Fisher-Jenks algorithm and is similar to _k_-Means in 1D: +- By using the external Python package `jenskpy` we can derive these _optimim_ breaks +as such: + +```python +>>> from jenkspy import JenksNaturalBreaks +>>> jnb = JenksNaturalBreaks(5) +>>> jnb.fit(us_unemp['rate']) +>>> jnb.inner_breaks_ +[0.061, 0.088, 0.116, 0.161] +``` +So when applying these different classification schemes to the county unemployment +dataset, we get the following overview: + +.. altair-plot:: + + alt.concat( + classify('linear'), + classify('quantile', title=['quantile','equal counts']), + classify('quantize', title=['quantize', 'equal range']), + classify('quantize', nice=True, title=['quantize', 'equal range nice']), + classify('threshold', breaks=[0.05, 0.20]), + classify('threshold', breaks=[0.061, 0.088, 0.116, 0.161], + title=['threshold Jenks','natural breaks'] + ), + columns=3 + ) + + +Caveats: + +- For the type `quantize` and `quantile` scales we observe that the default number of +classes is 5. It is currently not possible to define a different number of classes in +Altair in combination with a predefined color scheme. Track the following issue at the +Vega-Lite repository: https://github.com/vega/vega-lite/issues/8127 +- To define custom colors for each class, one should specify the `domain` and `range`. +Where the `range` contains +1 values than the classes specified in the `domain` +For example: `alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])` +In this `blue` is the class for all values below `0.05`, `white` for all values between +`0.05` and `0.20` and `red` for all values above `0.20`. +- The natural breaks method will determine the optimal class breaks given the required +number of classes. But how many classes should one pick? One can investigate usage of +goodness of variance fit (GVF), aka Jenks optimization method, to determine this. + + +Repeat a Map +~~~~~~~~~~~~ +The :class:`RepeatChart` pattern, accessible via the :meth:`Chart.repeat` method +provides a convenient interface for a particular type of horizontal or vertical +concatenation of a multi-dimensional dataset. + +In the following example we have a dataset referenced as `source` from which we use +three columns defining the `population`, `engineers` and `hurricanes` of each US state. + +The `states` is defined by making use of :func:`topo_feature` using `url` and `feature` +as parameters. This is a convenience function for extracting features from a topojson url. + +These variables we provide as list in the `.repeat()` operator, which we refer to within +the color encoding as `alt.repeat('row')` + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + + states = alt.topo_feature(data.us_10m.url, 'states') + source = data.population_engineers_hurricanes.url + variable_list = ['population', 'engineers', 'hurricanes'] + + alt.Chart(states).mark_geoshape(tooltip=True).encode( + alt.Color(alt.repeat('row'), type='quantitative') + ).transform_lookup( + lookup='id', + from_=alt.LookupData(source, 'id', variable_list) + ).project( + type='albersUsa' + ).repeat( + row=variable_list + ).resolve_scale( + color='independent' + ) + +Facet a Map +~~~~~~~~~~~ +The :class:`FacetChart` pattern, accessible via the :meth:`Chart.facet` method +provides a convenient interface for a particular type of horizontal or vertical +concatenation of a dataset where one field contain multiple `variables`. + +Unfortuantely, the following open issue https://github.com/altair-viz/altair/issues/2369 +will make the following not work for geographic visualization: + +.. altair-plot:: + + source = data.population_engineers_hurricanes().melt(id_vars=['state', 'id']) + us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') + gdf_comb = gpd.GeoDataFrame(source.join(us_states, on='id', rsuffix='_y')) + + alt.Chart(gdf_comb).mark_geoshape().encode( + color=alt.Color('value:Q'), + facet=alt.Facet('variable:N', columns=3) + ).properties( + width=200, + height=200 + ).resolve_scale('independent') + +For now, the following workaround can be adopted to facet a map, manually filter the +data in pandas, and create a small multiples chart via concatenation. For example: + +.. altair-plot:: + + alt.concat(*( + alt.Chart(gdf_comb[gdf_comb.variable == var], title=var).mark_geoshape().encode( + color='value:Q', + ).properties( + width=200 + ) + for var in gdf_comb.variable.unique() + ), columns=3 + ).resolve_scale(color='independent') + + +Interaction +~~~~~~~~~~~ +Often a map does not come alone, but is used in combination with another chart. +Here we provide an example of an interactive visualization of a bar chart and a map. + +The data shows the states of the US in combination with a bar chart showing the 15 most +populous states. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + import geopandas as gpd + + # load the data + us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') + us_population = data.population_engineers_hurricanes()[['state', 'id', 'population']] + + # define a pointer selection + click_state = alt.selection_point(fields=['state']) + + # create a chloropleth map using a lookup transform + # define a condition on the opacity encoding depending on the selection + choropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( + lookup='id', + from_=alt.LookupData(us_population, 'id', ['population', 'state']) + ).encode( + color='population:Q', + opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), + tooltip=['state:N', 'population:Q'] + ).project(type='albersUsa').add_params(click_state) + + # create a bar chart with a similar condition on the opacity encoding. + bars = alt.Chart( + us_population.nlargest(15, 'population'), + title='Top 15 states by population').mark_bar( + ).encode( + x='population', + opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), + color='population', + y=alt.Y('state', sort='-x') + ).add_params(click_state) + + + choropleth & bars + +Expression +~~~~~~~~~~ +Altair expressions can be used within a geographical visualization. The following example +visualize earthquakes on the globe using an `orthographic` projection. Where we can rotate +the earth on a single-axis. (`rotate0`). The utility function :func:sphere is adopted to +get a disk of the earth as background. + +The earthquakes are displayed using a `mark_geoshape` and filtered once out of sight of +the the visible part of the world. + +An hover highlighting is added to get more insight of each earthquake. + +.. altair-plot:: + + import altair as alt + from vega_datasets import data + import geopandas as gpd + + # load data + gdf_quakies = gpd.read_file(data.earthquakes.url, driver='GeoJSON') + gdf_world = gpd.read_file(data.world_110m.url, driver='TopoJSON') + + # define parameters + range0 = alt.binding_range(min=-180, max=180, step=5) + rotate0 = alt.param(value=120, bind=range0, name='rotate0') + hover = alt.selection_point(on='mouseover', clear='mouseout') + + # world disk + sphere = alt.Chart(alt.sphere()).mark_geoshape( + fill='aliceblue', + stroke='black', + strokeWidth=1.5 + ) + + # countries as shapes + world = alt.Chart(gdf_world).mark_geoshape( + fill='mintcream', + stroke='black', + strokeWidth=0.35 + ) + + # earthquakes as circles with fill for depth and size for magnitude + # the hover param is added on the mar_circle only + quakes = alt.Chart(gdf_quakies).mark_circle( + opacity=0.35, + tooltip=True, + stroke='black' + ).transform_calculate( + lon="datum.geometry.coordinates[0]", + lat="datum.geometry.coordinates[1]", + depth="datum.geometry.coordinates[2]" + ).transform_filter(''' + (rotate0 * -1) - 90 < datum.lon && datum.lon < (rotate0 * -1) + 90 + ''' + ).encode( + longitude='lon:Q', + latitude='lat:Q', + strokeWidth=alt.condition(hover, alt.value(1, empty=False), alt.value(0)), + size=alt.Size('mag:Q', scale=alt.Scale(type='pow', range=[1,1000], domain=[0,6], exponent=4)), + fill=alt.Fill('depth:Q', scale=alt.Scale(scheme='lightorange', domain=[0,400])) + ).add_params(hover) + + # define projection and add the rotation param for all layers + comb = alt.layer(sphere, world, quakes).project( + 'orthographic', + rotate=[90, 0, 0] + ).add_params(rotate0) + + # temporary changing params to top-level + # and defining the rotate reference expression on compiled VL directly + chart_vl = comb.to_dict() + chart_vl['params'] = chart_vl['layer'][0].pop('params') + chart_vl['projection']['rotate'] = {'expr':'[rotate0, 0, 0]'} + alt.Chart().from_dict(chart_vl) + +Geoshape Options +~~~~~~~~~~~~~~~~ + +Additional arguments to ``mark_geoshape()`` method are passed along to an +associated :class:`MarkDef` instance, which supports the following attributes: + +.. altair-object-table:: altair.MarkDef + +Marks can also be configured globally using chart-level configurations; see +:ref:`config-mark` for details. From 16f9be50d2eae701562cce004ef0846387fd0503 Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 19 Oct 2022 23:06:47 +0200 Subject: [PATCH 04/24] classify - refer by url --- doc/user_guide/marks/geoshape.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 381aefa01..20a7a58a7 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -296,9 +296,11 @@ Take for example the following example of unemployment statistics of 2018 of US width=200 height=150 - us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') - us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') - us_unemp = data.unemployment() + # us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') + # us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') + us_counties = alt.topo_feature(data.us_10m.url, 'counties') + us_states = alt.topo_feature(data.us_10m.url, 'states') + us_unemp = data.unemployment.url if title is None: title=scale_type From 07a29a2e054752dc7dd27665e19c6c1f2bc41061 Mon Sep 17 00:00:00 2001 From: mattijn Date: Mon, 31 Oct 2022 22:57:15 +0100 Subject: [PATCH 05/24] typos and few code updates --- doc/user_guide/marks/geoshape.rst | 85 +++++++++++++++---------------- 1 file changed, 42 insertions(+), 43 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 20a7a58a7..9687597ac 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -26,7 +26,7 @@ In the example above, Altair applies a default blue color and uses a default map .. altair-plot:: alt.Chart(gdf_ne).mark_geoshape( - fill='lightgray', stroke='white', strokeWidth=0.5 + fill='lightgrey', stroke='white', strokeWidth=0.5 ).project( type='equalEarth' ) @@ -48,7 +48,7 @@ The following examples show different approaches to focus on continental Africa: type='equalEarth' ) -2. Filter the source data using a ``transorm_filter``: +2. Filter the source data using a ``transform_filter``: .. altair-plot:: @@ -65,7 +65,7 @@ The following examples show different approaches to focus on continental Africa: alt.Chart(gdf_ne).mark_geoshape().project( type='equalEarth', scale=200, - translate=[160, 160] # lon, lat rotation + translate=[160, 160] # lon, lat, rotation ) Cartesian coordinates @@ -73,7 +73,7 @@ Cartesian coordinates The default projection of Altair is ``equalEarth``. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. Another widely used coordinate system for data visualization is the 2d cartesian coordinate system. This coordinate system does not take into account the curvature of the Earth. -In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` transformation. We have to define the ``reflectY`` as well since Canvas and SVG treats postive ``y`` as pointing down. +In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` transformation. We have to define the ``reflectY`` as well since Canvas and SVG treats positive ``y`` as pointing down. .. altair-plot:: @@ -95,7 +95,7 @@ The following example maps the visual property of the ``name`` column using the reflectY=True ) -Since each country is represented by a (multi)polygon, one can separate the ``stroke`` and ``fill`` defintions as such: +Since each country is represented by a (multi)polygon, one can separate the ``stroke`` and ``fill`` definitions as such: .. altair-plot:: @@ -176,15 +176,15 @@ But to use the ``size`` encoding for the Points you will need to use the ``mark_ gdf_centroid['lat'] = gdf_centroid['geometry'].y alt.Chart(gdf_centroid).mark_circle().encode( - latitude='lat:Q', longitude='lon:Q', + latitude='lat:Q', size="pop_est:Q" ).project( type='identity', reflectY=True ) -You could skip the extra assingment to the ``lon`` and ``lat`` column in the GeoDataFrame and use the coordinates directly. We combine the chart with a basemap to bring some perspective to the points: +You could skip the extra assignment to the ``lon`` and ``lat`` column in the GeoDataFrame and use the coordinates directly. We combine the chart with a basemap to bring some perspective to the points: .. altair-plot:: @@ -195,8 +195,8 @@ You could skip the extra assingment to the ``lon`` and ``lat`` column in the Geo bubbles = alt.Chart(gdf_centroid).mark_circle( stroke='black' ).encode( + longitude='geometry.coordinates[0]:Q', latitude='geometry.coordinates[1]:Q', - longitude='geometry.coordinates[0]:Q', size="pop_est:Q" ) @@ -235,7 +235,7 @@ You can use the ``lookup`` transform in two directions. 1. Use a GeoDataFrame with geometries as source and lookup related information in another DataFrame. 2. Use a DataFrame as source and lookup related geometries in a GeoDataFrame. -Depending on your usecase one or the other is more favorable. +Depending on your use-case one or the other is more favorable. First show an example of the first approach. Here we lookup the field ``rate`` from the ``us_unemp`` DataFrame, where the ``us_counties`` GeoDataFrame is used as source: @@ -358,9 +358,9 @@ Take for example the following example of unemployment statistics of 2018 of US classify('linear', size='default') -We visualise the unemployment `rate` in percentage of 2018 with a linear scale range +We visualize the unemployment `rate` in percentage of 2018 with a linear scale range using a `mark_geoshape()` to present the spatial patterns on a map and a _jitter_ plot -(using `mark_square()`) to visualise the distribution of the `rate` values. Each value/ +(using `mark_square()`) to visualize the distribution of the `rate` values. Each value/ county has defined an unique color. This gives a bit of insight, but often we like to group the distribution into classes. @@ -384,7 +384,7 @@ intervals. Each class contains different number of values, but the step size is alt.Scale(type='quantize') ``` -The `quantize` methode can also be used in combination with `nice`. This will "nice" +The `quantize` method can also be used in combination with `nice`. This will "nice" the domain before applying quantization. As such: ```python @@ -402,12 +402,12 @@ alt.Scale(type='quantize', range=[0.05, 0.20]) This definition above will create 3 classes. One class with values below `0.05`, one class with values from `0.05` to `0.20` and one class with values higher than `0.20`. -So which method provides the optimal data classification for chloropleths maps? As +So which method provides the optimal data classification for chloropleth maps? As usual, it depends. There is another popular method that aid in determining class breaks. This method will maximize the similarity of values in a class while maximizing the distance between the classes (natural breaks). The method is also known by as the Fisher-Jenks algorithm and is similar to _k_-Means in 1D: -- By using the external Python package `jenskpy` we can derive these _optimim_ breaks +- By using the external Python package `jenskpy` we can derive these _optimum_ breaks as such: ```python @@ -438,11 +438,11 @@ dataset, we get the following overview: Caveats: - For the type `quantize` and `quantile` scales we observe that the default number of -classes is 5. It is currently not possible to define a different number of classes in -Altair in combination with a predefined color scheme. Track the following issue at the -Vega-Lite repository: https://github.com/vega/vega-lite/issues/8127 +classes is 5. You can change the number of classes using a `SchemeParams()` object. In the +above specification we can change `scheme='turbo'` into `scheme=alt.SchemeParams('turbo', count=2)` +to manually specify usage of 2 classes for the scheme within the scale. - To define custom colors for each class, one should specify the `domain` and `range`. -Where the `range` contains +1 values than the classes specified in the `domain` +Where the `range` contains `+1` values than the classes specified in the `domain` For example: `alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])` In this `blue` is the class for all values below `0.05`, `white` for all values between `0.05` and `0.20` and `red` for all values above `0.20`. @@ -494,7 +494,7 @@ The :class:`FacetChart` pattern, accessible via the :meth:`Chart.facet` method provides a convenient interface for a particular type of horizontal or vertical concatenation of a dataset where one field contain multiple `variables`. -Unfortuantely, the following open issue https://github.com/altair-viz/altair/issues/2369 +Unfortunately, the following open issue https://github.com/altair-viz/altair/issues/2369 will make the following not work for geographic visualization: .. altair-plot:: @@ -516,15 +516,19 @@ data in pandas, and create a small multiples chart via concatenation. For exampl .. altair-plot:: - alt.concat(*( - alt.Chart(gdf_comb[gdf_comb.variable == var], title=var).mark_geoshape().encode( - color='value:Q', - ).properties( - width=200 - ) - for var in gdf_comb.variable.unique() - ), columns=3 - ).resolve_scale(color='independent') + alt.concat( + *( + alt.Chart(gdf_comb[gdf_comb.variable == var], title=var) + .mark_geoshape() + .encode( + color="value:Q", + ) + .properties(width=200) + for var in gdf_comb.variable.unique() + ), + columns=3 + ).resolve_scale(color="independent") + Interaction @@ -550,7 +554,7 @@ populous states. # create a chloropleth map using a lookup transform # define a condition on the opacity encoding depending on the selection - choropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( + chloropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( lookup='id', from_=alt.LookupData(us_population, 'id', ['population', 'state']) ).encode( @@ -571,7 +575,7 @@ populous states. ).add_params(click_state) - choropleth & bars + chloropleth & bars Expression ~~~~~~~~~~ @@ -597,7 +601,8 @@ An hover highlighting is added to get more insight of each earthquake. # define parameters range0 = alt.binding_range(min=-180, max=180, step=5) - rotate0 = alt.param(value=120, bind=range0, name='rotate0') + rotate0 = alt.param(value=120, bind=range0, name='param_rotate0') + rotate_param = alt.param(expr=f'[{rotate0.name}, 0, 0]') hover = alt.selection_point(on='mouseover', clear='mouseout') # world disk @@ -624,8 +629,8 @@ An hover highlighting is added to get more insight of each earthquake. lon="datum.geometry.coordinates[0]", lat="datum.geometry.coordinates[1]", depth="datum.geometry.coordinates[2]" - ).transform_filter(''' - (rotate0 * -1) - 90 < datum.lon && datum.lon < (rotate0 * -1) + 90 + ).transform_filter(f''' + ({rotate0.name} * -1) - 90 < datum.lon && datum.lon < ({rotate0.name} * -1) + 90 ''' ).encode( longitude='lon:Q', @@ -633,20 +638,14 @@ An hover highlighting is added to get more insight of each earthquake. strokeWidth=alt.condition(hover, alt.value(1, empty=False), alt.value(0)), size=alt.Size('mag:Q', scale=alt.Scale(type='pow', range=[1,1000], domain=[0,6], exponent=4)), fill=alt.Fill('depth:Q', scale=alt.Scale(scheme='lightorange', domain=[0,400])) - ).add_params(hover) + ).add_params(hover, rotate0) # define projection and add the rotation param for all layers comb = alt.layer(sphere, world, quakes).project( 'orthographic', - rotate=[90, 0, 0] - ).add_params(rotate0) - - # temporary changing params to top-level - # and defining the rotate reference expression on compiled VL directly - chart_vl = comb.to_dict() - chart_vl['params'] = chart_vl['layer'][0].pop('params') - chart_vl['projection']['rotate'] = {'expr':'[rotate0, 0, 0]'} - alt.Chart().from_dict(chart_vl) + rotate=rotate_param + ).add_params(rotate_param) + comb Geoshape Options ~~~~~~~~~~~~~~~~ From 54e01facb719db45ce956e6e9eb6ae888ec164e1 Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 2 Nov 2022 11:11:35 +0100 Subject: [PATCH 06/24] fix more styling --- doc/user_guide/marks/geoshape.rst | 184 +++++++++++++++++++----------- 1 file changed, 117 insertions(+), 67 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 9687597ac..3f64fa2ac 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -34,9 +34,14 @@ In the example above, Altair applies a default blue color and uses a default map Focus & Filtering ~~~~~~~~~~~~~~~~~ By default Altair automatically adjusts the projection so that all the data fits within the width and height of the chart. -Multiple approaches can be used to focus on specific regions of your spatial data. +Multiple approaches can be used to focus on specific regions of your spatial data. Namely: -The following examples show different approaches to focus on continental Africa: +1. Filter the source data within your GeoDataFrame. +2. Filter the source data using a ``transform_filter``. +3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project()`` method. +4. Specify ``fit`` (extent) within the ``project()`` method. + +The following examples applies these approaches to focus on continental Africa: 1. Filter the source data within your GeoDataFrame: @@ -58,16 +63,36 @@ The following examples show different approaches to focus on continental Africa: alt.datum.continent == 'Africa' ) -3. Specify projection parameters, such as ``scale`` (zoom level) and ``translate`` (panning): +3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project()`` method: .. altair-plot:: alt.Chart(gdf_ne).mark_geoshape().project( type='equalEarth', scale=200, - translate=[160, 160] # lon, lat, rotation + translate=[160, 160, 0] # lon, lat, rotation ) +3. Specify ``fit`` (extent) within the ``project()`` method: + +.. altair-plot:: + + from shapely.ops import orient + from shapely.geometry import mapping + + extent_roi = gdf_ne.query("continent == 'Africa'").unary_union.envelope + + # fit object should be an array of GeoJSON-like features + # order polygon exterior needs to be clock-wise (left-hand-rule) + if extent_roi.exterior.is_ccw: + extent_roi = orient(extent_roi, -1) + extent_roi_geojson = [mapping(extent_roi)] + + alt.Chart(gdf_ne).mark_geoshape().project( + type='equalEarth', + fit=extent_roi_geojson + ) + Cartesian coordinates ~~~~~~~~~~~~~~~~~~~~~ The default projection of Altair is ``equalEarth``. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. @@ -232,13 +257,13 @@ In this case you can use the ``lookup`` transform to connect related information You can use the ``lookup`` transform in two directions. -1. Use a GeoDataFrame with geometries as source and lookup related information in another DataFrame. -2. Use a DataFrame as source and lookup related geometries in a GeoDataFrame. +1. Use a ``GeoDataFrame`` with geometries as source and lookup related information in another ``DataFrame``. +2. Use a ``DataFrame`` as source and lookup related geometries in a ``GeoDataFrame``. Depending on your use-case one or the other is more favorable. First show an example of the first approach. -Here we lookup the field ``rate`` from the ``us_unemp`` DataFrame, where the ``us_counties`` GeoDataFrame is used as source: +Here we lookup the field ``rate`` from the ``df_us_unemp`` DataFrame, where the ``gdf_us_counties`` GeoDataFrame is used as source: .. altair-plot:: @@ -246,12 +271,12 @@ Here we lookup the field ``rate`` from the ``us_unemp`` DataFrame, where the ``u from vega_datasets import data import geopandas as gpd - us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') - us_unemp = data.unemployment() + gdf_us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') + df_us_unemp = data.unemployment() - alt.Chart(us_counties).mark_geoshape().transform_lookup( + alt.Chart(gdf_us_counties).mark_geoshape().transform_lookup( lookup='id', - from_=alt.LookupData(data=us_unemp, key='id', fields=['rate']) + from_=alt.LookupData(data=df_us_unemp, key='id', fields=['rate']) ).encode( alt.Color('rate:Q') ).project( @@ -259,13 +284,13 @@ Here we lookup the field ``rate`` from the ``us_unemp`` DataFrame, where the ``u ) Next, we show an example of the second approach. -Here we lookup the geometries through the fields ``geometry`` and ``type`` from the ``us_counties`` GeoDataFrame, where the ``us_unemp`` DataFrame is used as source. +Here we lookup the geometries through the fields ``geometry`` and ``type`` from the ``gdf_us_counties`` GeoDataFrame, where the ``df_us_unemp`` DataFrame is used as source. .. altair-plot:: - alt.Chart(us_unemp).mark_geoshape().transform_lookup( + alt.Chart(df_us_unemp).mark_geoshape().transform_lookup( lookup='id', - from_=alt.LookupData(data=us_counties, key='id', fields=['geometry', 'type']) + from_=alt.LookupData(data=gdf_us_counties, key='id', fields=['geometry', 'type']) ).encode( alt.Color('rate:Q') ).project( @@ -278,8 +303,7 @@ Chloropleth Classification Choropleth maps provide an easy way to visualize how a variable varies across a geographic area or show the level of variability within a region. -Take for example the following example of unemployment statistics of 2018 of US counties -(we define a utility function (`classify()` that we will use later again): +We first define a utility function ``classify()`` that we will use to showcase different approaches: .. altair-plot:: @@ -355,69 +379,102 @@ Take for example the following example of unemployment statistics of 2018 of US return (distrib_geoshape + states_geoshape) & distrib_square + +Take for example the following example of unemployment statistics of 2018 of US counties. + +.. altair-plot:: + classify('linear', size='default') -We visualize the unemployment `rate` in percentage of 2018 with a linear scale range -using a `mark_geoshape()` to present the spatial patterns on a map and a _jitter_ plot -(using `mark_square()`) to visualize the distribution of the `rate` values. Each value/ -county has defined an unique color. This gives a bit of insight, but often we like to +We visualize the unemployment ``rate`` in percentage of 2018 with a ``linear`` scale range +using a ``mark_geoshape()`` to present the spatial patterns on a map and a ``jitter`` plot +(using ``mark_square()``) to visualize the distribution of the ``rate`` values. Each value/ +county has defined a `unique` color. This gives a bit of insight, but often we like to group the distribution into classes. By grouping values in classes, you can classify the dataset so all values/geometries in each class get assigned the same color. Here we present a number of scale methods how Altair can be used: -- _quantile_, this type will divide your dataset (`domain`) into intervals of similar + +- ``quantile``, this type will divide your dataset (`domain`) into intervals of similar sizes. Each class contains more or less the same number of values/geometries (equal counts). The scale definition will look as follow: -```python -alt.Scale(type='quantile') -``` +.. code:: python + + alt.Scale(type='quantile') + + +.. altair-plot:: + + classify('quantile', size='default') + -- _quantize_, this type will divide the extent of your dataset (`range`) in equal +- ``quantize``, this type will divide the extent of your dataset (`range`) in equal intervals. Each class contains different number of values, but the step size is equal -(equal range). The scale definition will look as follow: +(`equal range`). The scale definition will look as follow: + +.. code:: python + + alt.Scale(type='quantize') + +.. altair-plot:: -```python -alt.Scale(type='quantize') -``` + classify('quantize', size='default') -The `quantize` method can also be used in combination with `nice`. This will "nice" + +The ``quantize`` method can also be used in combination with ``nice``. This will "nice" the domain before applying quantization. As such: -```python -alt.Scale(type='quantize', nice=True) -``` +.. code:: python + + alt.Scale(type='quantize', nice=True) + +.. altair-plot:: + + classify('quantize', nice=True, size='default') + -- _threshold_, this type will divide your dataset in separate classes by manually + +- ``threshold``, this type will divide your dataset in separate classes by manually specifying the cut values. Each class is separated by defined classes. The scale definition will look as follow: -```python -alt.Scale(type='quantize', range=[0.05, 0.20]) -``` +.. code:: python + + alt.Scale(type='threshold', breaks=[0.05, 0.20]) + + +.. altair-plot:: + + classify('threshold', breaks=[0.05, 0.20], size='default') + This definition above will create 3 classes. One class with values below `0.05`, one class with values from `0.05` to `0.20` and one class with values higher than `0.20`. So which method provides the optimal data classification for chloropleth maps? As -usual, it depends. There is another popular method that aid in determining class breaks. +usual, it depends. + +There is another popular method that aid in determining class breaks. This method will maximize the similarity of values in a class while maximizing the distance between the classes (natural breaks). The method is also known by as the -Fisher-Jenks algorithm and is similar to _k_-Means in 1D: -- By using the external Python package `jenskpy` we can derive these _optimum_ breaks +Fisher-Jenks algorithm and is similar to k-Means in 1D: + +- By using the external Python package ``jenskpy`` we can derive these `optimum` breaks as such: -```python ->>> from jenkspy import JenksNaturalBreaks ->>> jnb = JenksNaturalBreaks(5) ->>> jnb.fit(us_unemp['rate']) ->>> jnb.inner_breaks_ -[0.061, 0.088, 0.116, 0.161] -``` -So when applying these different classification schemes to the county unemployment +.. code:: python + + >>> from jenkspy import JenksNaturalBreaks + >>> jnb = JenksNaturalBreaks(5) + >>> jnb.fit(us_unemp['rate']) + >>> jnb.inner_breaks_ + [0.061, 0.088, 0.116, 0.161] + +So when applying all these different classification schemes to the county unemployment dataset, we get the following overview: .. altair-plot:: @@ -437,18 +494,9 @@ dataset, we get the following overview: Caveats: -- For the type `quantize` and `quantile` scales we observe that the default number of -classes is 5. You can change the number of classes using a `SchemeParams()` object. In the -above specification we can change `scheme='turbo'` into `scheme=alt.SchemeParams('turbo', count=2)` -to manually specify usage of 2 classes for the scheme within the scale. -- To define custom colors for each class, one should specify the `domain` and `range`. -Where the `range` contains `+1` values than the classes specified in the `domain` -For example: `alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])` -In this `blue` is the class for all values below `0.05`, `white` for all values between -`0.05` and `0.20` and `red` for all values above `0.20`. -- The natural breaks method will determine the optimal class breaks given the required -number of classes. But how many classes should one pick? One can investigate usage of -goodness of variance fit (GVF), aka Jenks optimization method, to determine this. +- For the type ``quantize`` and ``quantile`` scales we observe that the default number of classes is 5. You can change the number of classes using a `SchemeParams()` object. In the above specification we can change ``scheme='turbo'`` into ``scheme=alt.SchemeParams('turbo', count=2)`` to manually specify usage of 2 classes for the scheme within the scale. +- To define custom colors for each class, one should specify the ``domain`` and ``range``. Where the ``range`` contains ``+1`` values than the classes specified in the ``domain``. For example: ``alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])``. ``blue`` is the class for all values below ``0.05``, ``white`` for all values between ``0.05`` and ``0.20`` and ``red`` for all values above ``0.20``. +- The natural breaks method will determine the optimal class breaks given the required number of classes. But how many classes should one pick? One can investigate usage of goodness of variance fit (GVF), aka Jenks optimization method, to determine this. Repeat a Map @@ -577,18 +625,15 @@ populous states. chloropleth & bars +The interaction is two-directional. If you click (shift-click for multi-selection) on a geometry or bar the selection receive an ``opacity`` of ``1`` and the remaining an ``opacity`` of ``0.2``. + Expression ~~~~~~~~~~ Altair expressions can be used within a geographical visualization. The following example -visualize earthquakes on the globe using an `orthographic` projection. Where we can rotate -the earth on a single-axis. (`rotate0`). The utility function :func:sphere is adopted to +visualize earthquakes on the globe using an ``orthographic`` projection. Where we can rotate +the earth on a single-axis. (``rotate0``). The utility function :func:sphere is adopted to get a disk of the earth as background. -The earthquakes are displayed using a `mark_geoshape` and filtered once out of sight of -the the visible part of the world. - -An hover highlighting is added to get more insight of each earthquake. - .. altair-plot:: import altair as alt @@ -647,6 +692,11 @@ An hover highlighting is added to get more insight of each earthquake. ).add_params(rotate_param) comb +The earthquakes are displayed using a ``mark_geoshape`` and filtered once out of sight of +the the visible part of the world. + +A hover highlighting is added to get more insight of each earthquake. + Geoshape Options ~~~~~~~~~~~~~~~~ From d3394faef3441cb69c16763aeeba13110332091c Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 2 Nov 2022 13:53:39 +0100 Subject: [PATCH 07/24] make typo fixes --- doc/user_guide/marks/geoshape.rst | 98 +++++++++++++------------------ 1 file changed, 40 insertions(+), 58 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 3f64fa2ac..e34a3fd7d 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -8,7 +8,7 @@ The ``mark_geoshape`` represents an arbitrary shapes whose geometry is determine Basic Map ~~~~~~~~~ -Its most convenient to use a GeoDataFrame as input. Here we load the Natural Earth dataset and create a basic map using the geoshape mark: +Its most convenient to use a ``GeoDataFrame`` as input. Here we load the Natural Earth dataset and create a basic map using the ``mark_geoshape``: .. altair-plot:: @@ -21,7 +21,7 @@ Its most convenient to use a GeoDataFrame as input. Here we load the Natural Ear alt.Chart(gdf_ne).mark_geoshape() -In the example above, Altair applies a default blue color and uses a default map projection (``equalEarth``). We can customize the colors and boundary stroke widths using standard mark properties. Using the ``project`` method we can also define the map projection manually: +In the example above, Altair applies a default blue ``fill`` color and uses a default map projection (``equalEarth``). We can customize the colors and boundary stroke widths using standard mark properties. Using the ``project`` method we can also define the map projection manually: .. altair-plot:: @@ -38,8 +38,8 @@ Multiple approaches can be used to focus on specific regions of your spatial dat 1. Filter the source data within your GeoDataFrame. 2. Filter the source data using a ``transform_filter``. -3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project()`` method. -4. Specify ``fit`` (extent) within the ``project()`` method. +3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project`` method. +4. Specify ``fit`` (extent) within the ``project`` & ``clip=True`` in the mark properties. The following examples applies these approaches to focus on continental Africa: @@ -63,7 +63,7 @@ The following examples applies these approaches to focus on continental Africa: alt.datum.continent == 'Africa' ) -3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project()`` method: +3. Specify ``scale`` (zoom level) and ``translate`` (panning) within the ``project`` method: .. altair-plot:: @@ -73,7 +73,7 @@ The following examples applies these approaches to focus on continental Africa: translate=[160, 160, 0] # lon, lat, rotation ) -3. Specify ``fit`` (extent) within the ``project()`` method: +3. Specify ``fit`` (extent) within the ``project`` method & ``clip=True`` in the mark properties: .. altair-plot:: @@ -88,7 +88,7 @@ The following examples applies these approaches to focus on continental Africa: extent_roi = orient(extent_roi, -1) extent_roi_geojson = [mapping(extent_roi)] - alt.Chart(gdf_ne).mark_geoshape().project( + alt.Chart(gdf_ne).mark_geoshape(clip=True).project( type='equalEarth', fit=extent_roi_geojson ) @@ -98,7 +98,7 @@ Cartesian coordinates The default projection of Altair is ``equalEarth``. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. Another widely used coordinate system for data visualization is the 2d cartesian coordinate system. This coordinate system does not take into account the curvature of the Earth. -In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` transformation. We have to define the ``reflectY`` as well since Canvas and SVG treats positive ``y`` as pointing down. +In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` projection type. We have to define the ``reflectY`` as well since Canvas and SVG treats positive ``y`` as pointing down. .. altair-plot:: @@ -115,12 +115,9 @@ The following example maps the visual property of the ``name`` column using the alt.Chart(gdf_sel).mark_geoshape().encode( color='name:N' - ).project( - type='identity', - reflectY=True ) -Since each country is represented by a (multi)polygon, one can separate the ``stroke`` and ``fill`` definitions as such: +Since each country is represented by a (multi)polygon, we can separate the ``stroke`` and ``fill`` definitions as such: .. altair-plot:: @@ -129,9 +126,6 @@ Since each country is represented by a (multi)polygon, one can separate the ``st strokeWidth=1.5 ).encode( fill='name:N' - ).project( - type='identity', - reflectY=True ) Mapping Lines @@ -170,9 +164,6 @@ Using this approach one can also style Polygons as if they are Linestrings: strokeWidth=1.5 ).encode( stroke='name:N' - ).project( - type='identity', - reflectY=True ) Mapping Points @@ -187,13 +178,10 @@ We first assign the centroids of Polygons as Point geometry and plot these: geometry=gdf_sel.geometry.centroid ) - alt.Chart(gdf_centroid).mark_geoshape().project( - type='identity', - reflectY=True - ) + alt.Chart(gdf_centroid).mark_geoshape() -But to use the ``size`` encoding for the Points you will need to use the ``mark_circle`` plus defining the ``latitude`` and ``longitude`` encoding channels. +Caveat: To use the ``size`` encoding for the Points you will need to use the ``mark_circle`` in combination with the ``latitude`` and ``longitude`` encoding channel definitions. .. altair-plot:: @@ -204,9 +192,6 @@ But to use the ``size`` encoding for the Points you will need to use the ``mark_ longitude='lon:Q', latitude='lat:Q', size="pop_est:Q" - ).project( - type='identity', - reflectY=True ) You could skip the extra assignment to the ``lon`` and ``lat`` column in the GeoDataFrame and use the coordinates directly. We combine the chart with a basemap to bring some perspective to the points: @@ -230,7 +215,7 @@ You could skip the extra assignment to the ``lon`` and ``lat`` column in the Geo reflectY=True ) -Altair also contains expressions related to geographical features. One could for example define the ``centroids`` using a ``geoCentroid`` expression: +Altair also contains expressions related to geographical features. We can for example define the ``centroids`` using a ``geoCentroid`` expression: .. altair-plot:: @@ -253,16 +238,16 @@ Altair also contains expressions related to geographical features. One could for Lookup datasets ~~~~~~~~~~~~~~~ Sometimes your data is separated in two datasets. One ``DataFrame`` with the data and one ``GeoDataFrame`` with the geometries. -In this case you can use the ``lookup`` transform to connect related information in the other dataset. +In this case you can use the ``lookup`` transform to collect related information from the other dataset. -You can use the ``lookup`` transform in two directions. +You can use the ``lookup`` transform in two directions: 1. Use a ``GeoDataFrame`` with geometries as source and lookup related information in another ``DataFrame``. 2. Use a ``DataFrame`` as source and lookup related geometries in a ``GeoDataFrame``. Depending on your use-case one or the other is more favorable. -First show an example of the first approach. +First we show an example of the first approach. Here we lookup the field ``rate`` from the ``df_us_unemp`` DataFrame, where the ``gdf_us_counties`` GeoDataFrame is used as source: .. altair-plot:: @@ -300,10 +285,10 @@ Here we lookup the geometries through the fields ``geometry`` and ``type`` from Chloropleth Classification ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Choropleth maps provide an easy way to visualize how a variable varies across a +Chloropleth maps provide an easy way to visualize how a variable varies across a geographic area or show the level of variability within a region. -We first define a utility function ``classify()`` that we will use to showcase different approaches: +We first define a utility function ``classify()`` that we will use to showcase different approaches to make a chloropleth map: .. altair-plot:: @@ -380,7 +365,7 @@ We first define a utility function ``classify()`` that we will use to showcase d return (distrib_geoshape + states_geoshape) & distrib_square -Take for example the following example of unemployment statistics of 2018 of US counties. +Take for example the following example where we define a cholorpleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. .. altair-plot:: @@ -398,61 +383,58 @@ each class get assigned the same color. Here we present a number of scale methods how Altair can be used: -- ``quantile``, this type will divide your dataset (`domain`) into intervals of similar -sizes. Each class contains more or less the same number of values/geometries (equal -counts). The scale definition will look as follow: +- ``quantile``, this type will divide your dataset (`domain`) into intervals of similar sizes. Each class contains more or less the same number of values/geometries (equal counts). The scale definition will look as follow: .. code:: python alt.Scale(type='quantile') +And applied in our utility function: .. altair-plot:: classify('quantile', size='default') -- ``quantize``, this type will divide the extent of your dataset (`range`) in equal -intervals. Each class contains different number of values, but the step size is equal -(`equal range`). The scale definition will look as follow: +- ``quantize``, this type will divide the extent of your dataset (`range`) in equal intervals. Each class contains different number of values, but the step size is equal (`equal range`). The scale definition will look as follow: .. code:: python alt.Scale(type='quantize') +And applied in our utility function: + .. altair-plot:: classify('quantize', size='default') -The ``quantize`` method can also be used in combination with ``nice``. This will "nice" -the domain before applying quantization. As such: +The ``quantize`` method can also be used in combination with ``nice``. This will "nice" the domain before applying quantization. As such: .. code:: python alt.Scale(type='quantize', nice=True) +And applied in our utility function: + .. altair-plot:: classify('quantize', nice=True, size='default') - - -- ``threshold``, this type will divide your dataset in separate classes by manually -specifying the cut values. Each class is separated by defined classes. The scale -definition will look as follow: +- ``threshold``, this type will divide your dataset in separate classes by manually specifying the cut values. Each class is separated by defined classes. The scale definition will look as follow: .. code:: python alt.Scale(type='threshold', breaks=[0.05, 0.20]) +And applied in our utility function: .. altair-plot:: classify('threshold', breaks=[0.05, 0.20], size='default') -This definition above will create 3 classes. One class with values below `0.05`, one +The definition above will create 3 classes. One class with values below `0.05`, one class with values from `0.05` to `0.20` and one class with values higher than `0.20`. So which method provides the optimal data classification for chloropleth maps? As @@ -460,7 +442,7 @@ usual, it depends. There is another popular method that aid in determining class breaks. This method will maximize the similarity of values in a class while maximizing the -distance between the classes (natural breaks). The method is also known by as the +distance between the classes (natural breaks). The method is also known as the Fisher-Jenks algorithm and is similar to k-Means in 1D: - By using the external Python package ``jenskpy`` we can derive these `optimum` breaks @@ -470,7 +452,7 @@ as such: >>> from jenkspy import JenksNaturalBreaks >>> jnb = JenksNaturalBreaks(5) - >>> jnb.fit(us_unemp['rate']) + >>> jnb.fit(df_us_unemp['rate']) >>> jnb.inner_breaks_ [0.061, 0.088, 0.116, 0.161] @@ -494,9 +476,9 @@ dataset, we get the following overview: Caveats: -- For the type ``quantize`` and ``quantile`` scales we observe that the default number of classes is 5. You can change the number of classes using a `SchemeParams()` object. In the above specification we can change ``scheme='turbo'`` into ``scheme=alt.SchemeParams('turbo', count=2)`` to manually specify usage of 2 classes for the scheme within the scale. +- For the type ``quantize`` and ``quantile`` scales we observe that the default number of classes is 5. You can change the number of classes using a ``SchemeParams()`` object. In the above specification we can change ``scheme='turbo'`` into ``scheme=alt.SchemeParams('turbo', count=2)`` to manually specify usage of 2 classes for the scheme within the scale. - To define custom colors for each class, one should specify the ``domain`` and ``range``. Where the ``range`` contains ``+1`` values than the classes specified in the ``domain``. For example: ``alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])``. ``blue`` is the class for all values below ``0.05``, ``white`` for all values between ``0.05`` and ``0.20`` and ``red`` for all values above ``0.20``. -- The natural breaks method will determine the optimal class breaks given the required number of classes. But how many classes should one pick? One can investigate usage of goodness of variance fit (GVF), aka Jenks optimization method, to determine this. +- The natural breaks method will determine the optimal class breaks given the required number of classes, but how many classes should you pick? One can investigate usage of goodness of variance fit (GVF), aka Jenks optimization method, to determine this. Repeat a Map @@ -505,14 +487,14 @@ The :class:`RepeatChart` pattern, accessible via the :meth:`Chart.repeat` method provides a convenient interface for a particular type of horizontal or vertical concatenation of a multi-dimensional dataset. -In the following example we have a dataset referenced as `source` from which we use -three columns defining the `population`, `engineers` and `hurricanes` of each US state. +In the following example we have a dataset referenced as ``source`` from which we use +three columns defining the ``population``, ``engineers`` and ``hurricanes`` of each US state. -The `states` is defined by making use of :func:`topo_feature` using `url` and `feature` +The ``states`` is defined by making use of :func:`topo_feature` using ``url`` and ``feature`` as parameters. This is a convenience function for extracting features from a topojson url. -These variables we provide as list in the `.repeat()` operator, which we refer to within -the color encoding as `alt.repeat('row')` +These variables we provide as list in the ``.repeat()`` operator, which we refer to within +the color encoding as ``alt.repeat('row')`` .. altair-plot:: @@ -540,7 +522,7 @@ Facet a Map ~~~~~~~~~~~ The :class:`FacetChart` pattern, accessible via the :meth:`Chart.facet` method provides a convenient interface for a particular type of horizontal or vertical -concatenation of a dataset where one field contain multiple `variables`. +concatenation of a dataset where one field contain multiple ``variables``. Unfortunately, the following open issue https://github.com/altair-viz/altair/issues/2369 will make the following not work for geographic visualization: @@ -585,7 +567,7 @@ Often a map does not come alone, but is used in combination with another chart. Here we provide an example of an interactive visualization of a bar chart and a map. The data shows the states of the US in combination with a bar chart showing the 15 most -populous states. +populous states. Using an ``alt.selection_point()`` we define a selection parameter that connects to our left-mouseclick. .. altair-plot:: From d00f258aa34d3cd6dd0bf114ebdf4bf2e1b87745 Mon Sep 17 00:00:00 2001 From: mattijn Date: Wed, 2 Nov 2022 14:12:10 +0100 Subject: [PATCH 08/24] enhance styling --- doc/user_guide/marks/geoshape.rst | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index e34a3fd7d..858b85887 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -70,7 +70,7 @@ The following examples applies these approaches to focus on continental Africa: alt.Chart(gdf_ne).mark_geoshape().project( type='equalEarth', scale=200, - translate=[160, 160, 0] # lon, lat, rotation + translate=[160, 160] # lon, lat ) 3. Specify ``fit`` (extent) within the ``project`` method & ``clip=True`` in the mark properties: @@ -288,7 +288,8 @@ Chloropleth Classification Chloropleth maps provide an easy way to visualize how a variable varies across a geographic area or show the level of variability within a region. -We first define a utility function ``classify()`` that we will use to showcase different approaches to make a chloropleth map: +We first define a utility function ``classify()`` that we will use to showcase different approaches to make a chloropleth map. +We apply it to define a chloropleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. .. altair-plot:: @@ -302,8 +303,8 @@ We first define a utility function ``classify()`` that we will use to showcase d width=400 height=300 else: - width=200 - height=150 + width=180 + height=130 # us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') # us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') @@ -364,12 +365,7 @@ We first define a utility function ``classify()`` that we will use to showcase d return (distrib_geoshape + states_geoshape) & distrib_square - -Take for example the following example where we define a cholorpleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. - -.. altair-plot:: - - classify('linear', size='default') + classify('linear', size='default') We visualize the unemployment ``rate`` in percentage of 2018 with a ``linear`` scale range @@ -537,8 +533,8 @@ will make the following not work for geographic visualization: color=alt.Color('value:Q'), facet=alt.Facet('variable:N', columns=3) ).properties( - width=200, - height=200 + width=180, + height=130 ).resolve_scale('independent') For now, the following workaround can be adopted to facet a map, manually filter the @@ -551,9 +547,11 @@ data in pandas, and create a small multiples chart via concatenation. For exampl alt.Chart(gdf_comb[gdf_comb.variable == var], title=var) .mark_geoshape() .encode( - color="value:Q", + color=alt.Color( + "value:Q", legend=alt.Legend(orient="bottom", direction="horizontal") + ) ) - .properties(width=200) + .properties(width=180, height=130) for var in gdf_comb.variable.unique() ), columns=3 From d29bddfb10774b826fbdcba949c75f4de3549369 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:44:15 +0100 Subject: [PATCH 09/24] Update doc/user_guide/marks/index.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/index.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/user_guide/marks/index.rst b/doc/user_guide/marks/index.rst index 54973ca5a..e10ad490d 100644 --- a/doc/user_guide/marks/index.rst +++ b/doc/user_guide/marks/index.rst @@ -56,4 +56,8 @@ associated :class:`MarkDef` instance, which supports the following attributes: .. altair-object-table:: altair.MarkDef .. toctree:: - :hidden: \ No newline at end of file + :hidden: + + arc + area + geoshape \ No newline at end of file From 93e0dc41c9853c7edacf6fdbe3e8ad108801e5a1 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:44:27 +0100 Subject: [PATCH 10/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 858b85887..460f591db 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -4,7 +4,7 @@ Geoshape ~~~~~~~~~~~~~ -The ``mark_geoshape`` represents an arbitrary shapes whose geometry is determined by specified spatial data. +``mark_geoshape`` represents an arbitrary shapes whose geometry is determined by specified spatial data. Basic Map ~~~~~~~~~ From cbf8be131553ebccffcaa087dea1a7f7f70d62ff Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:44:42 +0100 Subject: [PATCH 11/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 460f591db..e450eb8a4 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -8,7 +8,7 @@ Geoshape Basic Map ~~~~~~~~~ -Its most convenient to use a ``GeoDataFrame`` as input. Here we load the Natural Earth dataset and create a basic map using the ``mark_geoshape``: +Altair can work with many different geographical data formats, including geojson and topojson files. Often, the most convenient input format to use is a ``GeoDataFrame``. Here we load the Natural Earth dataset and create a basic map using ``mark_geoshape``: .. altair-plot:: From cd1b613f8185624a88659ebf2b4197e6303566e5 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:52:19 +0100 Subject: [PATCH 12/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index e450eb8a4..a433bb09c 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -49,9 +49,7 @@ The following examples applies these approaches to focus on continental Africa: gdf_sel = gdf_ne[gdf_ne.continent == 'Africa'] - alt.Chart(gdf_sel).mark_geoshape().project( - type='equalEarth' - ) + alt.Chart(gdf_sel).mark_geoshape() 2. Filter the source data using a ``transform_filter``: From c6fd5e572565b0ed852a063e0da0001220ea7bb4 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:52:44 +0100 Subject: [PATCH 13/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index a433bb09c..6588c4f83 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -55,9 +55,7 @@ The following examples applies these approaches to focus on continental Africa: .. altair-plot:: - alt.Chart(gdf_ne).mark_geoshape().project( - type='equalEarth' - ).transform_filter( + alt.Chart(gdf_ne).mark_geoshape().transform_filter( alt.datum.continent == 'Africa' ) From a06e798be4fe0330219b7e7f760d879797339438 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:53:41 +0100 Subject: [PATCH 14/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 6588c4f83..6e8ca27ee 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -170,7 +170,7 @@ We first assign the centroids of Polygons as Point geometry and plot these: .. altair-plot:: gdf_centroid = gpd.GeoDataFrame( - data=gdf_sel.drop('geometry', axis=1), + data=gdf_sel.copy(), # .copy() to prevent changing the original `gdf_sel` variable geometry=gdf_sel.geometry.centroid ) From da27e86e7408cc1f45b05bee2f0ddaf8d19c66ca Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 15:55:13 +0100 Subject: [PATCH 15/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 6e8ca27ee..00eddf007 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -91,7 +91,7 @@ The following examples applies these approaches to focus on continental Africa: Cartesian coordinates ~~~~~~~~~~~~~~~~~~~~~ -The default projection of Altair is ``equalEarth``. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. +The default projection of Altair is ``equalEarth``, which accurately represents the areas of the world's landmasses relative each other. This default assumes that your geometries are in degrees and referenced by longitude and latitude values. Another widely used coordinate system for data visualization is the 2d cartesian coordinate system. This coordinate system does not take into account the curvature of the Earth. In the following example the input geometry is not projected and is instead rendered directly in raw coordinates using the ``identity`` projection type. We have to define the ``reflectY`` as well since Canvas and SVG treats positive ``y`` as pointing down. From 31271caaf2736e4b032ab0046889f671383b16fa Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:07:59 +0100 Subject: [PATCH 16/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 00eddf007..dd58d4e67 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -230,7 +230,18 @@ Altair also contains expressions related to geographical features. We can for ex (basemap + bubbles).project( type='identity', reflectY=True ) +Choropleths +~~~~~~~~~ + +An alternative to showing the population sizes as bubbles, is to create a "Choropleth" map. These are geographical heatmaps where the color or each region are mapped to the values of a column in the dataframe. + +.. altair-plot:: + + alt.Chart(gdf_sel).mark_geoshape().encode( + color='pop_est' + ) +When we create choropleth maps, we need to be careful, because although the color changes according to the value of the column we are interested in, the size is tied to the area of each country and we might miss interesting values in small countries just because we can't easily see them on the map (e.g. if we were to visualize population density). Lookup datasets ~~~~~~~~~~~~~~~ Sometimes your data is separated in two datasets. One ``DataFrame`` with the data and one ``GeoDataFrame`` with the geometries. From b636003ec0ab4dae938d005ef7f7b72f7e356494 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:09:33 +0100 Subject: [PATCH 17/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index dd58d4e67..9f7da9ee0 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -292,9 +292,7 @@ Here we lookup the geometries through the fields ``geometry`` and ``type`` from Chloropleth Classification ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Chloropleth maps provide an easy way to visualize how a variable varies across a -geographic area or show the level of variability within a region. - +In addition to displaying a continuous quantitative variable, choropleths can also be used to show discrete levels of a variable. While we should generally be careful to not create artificial groups when discretizing a continuous variable, it can be very useful when we have natural cutoff levels of a variable that we want to showcase clearly. We first define a utility function ``classify()`` that we will use to showcase different approaches to make a chloropleth map. We apply it to define a chloropleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. From c3d0e1f73d379e1b3e9dcf5b98ea22564cf5a0fc Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:11:17 +0100 Subject: [PATCH 18/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 9f7da9ee0..2a3fd63b6 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -321,9 +321,9 @@ We apply it to define a chloropleth map of the unemployment statistics of 2018 o title=scale_type if 'threshold' in scale_type: - scale = alt.Scale(type=scale_type, domain=breaks, scheme='turbo') + scale = alt.Scale(type=scale_type, domain=breaks, scheme='inferno') else: - scale = alt.Scale(type=scale_type, nice=nice, scheme='turbo') + scale = alt.Scale(type=scale_type, nice=nice, scheme='inferno') fill = alt.Fill( 'rate:Q', From d4a0a6b5388e54c770c45b53dd5cc6a4adf3ccb3 Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:11:31 +0100 Subject: [PATCH 19/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 2a3fd63b6..4eabbcf37 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -438,7 +438,7 @@ And applied in our utility function: The definition above will create 3 classes. One class with values below `0.05`, one class with values from `0.05` to `0.20` and one class with values higher than `0.20`. -So which method provides the optimal data classification for chloropleth maps? As +So which method provides the optimal data classification for choropleth maps? As usual, it depends. There is another popular method that aid in determining class breaks. From 4209eb19a73feab8493282eb402eeebad091b13f Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:11:58 +0100 Subject: [PATCH 20/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 4eabbcf37..6f3ac2353 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -585,9 +585,9 @@ populous states. Using an ``alt.selection_point()`` we define a selection parame # define a pointer selection click_state = alt.selection_point(fields=['state']) - # create a chloropleth map using a lookup transform + # create a choropleth map using a lookup transform # define a condition on the opacity encoding depending on the selection - chloropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( + choropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( lookup='id', from_=alt.LookupData(us_population, 'id', ['population', 'state']) ).encode( From de503384ba01d88c18af880b122053541280c68e Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:12:18 +0100 Subject: [PATCH 21/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 6f3ac2353..d2f0a891c 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -556,6 +556,7 @@ data in pandas, and create a small multiples chart via concatenation. For exampl "value:Q", legend=alt.Legend(orient="bottom", direction="horizontal") ) ) + .project('albersUsa') .properties(width=180, height=130) for var in gdf_comb.variable.unique() ), From 86124dad55039b0852cc4d10633bb5939311408e Mon Sep 17 00:00:00 2001 From: Mattijn van Hoek Date: Sat, 5 Nov 2022 16:12:33 +0100 Subject: [PATCH 22/24] Update doc/user_guide/marks/geoshape.rst Co-authored-by: Joel Ostblom --- doc/user_guide/marks/geoshape.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index d2f0a891c..74ac06116 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -609,7 +609,7 @@ populous states. Using an ``alt.selection_point()`` we define a selection parame ).add_params(click_state) - chloropleth & bars + choropleth & bars The interaction is two-directional. If you click (shift-click for multi-selection) on a geometry or bar the selection receive an ``opacity`` of ``1`` and the remaining an ``opacity`` of ``0.2``. From e34b4e2981e8c03599073f7e31f3da037bd9dab7 Mon Sep 17 00:00:00 2001 From: mattijn Date: Sun, 6 Nov 2022 00:00:56 +0100 Subject: [PATCH 23/24] add geoshape to toc --- doc/user_guide/marks/index.rst | 56 +++++++++++++++++++++------------- 1 file changed, 35 insertions(+), 21 deletions(-) diff --git a/doc/user_guide/marks/index.rst b/doc/user_guide/marks/index.rst index e10ad490d..a45522d53 100644 --- a/doc/user_guide/marks/index.rst +++ b/doc/user_guide/marks/index.rst @@ -19,29 +19,29 @@ Mark Method ========================================= ========================================= ================================================================================ :ref:`user-guide-arc-marks` :meth:`~Chart.mark_arc` A pie chart. :ref:`user-guide-area-marks` :meth:`~Chart.mark_area` A filled area plot. -bar :meth:`~Chart.mark_bar` A bar plot. -circle :meth:`~Chart.mark_circle` A scatter plot with filled circles. -geoshape :meth:`~Chart.mark_geoshape` Visualization containing spatial data -image :meth:`~Chart.mark_image` A scatter plot with image markers. -line :meth:`~Chart.mark_line` A line plot. -point :meth:`~Chart.mark_point` A scatter plot with configurable point shapes. -rect :meth:`~Chart.mark_rect` A filled rectangle, used for heatmaps -rule :meth:`~Chart.mark_rule` A vertical or horizontal line spanning the axis. -square :meth:`~Chart.mark_square` A scatter plot with filled squares. -text :meth:`~Chart.mark_text` A scatter plot with points represented by text. -tick :meth:`~Chart.mark_tick` A vertical or horizontal tick mark. -trail :meth:`~Chart.mark_trail` A line with variable widths. +:ref:`user-guide-bar-marks` :meth:`~Chart.mark_bar` A bar plot. +:ref:`user-guide-circle-marks` :meth:`~Chart.mark_circle` A scatter plot with filled circles. +:ref:`user-guide-geoshape-marks` :meth:`~Chart.mark_geoshape` Visualization containing spatial data +:ref:`user-guide-image-marks` :meth:`~Chart.mark_image` A scatter plot with image markers. +:ref:`user-guide-line-marks` :meth:`~Chart.mark_line` A line plot. +:ref:`user-guide-point-marks` :meth:`~Chart.mark_point` A scatter plot with configurable point shapes. +:ref:`user-guide-rect-marks` :meth:`~Chart.mark_rect` A filled rectangle, used for heatmaps +:ref:`user-guide-rule-marks` :meth:`~Chart.mark_rule` A vertical or horizontal line spanning the axis. +:ref:`user-guide-square-marks` :meth:`~Chart.mark_square` A scatter plot with filled squares. +:ref:`user-guide-text-marks` :meth:`~Chart.mark_text` A scatter plot with points represented by text. +:ref:`user-guide-tick-marks` :meth:`~Chart.mark_tick` A vertical or horizontal tick mark. +:ref:`user-guide-trail-marks` :meth:`~Chart.mark_trail` A line with variable widths. ========================================= ========================================= ================================================================================ In addition, Altair provides the following compound marks: -========== ============================== ================================ ================================== -Mark Name Method Description Example -========== ============================== ================================ ================================== -box plot :meth:`~Chart.mark_boxplot` A box plot. :ref:`gallery_boxplot` -error band :meth:`~Chart.mark_errorband` A continuous band around a line. :ref:`gallery_line_with_ci` -error bar :meth:`~Chart.mark_errorbar` An errorbar around a point. :ref:`gallery_errorbars_with_ci` -========== ============================== ================================ ================================== +========================================= ============================== ================================ ================================== +Mark Name Method Description Example +========================================= ============================== ================================ ================================== +:ref:`user-guide-boxplot-marks` :meth:`~Chart.mark_boxplot` A box plot. :ref:`gallery_boxplot` +:ref:`user-guide-errorband-marks` :meth:`~Chart.mark_errorband` A continuous band around a line. :ref:`gallery_line_with_ci` +:ref:`user-guide-errorbar-marks` :meth:`~Chart.mark_errorbar` An errorbar around a point. :ref:`gallery_errorbars_with_ci` +========================================= ============================== ================================ ================================== In Altair, marks can be most conveniently specified by the ``mark_*`` methods of the Chart object, which take optional keyword arguments that are passed to @@ -57,7 +57,21 @@ associated :class:`MarkDef` instance, which supports the following attributes: .. toctree:: :hidden: - + arc area - geoshape \ No newline at end of file + bar + boxplot + circle + errorband + errorbar + geoshape + image + line + point + rect + rule + square + text + tick + trail \ No newline at end of file From fbd6a9da7268b92ec9f486486ba35e40cdb2e11a Mon Sep 17 00:00:00 2001 From: mattijn Date: Sun, 6 Nov 2022 00:01:33 +0100 Subject: [PATCH 24/24] simplify and improve docs --- doc/user_guide/marks/geoshape.rst | 309 ++++++++++++------------------ 1 file changed, 123 insertions(+), 186 deletions(-) diff --git a/doc/user_guide/marks/geoshape.rst b/doc/user_guide/marks/geoshape.rst index 74ac06116..cb47e7516 100644 --- a/doc/user_guide/marks/geoshape.rst +++ b/doc/user_guide/marks/geoshape.rst @@ -21,14 +21,14 @@ Altair can work with many different geographical data formats, including geojson alt.Chart(gdf_ne).mark_geoshape() -In the example above, Altair applies a default blue ``fill`` color and uses a default map projection (``equalEarth``). We can customize the colors and boundary stroke widths using standard mark properties. Using the ``project`` method we can also define the map projection manually: +In the example above, Altair applies a default blue ``fill`` color and uses a default map projection (``equalEarth``). We can customize the colors and boundary stroke widths using standard mark properties. Using the ``project`` method we can also define a custom map projection manually: .. altair-plot:: alt.Chart(gdf_ne).mark_geoshape( fill='lightgrey', stroke='white', strokeWidth=0.5 ).project( - type='equalEarth' + type='albers' ) Focus & Filtering @@ -64,7 +64,6 @@ The following examples applies these approaches to focus on continental Africa: .. altair-plot:: alt.Chart(gdf_ne).mark_geoshape().project( - type='equalEarth', scale=200, translate=[160, 160] # lon, lat ) @@ -85,7 +84,6 @@ The following examples applies these approaches to focus on continental Africa: extent_roi_geojson = [mapping(extent_roi)] alt.Chart(gdf_ne).mark_geoshape(clip=True).project( - type='equalEarth', fit=extent_roi_geojson ) @@ -181,34 +179,11 @@ Caveat: To use the ``size`` encoding for the Points you will need to use the ``m .. altair-plot:: - gdf_centroid['lon'] = gdf_centroid['geometry'].x - gdf_centroid['lat'] = gdf_centroid['geometry'].y + gdf_centroid["lon"] = gdf_centroid.geometry.x + gdf_centroid["lat"] = gdf_centroid.geometry.y alt.Chart(gdf_centroid).mark_circle().encode( - longitude='lon:Q', - latitude='lat:Q', - size="pop_est:Q" - ) - -You could skip the extra assignment to the ``lon`` and ``lat`` column in the GeoDataFrame and use the coordinates directly. We combine the chart with a basemap to bring some perspective to the points: - -.. altair-plot:: - - basemap = alt.Chart(gdf_sel).mark_geoshape( - fill='lightgray', stroke='white', strokeWidth=0.5 - ) - - bubbles = alt.Chart(gdf_centroid).mark_circle( - stroke='black' - ).encode( - longitude='geometry.coordinates[0]:Q', - latitude='geometry.coordinates[1]:Q', - size="pop_est:Q" - ) - - (basemap + bubbles).project( - type='identity', - reflectY=True + longitude="lon:Q", latitude="lat:Q", size="pop_est:Q" ) Altair also contains expressions related to geographical features. We can for example define the ``centroids`` using a ``geoCentroid`` expression: @@ -230,6 +205,7 @@ Altair also contains expressions related to geographical features. We can for ex (basemap + bubbles).project( type='identity', reflectY=True ) + Choropleths ~~~~~~~~~ @@ -242,6 +218,7 @@ An alternative to showing the population sizes as bubbles, is to create a "Choro ) When we create choropleth maps, we need to be careful, because although the color changes according to the value of the column we are interested in, the size is tied to the area of each country and we might miss interesting values in small countries just because we can't easily see them on the map (e.g. if we were to visualize population density). + Lookup datasets ~~~~~~~~~~~~~~~ Sometimes your data is separated in two datasets. One ``DataFrame`` with the data and one ``GeoDataFrame`` with the geometries. @@ -290,11 +267,11 @@ Here we lookup the geometries through the fields ``geometry`` and ``type`` from ) -Chloropleth Classification +Choropleth Classification ~~~~~~~~~~~~~~~~~~~~~~~~~~ In addition to displaying a continuous quantitative variable, choropleths can also be used to show discrete levels of a variable. While we should generally be careful to not create artificial groups when discretizing a continuous variable, it can be very useful when we have natural cutoff levels of a variable that we want to showcase clearly. -We first define a utility function ``classify()`` that we will use to showcase different approaches to make a chloropleth map. -We apply it to define a chloropleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. +We first define a utility function ``classify()`` that we will use to showcase different approaches to make a choropleth map. +We apply it to define a choropleth map of the unemployment statistics of 2018 of US counties using a ``linear`` scale. .. altair-plot:: @@ -302,80 +279,46 @@ We apply it to define a chloropleth map of the unemployment statistics of 2018 o from vega_datasets import data import geopandas as gpd - def classify(scale_type, breaks=None, nice=False, title=None, size='small'): + def classify(type, breaks=None, nice=False, title=None): + # define data + us_counties = alt.topo_feature(data.us_10m.url, "counties") + us_unemp = data.unemployment.url - if size =='default': - width=400 - height=300 + # define choropleth scale + if "threshold" in scale_type: + scale = alt.Scale(type=type, domain=breaks, scheme="inferno") else: - width=180 - height=130 - - # us_counties = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='counties') - # us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') - us_counties = alt.topo_feature(data.us_10m.url, 'counties') - us_states = alt.topo_feature(data.us_10m.url, 'states') - us_unemp = data.unemployment.url - + scale = alt.Scale(type=type, nice=nice, scheme="inferno") + + # define title if title is None: - title=scale_type - - if 'threshold' in scale_type: - scale = alt.Scale(type=scale_type, domain=breaks, scheme='inferno') - else: - scale = alt.Scale(type=scale_type, nice=nice, scheme='inferno') - - fill = alt.Fill( - 'rate:Q', - scale=scale, - legend=alt.Legend(direction='horizontal', orient='bottom', format='.1%') - ) - - distrib_square = alt.Chart( - us_unemp, - height=20, - width=width - ).mark_square( - size=3, - opacity=1 - ).encode( - x=alt.X('rate:Q', title=None, axis=alt.Axis(format='.0%')), - y=alt.Y('jitter:Q', title=None, axis=None), - fill=fill - ).transform_calculate( - jitter='random()' - ) - - distrib_geoshape = alt.Chart( - us_counties, - width=width, - height=height, - title=title - ).mark_geoshape().transform_lookup( - lookup='id', - from_=alt.LookupData(data=us_unemp, key='id', fields=['rate']) - ).encode( - fill=fill - ).project( - type='albersUsa' + title = type + + # define choropleth chart + choropleth = ( + alt.Chart(us_counties, title=title) + .mark_geoshape() + .transform_lookup( + lookup="id", from_=alt.LookupData(data=us_unemp, key="id", fields=["rate"]) + ) + .encode( + alt.Color( + "rate:Q", + scale=scale, + legend=alt.Legend( + direction="horizontal", orient="bottom", format=".1%" + ), + ) + ) + .project(type="albersUsa") ) - - states_geoshape = alt.Chart( - us_states, - width=width, - height=height - ).mark_geoshape(filled=False, stroke='white', strokeWidth=0.75).project( - type='albersUsa' - ) - - return (distrib_geoshape + states_geoshape) & distrib_square - classify('linear', size='default') + return choropleth + classify(scale_type='linear') We visualize the unemployment ``rate`` in percentage of 2018 with a ``linear`` scale range -using a ``mark_geoshape()`` to present the spatial patterns on a map and a ``jitter`` plot -(using ``mark_square()``) to visualize the distribution of the ``rate`` values. Each value/ +using a ``mark_geoshape()`` to present the spatial patterns on a map. Each value/ county has defined a `unique` color. This gives a bit of insight, but often we like to group the distribution into classes. @@ -384,7 +327,7 @@ each class get assigned the same color. Here we present a number of scale methods how Altair can be used: -- ``quantile``, this type will divide your dataset (`domain`) into intervals of similar sizes. Each class contains more or less the same number of values/geometries (equal counts). The scale definition will look as follow: +- ``quantile``, this type will divide your dataset (`domain`) into intervals of similar sizes. Each class contains more or less the same number of values/geometries (`equal counts`). The scale definition will look as follow: .. code:: python @@ -394,8 +337,7 @@ And applied in our utility function: .. altair-plot:: - classify('quantile', size='default') - + classify(type='quantile', title=['quantile', 'equal counts']) - ``quantize``, this type will divide the extent of your dataset (`range`) in equal intervals. Each class contains different number of values, but the step size is equal (`equal range`). The scale definition will look as follow: @@ -407,10 +349,10 @@ And applied in our utility function: .. altair-plot:: - classify('quantize', size='default') + classify(type='quantize', title=['quantile', 'equal range']) -The ``quantize`` method can also be used in combination with ``nice``. This will "nice" the domain before applying quantization. As such: +The ``quantize`` method can also be used in combination with ``nice``. This will `"nice"` the domain before applying quantization. As such: .. code:: python @@ -420,7 +362,7 @@ And applied in our utility function: .. altair-plot:: - classify('quantize', nice=True, size='default') + classify(type='quantize', nice=True, title=['quantize', 'equal range nice']) - ``threshold``, this type will divide your dataset in separate classes by manually specifying the cut values. Each class is separated by defined classes. The scale definition will look as follow: @@ -432,8 +374,7 @@ And applied in our utility function: .. altair-plot:: - classify('threshold', breaks=[0.05, 0.20], size='default') - + classify(type='threshold', breaks=[0.05, 0.20]) The definition above will create 3 classes. One class with values below `0.05`, one class with values from `0.05` to `0.20` and one class with values higher than `0.20`. @@ -443,7 +384,7 @@ usual, it depends. There is another popular method that aid in determining class breaks. This method will maximize the similarity of values in a class while maximizing the -distance between the classes (natural breaks). The method is also known as the +distance between the classes (`natural breaks`). The method is also known as the Fisher-Jenks algorithm and is similar to k-Means in 1D: - By using the external Python package ``jenskpy`` we can derive these `optimum` breaks @@ -457,31 +398,18 @@ as such: >>> jnb.inner_breaks_ [0.061, 0.088, 0.116, 0.161] -So when applying all these different classification schemes to the county unemployment -dataset, we get the following overview: +And applied in our utility function: .. altair-plot:: - alt.concat( - classify('linear'), - classify('quantile', title=['quantile','equal counts']), - classify('quantize', title=['quantize', 'equal range']), - classify('quantize', nice=True, title=['quantize', 'equal range nice']), - classify('threshold', breaks=[0.05, 0.20]), - classify('threshold', breaks=[0.061, 0.088, 0.116, 0.161], - title=['threshold Jenks','natural breaks'] - ), - columns=3 - ) - + classify(type='threshold', breaks=[0.061, 0.088, 0.116, 0.161], + title=['threshold Jenks','natural breaks']) Caveats: - For the type ``quantize`` and ``quantile`` scales we observe that the default number of classes is 5. You can change the number of classes using a ``SchemeParams()`` object. In the above specification we can change ``scheme='turbo'`` into ``scheme=alt.SchemeParams('turbo', count=2)`` to manually specify usage of 2 classes for the scheme within the scale. -- To define custom colors for each class, one should specify the ``domain`` and ``range``. Where the ``range`` contains ``+1`` values than the classes specified in the ``domain``. For example: ``alt.Scale(type='threshold', domain=[0.05, 0.20], range=['blue','white','red'])``. ``blue`` is the class for all values below ``0.05``, ``white`` for all values between ``0.05`` and ``0.20`` and ``red`` for all values above ``0.20``. - The natural breaks method will determine the optimal class breaks given the required number of classes, but how many classes should you pick? One can investigate usage of goodness of variance fit (GVF), aka Jenks optimization method, to determine this. - Repeat a Map ~~~~~~~~~~~~ The :class:`RepeatChart` pattern, accessible via the :meth:`Chart.repeat` method @@ -563,8 +491,6 @@ data in pandas, and create a small multiples chart via concatenation. For exampl columns=3 ).resolve_scale(color="independent") - - Interaction ~~~~~~~~~~~ Often a map does not come alone, but is used in combination with another chart. @@ -580,36 +506,44 @@ populous states. Using an ``alt.selection_point()`` we define a selection parame import geopandas as gpd # load the data - us_states = gpd.read_file(data.us_10m.url, driver='TopoJSON', layer='states') - us_population = data.population_engineers_hurricanes()[['state', 'id', 'population']] + us_states = gpd.read_file(data.us_10m.url, driver="TopoJSON", layer="states") + us_population = data.population_engineers_hurricanes()[["state", "id", "population"]] # define a pointer selection - click_state = alt.selection_point(fields=['state']) + click_state = alt.selection_point(fields=["state"]) - # create a choropleth map using a lookup transform + # create a choropleth map using a lookup transform # define a condition on the opacity encoding depending on the selection - choropleth = alt.Chart(us_states).mark_geoshape().transform_lookup( - lookup='id', - from_=alt.LookupData(us_population, 'id', ['population', 'state']) - ).encode( - color='population:Q', - opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), - tooltip=['state:N', 'population:Q'] - ).project(type='albersUsa').add_params(click_state) + choropleth = ( + alt.Chart(us_states) + .mark_geoshape() + .transform_lookup( + lookup="id", from_=alt.LookupData(us_population, "id", ["population", "state"]) + ) + .encode( + color="population:Q", + opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), + tooltip=["state:N", "population:Q"], + ) + .project(type="albersUsa") + ) # create a bar chart with a similar condition on the opacity encoding. - bars = alt.Chart( - us_population.nlargest(15, 'population'), - title='Top 15 states by population').mark_bar( - ).encode( - x='population', - opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), - color='population', - y=alt.Y('state', sort='-x') - ).add_params(click_state) + bars = ( + alt.Chart( + us_population.nlargest(15, "population"), title="Top 15 states by population" + ) + .mark_bar() + .encode( + x="population", + opacity=alt.condition(click_state, alt.value(1), alt.value(0.2)), + color="population", + y=alt.Y("state", sort="-x"), + ) + ) + (choropleth & bars).add_params(click_state) - choropleth & bars The interaction is two-directional. If you click (shift-click for multi-selection) on a geometry or bar the selection receive an ``opacity`` of ``1`` and the remaining an ``opacity`` of ``0.2``. @@ -617,8 +551,9 @@ Expression ~~~~~~~~~~ Altair expressions can be used within a geographical visualization. The following example visualize earthquakes on the globe using an ``orthographic`` projection. Where we can rotate -the earth on a single-axis. (``rotate0``). The utility function :func:sphere is adopted to -get a disk of the earth as background. +the earth on a single-axis. (``rotate0``). The utility function :func:`sphere` is adopted to +get a disk of the earth as background. The GeoDataFrame with the earthquakes has an ``XYZ``` point geometry, where each coordinate represent ``lon``, ``lat`` and ``depth`` respectively. +We use here an elegant way to access the nested point coordinates from the geometry column directly to draw circles. Using this approach we do not need to assign them to three separate columns first. .. altair-plot:: @@ -627,61 +562,63 @@ get a disk of the earth as background. import geopandas as gpd # load data - gdf_quakies = gpd.read_file(data.earthquakes.url, driver='GeoJSON') - gdf_world = gpd.read_file(data.world_110m.url, driver='TopoJSON') + gdf_quakies = gpd.read_file(data.earthquakes.url, driver="GeoJSON") + gdf_world = gpd.read_file(data.world_110m.url, driver="TopoJSON") # define parameters range0 = alt.binding_range(min=-180, max=180, step=5) - rotate0 = alt.param(value=120, bind=range0, name='param_rotate0') - rotate_param = alt.param(expr=f'[{rotate0.name}, 0, 0]') - hover = alt.selection_point(on='mouseover', clear='mouseout') + rotate0 = alt.param(value=120, bind=range0, name='rotate0') + rotate_param = alt.param(expr=f"[{rotate0.name}, 0, 0]") + hover = alt.selection_point(on="mouseover", clear="mouseout") # world disk sphere = alt.Chart(alt.sphere()).mark_geoshape( - fill='aliceblue', - stroke='black', - strokeWidth=1.5 + fill="aliceblue", stroke="black", strokeWidth=1.5 ) # countries as shapes world = alt.Chart(gdf_world).mark_geoshape( - fill='mintcream', - stroke='black', - strokeWidth=0.35 + fill="mintcream", stroke="black", strokeWidth=0.35 ) # earthquakes as circles with fill for depth and size for magnitude # the hover param is added on the mar_circle only - quakes = alt.Chart(gdf_quakies).mark_circle( - opacity=0.35, - tooltip=True, - stroke='black' - ).transform_calculate( - lon="datum.geometry.coordinates[0]", - lat="datum.geometry.coordinates[1]", - depth="datum.geometry.coordinates[2]" - ).transform_filter(f''' - ({rotate0.name} * -1) - 90 < datum.lon && datum.lon < ({rotate0.name} * -1) + 90 - ''' - ).encode( - longitude='lon:Q', - latitude='lat:Q', - strokeWidth=alt.condition(hover, alt.value(1, empty=False), alt.value(0)), - size=alt.Size('mag:Q', scale=alt.Scale(type='pow', range=[1,1000], domain=[0,6], exponent=4)), - fill=alt.Fill('depth:Q', scale=alt.Scale(scheme='lightorange', domain=[0,400])) - ).add_params(hover, rotate0) + quakes = ( + alt.Chart(gdf_quakies) + .mark_circle(opacity=0.35, tooltip=True, stroke="black") + .transform_calculate( + lon="datum.geometry.coordinates[0]", + lat="datum.geometry.coordinates[1]", + depth="datum.geometry.coordinates[2]", + ) + .transform_filter( + ((rotate0 * -1 - 90 < alt.datum.lon) & (alt.datum.lon < rotate0 * -1 + 90)).expr + ) + .encode( + longitude="lon:Q", + latitude="lat:Q", + strokeWidth=alt.condition(hover, alt.value(1, empty=False), alt.value(0)), + size=alt.Size( + "mag:Q", + scale=alt.Scale(type="pow", range=[1, 1000], domain=[0, 6], exponent=4), + ), + fill=alt.Fill( + "depth:Q", scale=alt.Scale(scheme="lightorange", domain=[0, 400]) + ), + ) + .add_params(hover, rotate0) + ) # define projection and add the rotation param for all layers - comb = alt.layer(sphere, world, quakes).project( - 'orthographic', - rotate=rotate_param - ).add_params(rotate_param) + comb = ( + alt.layer(sphere, world, quakes) + .project("orthographic", rotate=rotate_param) + .add_params(rotate_param) + ) comb The earthquakes are displayed using a ``mark_geoshape`` and filtered once out of sight of -the the visible part of the world. - -A hover highlighting is added to get more insight of each earthquake. +the visible part of the world. A hover highlighting is added to get more insight of each earthquake. Geoshape Options ~~~~~~~~~~~~~~~~