Visualization

Install the optional visualization package with pip install "fastmob[vis]". Its stable entry point is fastmob.vis; the wheel is named fastmob-vis and the module behind it is fastmob_vis. The generic chart constructors are exported by fastmob.vis. The charts for particular results (jump lengths, activities, mobility profiles, motifs, fitted laws and STVD) are in fastmob_vis.

Every constructor takes a pandas, Polars or other eager dataframe and the names of the columns to draw. Generic constructors return an immutable Chart; the result-specific functions return an EChartsFigure. Both draw themselves as the last expression of a notebook cell, and export to a web page, to JSON for a web application, or to a static SVG. For a walk-through that draws every chart, see Chart your results.

Generic charts from a table

API	Description	Example
`ecdf`	Draw the empirical cumulative distribution of a numeric column, optionally against a second result.	A distribution from one result
`bar`	Draw a categorical bar chart.	Bars, boxes, points and a heatmap from a table
`scatter`	Draw a scatter chart of two numeric columns.	Bars, boxes, points and a heatmap from a table
`heatmap`	Draw a heatmap from a long-form table of x, y and value columns.	Bars, boxes, points and a heatmap from a table
`boxplot`	Draw a box plot of a numeric column for each category.	Bars, boxes, points and a heatmap from a table
`map`	Draw polygons from a GeoJSON FeatureCollection as a map chart.	Maps, which are interactive only

Chart objects and export

API	Description	Example
`Chart`	Immutable, notebook-renderable chart specification.	Save and embed charts
`Chart.render`	Return the lower-level `EChartsFigure` with the same option and settings.	Save and embed charts
`Chart.to_dict`	Return a copy of the ECharts option, ready to send to a web page.
`Chart.to_html`	Write a standalone HTML page that draws the chart.	Save and embed charts
`Chart.to_json`	Write the ECharts option as a JSON file.	Save and embed charts
`Chart.to_svg`	Draw the chart as a static SVG picture.	Save and embed charts
`EChartsFigure`	Low-level notebook-renderable ECharts option.	Save and embed charts
`EChartsFigure.to_dict`	Return a copy of the ECharts option, ready to send to a web page.	Save and embed charts
`EChartsFigure.to_html`	Write a standalone HTML page that draws the chart.
`EChartsFigure.to_json`	Write the ECharts option as a JSON file.
`EChartsFigure.to_svg`	Draw the chart as a static SVG picture.
`get_resource_bundle`	Return the script and style tags that charts need, to include once in a page.	Save and embed charts

Distributions of results (ECDF)

API	Description	Example
`plot_jump_lengths_ecdf`	Compare two sets of jump lengths with ECDF curves.	Charts for one kind of result
`plot_radius_of_gyration_ecdf`	Compare two sets of radii of gyration with ECDF curves.	Charts for one kind of result
`plot_visits_frequency_ecdf`	Compare two sets of visit counts with ECDF curves.	Charts for one kind of result
`plot_trip_duration_ecdf`	Compare two sets of trip durations with ECDF curves.	Time spent and time between visits
`plot_dwell_time_ecdf`	Compare two sets of dwell times with ECDF curves.	Time spent and time between visits

Visits and activities

API	Description	Example
`plot_visit_purpose_distribution`	Draw the share of visits by purpose as a bar chart.	Visit purposes
`plot_visit_purpose_comparison`	Compare visit-purpose shares of several datasets as grouped bars.	Visit purposes
`plot_activity_transition_matrix`	Draw the activity-to-activity transition matrix as a heatmap.	Moving between activities
`plot_activity_transition_difference`	Draw the difference between two transition matrices as a signed heatmap.	Moving between activities
`plot_daily_activity_distribution`	Draw the daily activity distribution (DARD): the share of each activity by time of day.	Activities through the day
`plot_daily_activity_difference`	Draw the difference between two daily activity distributions as a signed heatmap.	Activities through the day

Mobility profiles and motifs

API	Description	Example
`plot_mobility_profiles`	Scatter intermittency against degree of return, coloured by mobility profile.	Mobility profiles
`plot_profile_metrics`	Draw box plots of mobility metrics for each mobility profile, one panel per metric.	Mobility profiles
`plot_motif_literature_comparison`	Compare motif distributions with the literature as grouped bars.	Daily motifs

Fitted mobility laws

API	Description	Example
`plot_truncated_powerlaw_fits`	Plot jump-length distributions with fitted truncated power laws.	Mobility laws and their fits
`plot_lognormal_fits`	Plot the distribution of daily visited locations with fitted log-normal curves.	Mobility laws and their fits
`plot_distance_frequency_law`	Plot the distance-frequency visitation law with fitted curves.	Mobility laws and their fits

Maps

API	Description	Example
`plot_stvd_comparison`	Map a spatio-temporal visitation difference (STVD) comparison on a Leaflet basemap.	Maps, which are interactive only

Choosing the output

Pass display="svg" to any constructor to show a static picture in notebooks that do not run JavaScript (documentation, some viewers). The default display="html" is interactive. Maps (map, plot_stvd_comparison) are interactive only. To put several charts on one page, write the libraries once with get_resource_bundle and make the charts with bundle_libs=False.

Palettes

palette takes the name of one of four built-in palettes, or a mapping with the same keys (bg, grid, axis, observed, synthetic, syn2, syn3, baseline, band). The first series is drawn in observed, the second in synthetic, and further series in syn2, syn3 and baseline. fastmob.vis.PALETTES holds them.

Palette	Background	Observed	Synthetic	Third	Fourth	Baseline
`warm` (default)	`#fbf8f1`	`#14110d`	`#c8533a`	`#7a8c5a`	`#3d6a8a`	`#a39c8e`
`ink`	`#fbf8f1`	`#14110d`	`#5a544a`	`#7a7468`	`#403b34`	`#bfb8a8`
`terracotta`	`#fbf8f1`	`#3a1e15`	`#c8533a`	`#e08a4a`	`#7a3325`	`#b89a8e`
`forest`	`#f4efe3`	`#1e2a1a`	`#4e7a3d`	`#8a9a4a`	`#2d4a3e`	`#a39c8e`

Motif reference data

fastmob.vis.LITERATURE_MOTIF_PERCENTAGES maps the ordinal (1 to 17) of each daily motif of the literature to its percentage of person-days, and fastmob.vis.LITERATURE_TO_FASTMOB_MOTIF_ID maps the same ordinal to the packed integer id that motif_distribution uses. They are what plot_motif_literature_comparison compares against.

from fastmob.vis import LITERATURE_MOTIF_PERCENTAGES, LITERATURE_TO_FASTMOB_MOTIF_ID

The former Folium and Matplotlib plotting API was removed when fastmob-vis became a separate package. Use the charts below or a dedicated GIS renderer for maps with basemaps.

`ecdf(data, *, value_col, second=None, labels=('first', 'second'), title='Empirical cumulative distribution', x_label=None, x_unit='', cdf_cutoff=0.98, palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

Draw the empirical cumulative distribution of a numeric column, optionally against a second result.

The column may hold one number per row or one list of numbers per row (as jump_lengths returns); lists are flattened. Missing values are ignored. The curve stops at cdf_cutoff so that a long tail does not stretch the axis.

Parameters:

Name	Type	Description	Default
`data`	`dataframe`	Any pandas, Polars or other Narwhals-compatible eager dataframe.	required
`value_col`	`str`	Column with the values, scalar or list-valued.	required
`second`	`dataframe`	A second result with the same column, drawn as a dashed series for comparison.	`None`
`labels`	`sequence of two str`	Series names for the first and second result. Default `("first", "second")`.	`('first', 'second')`
`x_label`	`str`	X-axis label; defaults to `value_col`.	`None`
`x_unit`	`str`	Unit appended to the tooltip values. Default empty.	`''`
`cdf_cutoff`	`float`	Cumulative probability in (0, 1] at which each curve stops. Default 0.98.	`0.98`
`title`	`str`	Chart title. Default `"Empirical cumulative distribution"`.	`'Empirical cumulative distribution'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If `value_col` is missing or has no finite numeric value, `cdf_cutoff` is outside (0, 1], or `labels` does not have two entries when `second` is given.
`TypeError`	If `data` is not an eager dataframe.

See Also

bar : Categorical bars. plot_jump_lengths_ecdf : Two-array ECDF with jump-length defaults.

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.ecdf(pd.DataFrame({"jump_km": [0.8, 1.2, 2.4]}), value_col="jump_km", x_unit="km")
>>> chart.to_dict()["series"][0]["type"]
'line'

Worked example: A distribution from one result

`bar(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

Draw a categorical bar chart.

One bar per category; when series_col is given the bars are grouped, one series per value of that column. A category/series pair with no row is drawn as 0, and when it has several rows only the first is used, so aggregate first.

Parameters:

Name	Type	Description	Default
`data`	`dataframe`	Any pandas, Polars or other Narwhals-compatible eager dataframe.	required
`category_col`	`str`	Column with the category on the x-axis.	required
`value_col`	`str`	Numeric column with the bar height.	required
`series_col`	`str`	Column that splits the bars into groups. Default none: a single series named after `value_col`.	`None`
`title`	`str`	Chart title. Default empty.	`''`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If a named column is missing.

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.bar(pd.DataFrame({"who": ["a", "b"], "n": [3, 5]}), category_col="who", value_col="n")
>>> chart.to_dict()["xAxis"]["data"]
['a', 'b']

Worked example: Bars, boxes, points and a heatmap from a table

`scatter(data, *, x_col, y_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

Draw a scatter chart of two numeric columns.

Use series_col to overlay several groups, for example observed points and a fitted curve.

Parameters:

Name	Type	Description	Default
`data`	`dataframe`	Any pandas, Polars or other Narwhals-compatible eager dataframe.	required
`x_col`	`str`	Numeric column on the x-axis.	required
`y_col`	`str`	Numeric column on the y-axis.	required
`series_col`	`str`	Column that splits the points into coloured series. Default none.	`None`
`title`	`str`	Chart title. Default empty.	`''`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If a named column is missing.

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.scatter(pd.DataFrame({"x": [1, 2], "y": [2, 4]}), x_col="x", y_col="y")
>>> chart.to_dict()["series"][0]["data"]
[[1.0, 2.0], [2.0, 4.0]]

Worked example: Bars, boxes, points and a heatmap from a table

`heatmap(data, *, x_col, y_col, value_col, title='', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

Draw a heatmap from a long-form table of x, y and value columns.

One cell per row; the colour scale runs from 0 to the largest value. A pair with no row is left empty.

Parameters:

Name	Type	Description	Default
`data`	`dataframe`	Any pandas, Polars or other Narwhals-compatible eager dataframe.	required
`x_col`	`str`	Column with the horizontal category.	required
`y_col`	`str`	Column with the vertical category.	required
`value_col`	`str`	Numeric column that sets the colour.	required
`title`	`str`	Chart title. Default empty.	`''`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'520px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If a named column is missing.

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.heatmap(pd.DataFrame({"h": ["8", "9"], "who": ["a", "a"], "n": [1, 3]}), x_col="h", y_col="who", value_col="n")
>>> chart.to_dict()["series"][0]["data"]
[[0, 0, 1.0], [1, 0, 3.0]]

Worked example: Bars, boxes, points and a heatmap from a table

`boxplot(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

Draw a box plot of a numeric column for each category.

Each box spans the quartiles with the median inside and whiskers at the minimum and maximum. With series_col the boxes are grouped; a group with no rows is skipped.

Parameters:

Name	Type	Description	Default
`data`	`dataframe`	Any pandas, Polars or other Narwhals-compatible eager dataframe.	required
`category_col`	`str`	Column with the category on the x-axis.	required
`value_col`	`str`	Numeric column summarised by each box.	required
`series_col`	`str`	Column that splits each category into groups. Default none.	`None`
`title`	`str`	Chart title. Default empty.	`''`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If a named column is missing.

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.boxplot(pd.DataFrame({"who": ["a"] * 4, "d": [1, 2, 3, 4]}), category_col="who", value_col="d")
>>> chart.to_dict()["series"][0]["data"]
[[1.0, 1.75, 2.5, 3.25, 4.0]]

Worked example: Bars, boxes, points and a heatmap from a table

`map(geojson, *, title='Map', palette='warm', width='100%', height='600px', bundle_libs=True, display='html')`

Draw polygons from a GeoJSON FeatureCollection as a map chart.

No GIS library is needed. Maps are interactive only: to_svg and display="svg" raise ValueError for this chart.

Parameters:

Name	Type	Description	Default
`geojson`	`dict`	A GeoJSON object whose `type` is `"FeatureCollection"`.	required
`title`	`str`	Chart title. Default `"Map"`.	`'Map'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`'100%'`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'600px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`Chart`	An immutable chart specification; it draws itself in a notebook and can be exported.

Raises:

Type	Description
`ValueError`	If `geojson` is not a FeatureCollection.

Worked example: Maps, which are interactive only

`Chart` `dataclass`

Immutable, notebook-renderable chart specification.

Returned by ecdf, bar, scatter, heatmap, boxplot and map; you do not build one directly. As the last expression of a notebook cell it draws itself. to_dict returns the ECharts option for a web application, and to_html, to_json and to_svg write portable files. render returns the lower-level EChartsFigure.

Parameters:

Name	Type	Description	Default
`kind`	`str`	Chart type: `"ecdf"`, `"bar"`, `"scatter"`, `"heatmap"`, `"boxplot"` or `"map"`.	required
`width`	`str`	CSS sizes.	`'600px'`
`height`	`str`	CSS sizes.	`'420px'`
`background`	`str`	Background colour taken from the palette.	`'white'`
`bundle_libs`	`bool`	Whether the JavaScript is embedded in the chart.	`True`
`display`	`('html', 'svg')`	Notebook display mode.	`"html"`

Examples:

>>> from fastmob import vis
>>> import pandas as pd
>>> chart = vis.bar(pd.DataFrame({"who": ["a", "b"], "n": [3, 5]}), category_col="who", value_col="n")
>>> sorted(chart.to_dict())[:3]
['_meta', 'animation', 'backgroundColor']

`option` `property`

A copy of the ECharts option; changing it does not change the chart.

`render()`

Return the lower-level EChartsFigure with the same option and settings.

`to_dict()`

Return a copy of the ECharts option, ready to send to a web page.

Returns:

Type	Description
`dict`	The ECharts option, including a `_meta` entry with the chart type.

`to_html(filepath)`

Write a standalone HTML page that draws the chart.

The page embeds the JavaScript libraries, so it opens without a network connection (map tiles excepted).

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file.	required

Returns:

Type	Description
`Path`	The file written.

`to_json(filepath)`

Write the ECharts option as a JSON file.

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file.	required

Returns:

Type	Description
`Path`	The file written.

`to_svg(filepath=None)`

Draw the chart as a static SVG picture.

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file. When omitted the SVG text is returned.	`None`

Returns:

Type	Description
`str or Path`	The SVG text, or the file written.

Raises:

Type	Description
`ValueError`	For maps and STVD comparisons, which can only be drawn with JavaScript.

Worked example: Save and embed charts

`EChartsFigure` `dataclass`

Low-level notebook-renderable ECharts option.

Wraps a raw ECharts option dictionary. Most code uses Chart instead; Chart.render returns this class, and the domain plot helpers such as plot_jump_lengths_ecdf return it directly. It has the same exports as Chart: to_dict, to_json, to_html and to_svg.

Parameters:

Name	Type	Description	Default
`option`	`dict`	The ECharts option.	required
`width`	`str`	CSS width. Default `"600px"`.	`'600px'`
`height`	`str`	CSS height. Default `"420px"`.	`'420px'`
`background`	`str`	Page background colour. Default `"white"`.	`'white'`
`bundle_libs`	`bool`	Embed the JavaScript libraries. Default True.	`True`
`display`	`('html', 'svg')`	Notebook display mode. Default `"html"`.	`"html"`

Raises:

Type	Description
`TypeError`	If `option` is not a dictionary.
`ValueError`	If `display` is not `"html"` or `"svg"`.

`option` `property`

A copy of the ECharts option; changing it does not change the chart.

`option_json` `property`

The ECharts option as a JSON string.

`to_dict()`

Return a copy of the ECharts option, ready to send to a web page.

Returns:

Type	Description
`dict`	The ECharts option, including a `_meta` entry with the chart type.

`to_html(filepath)`

Write a standalone HTML page that draws the chart.

The page embeds the JavaScript libraries, so it opens without a network connection (map tiles excepted).

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file.	required

Returns:

Type	Description
`Path`	The file written.

`to_json(filepath)`

Write the ECharts option as a JSON file.

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file.	required

Returns:

Type	Description
`Path`	The file written.

`to_svg(filepath=None)`

Draw the chart as a static SVG picture.

Parameters:

Name	Type	Description	Default
`filepath`	`str or Path`	Destination file. When omitted the SVG text is returned.	`None`

Returns:

Type	Description
`str or Path`	The SVG text, or the file written.

Raises:

Type	Description
`ValueError`	For maps and STVD comparisons, which can only be drawn with JavaScript.

Worked example: Save and embed charts

`get_resource_bundle(*, echarts=True, leaflet=False)`

Return the script and style tags that charts need, to include once in a page.

Use this with bundle_libs=False on every chart of a page so that the large JavaScript libraries are written once instead of once per chart.

Parameters:

Name	Type	Description	Default
`echarts`	`bool`	Include ECharts. Default True.	`True`
`leaflet`	`bool`	Include Leaflet and its ECharts extension, needed by `plot_stvd_comparison`. Default False.	`False`

Returns:

Type	Description
`str`	HTML `<script>` and `<style>` tags to place in the page `<head>`.

Examples:

>>> from fastmob import vis
>>> vis.get_resource_bundle().startswith("<script>")
True

Worked example: Save and embed charts

`plot_jump_lengths_ecdf(left, right, labels=('A', 'B'), title='Jump length ECDF', palette='warm', cdf_cutoff=0.98, x_label='jump length', x_unit='km', width=600, *, bundle_libs=True, display='html')`

Compare two sets of jump lengths with ECDF curves.

Both arrays are drawn as empirical cumulative distribution functions on the same axes, the first solid and the second dashed. Use it to compare an observed result with a simulated one. Arrays are not sorted or cleaned beyond dropping nothing: pass finite numbers.

Parameters:

Name	Type	Description	Default
`left`	`array - like`	The two sets of jump lengths.	required
`right`	`array - like`	The two sets of jump lengths.	required
`labels`	`sequence of two str`	Series names. Default `("A", "B")`.	`('A', 'B')`
`title`	`str`	Chart title.	`'Jump length ECDF'`
`cdf_cutoff`	`float`	Cumulative probability at which each curve stops. Default 0.98.	`0.98`
`x_label`	`str`	X-axis label.	`'jump length'`
`x_unit`	`str`	Unit shown on the axis and tooltip (default `"km"`).	`'km'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The ECDF figure.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries.

See Also

fastmob.vis.ecdf : The dataframe-based ECDF.

Worked example: Charts for one kind of result

`plot_radius_of_gyration_ecdf(left, right, labels=('A', 'B'), title='Radius of gyration ECDF', palette='warm', cdf_cutoff=0.98, x_label='radius of gyration', x_unit='km', width=600, *, bundle_libs=True, display='html')`

Compare two sets of radii of gyration with ECDF curves.

Both arrays are drawn as empirical cumulative distribution functions on the same axes, the first solid and the second dashed. Use it to compare an observed result with a simulated one. Arrays are not sorted or cleaned beyond dropping nothing: pass finite numbers.

Parameters:

Name	Type	Description	Default
`left`	`array - like`	The two sets of radii of gyration.	required
`right`	`array - like`	The two sets of radii of gyration.	required
`labels`	`sequence of two str`	Series names. Default `("A", "B")`.	`('A', 'B')`
`title`	`str`	Chart title.	`'Radius of gyration ECDF'`
`cdf_cutoff`	`float`	Cumulative probability at which each curve stops. Default 0.98.	`0.98`
`x_label`	`str`	X-axis label.	`'radius of gyration'`
`x_unit`	`str`	Unit shown on the axis and tooltip (default `"km"`).	`'km'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The ECDF figure.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries.

See Also

fastmob.vis.ecdf : The dataframe-based ECDF.

Worked example: Charts for one kind of result

`plot_visits_frequency_ecdf(left, right, labels=('A', 'B'), title='Visits frequency ECDF', palette='warm', cdf_cutoff=0.98, x_label='number of visits', x_unit='', width=600, *, bundle_libs=True, display='html')`

Compare two sets of visit counts with ECDF curves.

Both arrays are drawn as empirical cumulative distribution functions on the same axes, the first solid and the second dashed. Use it to compare an observed result with a simulated one. Arrays are not sorted or cleaned beyond dropping nothing: pass finite numbers.

Parameters:

Name	Type	Description	Default
`left`	`array - like`	The two sets of visit counts.	required
`right`	`array - like`	The two sets of visit counts.	required
`labels`	`sequence of two str`	Series names. Default `("A", "B")`.	`('A', 'B')`
`title`	`str`	Chart title.	`'Visits frequency ECDF'`
`cdf_cutoff`	`float`	Cumulative probability at which each curve stops. Default 0.98.	`0.98`
`x_label`	`str`	X-axis label.	`'number of visits'`
`x_unit`	`str`	Unit shown on the axis and tooltip.	`''`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The ECDF figure.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries.

See Also

fastmob.vis.ecdf : The dataframe-based ECDF.

Worked example: Charts for one kind of result

`plot_trip_duration_ecdf(left, right, labels=('A', 'B'), title='Trip duration ECDF', palette='warm', cdf_cutoff=0.98, x_label='trip duration', x_unit='min', width=600, *, bundle_libs=True, display='html')`

Compare two sets of trip durations with ECDF curves.

Both arrays are drawn as empirical cumulative distribution functions on the same axes, the first solid and the second dashed. Use it to compare an observed result with a simulated one. Arrays are not sorted or cleaned beyond dropping nothing: pass finite numbers.

Parameters:

Name	Type	Description	Default
`left`	`array - like`	The two sets of trip durations.	required
`right`	`array - like`	The two sets of trip durations.	required
`labels`	`sequence of two str`	Series names. Default `("A", "B")`.	`('A', 'B')`
`title`	`str`	Chart title.	`'Trip duration ECDF'`
`cdf_cutoff`	`float`	Cumulative probability at which each curve stops. Default 0.98.	`0.98`
`x_label`	`str`	X-axis label.	`'trip duration'`
`x_unit`	`str`	Unit shown on the axis and tooltip (default `"min"`).	`'min'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The ECDF figure.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries.

See Also

fastmob.vis.ecdf : The dataframe-based ECDF.

Worked example: Time spent and time between visits

`plot_dwell_time_ecdf(left, right, labels=('A', 'B'), title='Dwell time ECDF', palette='warm', cdf_cutoff=0.98, x_label='dwell time', x_unit='min', width=600, *, bundle_libs=True, display='html')`

Compare two sets of dwell times with ECDF curves.

Both arrays are drawn as empirical cumulative distribution functions on the same axes, the first solid and the second dashed. Use it to compare an observed result with a simulated one. Arrays are not sorted or cleaned beyond dropping nothing: pass finite numbers.

Parameters:

Name	Type	Description	Default
`left`	`array - like`	The two sets of dwell times.	required
`right`	`array - like`	The two sets of dwell times.	required
`labels`	`sequence of two str`	Series names. Default `("A", "B")`.	`('A', 'B')`
`title`	`str`	Chart title.	`'Dwell time ECDF'`
`cdf_cutoff`	`float`	Cumulative probability at which each curve stops. Default 0.98.	`0.98`
`x_label`	`str`	X-axis label.	`'dwell time'`
`x_unit`	`str`	Unit shown on the axis and tooltip (default `"min"`).	`'min'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The ECDF figure.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries.

See Also

fastmob.vis.ecdf : The dataframe-based ECDF.

Worked example: Time spent and time between visits

`plot_visit_purpose_distribution(data, *, labels=None, title='Visit Purpose Distribution', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

Draw the share of visits by purpose as a bar chart.

The input is either raw visits (a table with an activity column, summarised by visit_purpose_distribution) or an already-summarised table with activity and percentage and/or count columns, or a tuple (labels, percentages[, counts]).

Parameters:

Name	Type	Description	Default
`data`	`dataframe or tuple`	Raw visits or a summarised distribution, as above.	required
`labels`	`sequence of str`	Replacement category names, one per category in order.	`None`
`title`	`str`	Chart title.	`'Visit Purpose Distribution'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The bar chart; bars are percentages.

Raises:

Type	Description
`ValueError`	If `labels` has a different length from the categories, or `data` has none of the accepted shapes.

Worked example: Visit purposes

`plot_visit_purpose_comparison(datasets, *, title='Visit Purpose Comparison', palette='warm', width=800, height='420px', bundle_libs=True, display='html')`

Compare visit-purpose shares of several datasets as grouped bars.

Categories are the union over the datasets, in order of first appearance; a dataset with no visits for a category shows 0.

Parameters:

Name	Type	Description	Default
`datasets`	`mapping`	Dataset name to data, each in a form accepted by `plot_visit_purpose_distribution`. Must not be empty.	required
`title`	`str`	Chart title.	`'Visit Purpose Comparison'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`800`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The grouped bar chart.

Raises:

Type	Description
`ValueError`	If `datasets` is empty or a dataset repeats a label.

Worked example: Visit purposes

`plot_activity_transition_matrix(matrix_or_visits, *, title='Activity Transition Matrix', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

Draw the activity-to-activity transition matrix as a heatmap.

Rows are the activity a visit comes from and columns the activity it goes to; cells are percentages. The input is raw visits (summarised by activity_transition_matrix), the output of that function, a labelled square dataframe or a (labels, matrix) tuple.

Parameters:

Name	Type	Description	Default
`matrix_or_visits`	`dataframe or tuple`	Raw visits or a transition matrix, as above.	required
`title`	`str`	Chart title.	`'Activity Transition Matrix'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'520px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The heatmap.

Raises:

Type	Description
`ValueError`	If the matrix is not square, does not match its labels, or contains infinite values.

Worked example: Moving between activities

`plot_activity_transition_difference(first, second, *, labels=('first', 'second'), title='Activity Transition Difference', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

Draw the difference between two transition matrices as a signed heatmap.

Each cell is the second matrix minus the first, in percentage points, on a scale symmetric around zero. Activities missing from one matrix count as 0 there.

Parameters:

Name	Type	Description	Default
`first`	`dataframe or tuple`	Two transition matrices, each in a form accepted by `plot_activity_transition_matrix`.	required
`second`	`dataframe or tuple`	Two transition matrices, each in a form accepted by `plot_activity_transition_matrix`.	required
`labels`	`sequence of two str`	Names of the two datasets, used in the legend. Default `("first", "second")`.	`('first', 'second')`
`title`	`str`	Chart title.	`'Activity Transition Difference'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'520px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The signed heatmap.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries or a matrix is invalid.

Worked example: Moving between activities

`plot_daily_activity_distribution(data, *, categories=None, n_bins=None, title='Daily Activity Distribution', palette='warm', width=900, height='420px', bundle_libs=True, display='html')`

Draw the daily activity distribution (DARD): the share of each activity by time of day.

Rows are activities and columns are time-of-day bins; each column sums to 100%. The input is raw visits (summarised by daily_activity_distribution), a matrix together with categories and n_bins, or a (matrix, categories, n_bins) tuple.

Parameters:

Name	Type	Description	Default
`data`	`(dataframe, array - like or tuple)`	Raw visits, a matrix, or a tuple, as above.	required
`categories`	`sequence of str`	Activity names for the matrix rows; needed with a bare matrix.	`None`
`n_bins`	`int`	Number of time-of-day bins; needed with a bare matrix.	`None`
`title`	`str`	Chart title.	`'Daily Activity Distribution'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`900`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The heatmap.

Raises:

Type	Description
`ValueError`	If the matrix shape does not match `categories` and `n_bins`, contains infinite values, or the data has none of the accepted shapes.

Worked example: Activities through the day

`plot_daily_activity_difference(first, second, *, categories=None, n_bins=None, labels=('first', 'second'), title='Daily Activity Difference', palette='warm', width=900, height='420px', bundle_libs=True, display='html')`

Draw the difference between two daily activity distributions as a signed heatmap.

Each cell is the second distribution minus the first, in percentage points. Both must use the same n_bins; activities missing from one count as 0 there.

Parameters:

Name	Type	Description	Default
`first`	`(dataframe, array - like or tuple)`	Two daily distributions, each in a form accepted by `plot_daily_activity_distribution`.	required
`second`	`(dataframe, array - like or tuple)`	Two daily distributions, each in a form accepted by `plot_daily_activity_distribution`.	required
`categories`	`sequence of str`	Activity names for bare matrices.	`None`
`n_bins`	`int`	Number of time-of-day bins for bare matrices.	`None`
`labels`	`sequence of two str`	Names of the two datasets. Default `("first", "second")`.	`('first', 'second')`
`title`	`str`	Chart title.	`'Daily Activity Difference'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`900`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The signed heatmap.

Raises:

Type	Description
`ValueError`	If the two datasets use a different `n_bins`, `labels` does not have two entries, or a matrix is invalid.

Worked example: Activities through the day

`plot_mobility_profiles(profiles, *, profile_col='agent_type', profile_colors=None, title='Mobility profiles', palette='warm', width=520, height='420px', bundle_libs=True, display='html')`

Scatter intermittency against degree of return, coloured by mobility profile.

Points are grouped into one series per profile (Routiner, Regular, Scouter, then any others), which makes the clustering visible. To compare datasets pass a mapping of dataset name to dataset: they are overlaid on the same axes, colour encodes the profile and symbol shape encodes the dataset.

Parameters:

Name	Type	Description	Default
`profiles`	`(dataframe, dict or mapping)`	A table with `degree_of_return`, `intermittency` and a profile-label column, or a mapping of dataset name to such a table.	required
`profile_col`	`str`	Column with the profile label. Default `"agent_type"`.	`'agent_type'`
`profile_colors`	`dict`	Profile name to colour; must cover every profile present. Default: colours from the palette.	`None`
`title`	`str`	Chart title.	`'Mobility profiles'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`520`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The scatter figure.

Raises:

Type	Description
`ValueError`	If the three columns differ in length, contain non-finite values, or `profile_colors` misses a profile.

Worked example: Mobility profiles

`plot_profile_metrics(datasets, *, metrics=('regularity', 'diversity', 'stationarity', 'entropy'), profile_col='agent_type', profile_order=('Scouter', 'Regular', 'Routiner'), title='Mobility profile metrics', palette='warm', width=900, height='640px', bundle_libs=True, display='html')`

Draw box plots of mobility metrics for each mobility profile, one panel per metric.

Each panel shows the profiles on the x-axis with one box per dataset, so a one-entry mapping describes a single dataset.

Parameters:

Name	Type	Description	Default
`datasets`	`mapping`	Dataset name to a table with a profile column and the metric columns. Must not be empty.	required
`metrics`	`sequence of str`	Metric columns to draw. Default `("regularity", "diversity", "stationarity", "entropy")`.	`('regularity', 'diversity', 'stationarity', 'entropy')`
`profile_col`	`str`	Column with the profile label. Default `"agent_type"`.	`'agent_type'`
`profile_order`	`sequence of str`	Order of the profiles on the x-axis. Default `("Scouter", "Regular", "Routiner")`.	`('Scouter', 'Regular', 'Routiner')`
`title`	`str`	Chart title.	`'Mobility profile metrics'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`900`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'640px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The grouped box-plot panels.

Raises:

Type	Description
`ValueError`	If `datasets` is empty, `metrics` is empty, or a column is missing.

Worked example: Mobility profiles

`plot_motif_literature_comparison(*, literature_df=None, reference_distribution=None, comparison_distribution=None, labels=('Reference', 'Simulation'), title='Motif Literature Comparison', palette='warm', width=900, height='560px', bundle_libs=True, display='html')`

Compare motif distributions with the literature as grouped bars.

The literature series (percentages of Schneider et al., 2013) is always drawn. Add an observed distribution, a simulated one or both.

Parameters:

Name	Type	Description	Default
`literature_df`	`dataframe`	Replacement literature distribution with `fastmob_motif_id` or `motif_id` and `percentage` or `count`. Default: the built-in literature values.	`None`
`reference_distribution`	`dataframe`	First distribution to compare, with `motif_id` and `percentage` or `count`.	`None`
`comparison_distribution`	`dataframe`	Second distribution to compare, same form.	`None`
`labels`	`sequence of two str`	Names of the two distributions. Default `("Reference", "Simulation")`.	`('Reference', 'Simulation')`
`title`	`str`	Chart title.	`'Motif Literature Comparison'`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`900`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'560px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The grouped bar chart.

Raises:

Type	Description
`ValueError`	If `labels` does not have two entries or a distribution lacks the required columns.

Worked example: Daily motifs

`plot_truncated_powerlaw_fits(*datasets, title='Truncated power-law fits', x_label='travel distance · km', y_label='P(Δr)', palette='warm', show_reference=True, reference_parameters=(1.5, 1.75, 400.0), reference_label='González reference', n_points=200, width=600, height='420px', bundle_libs=True, display='html')`

Plot jump-length distributions with fitted truncated power laws.

Each dataset is drawn as empirical points with a fitted curve, on log-log axes, optionally beside the reference curve of González et al. (2008). The fit itself is not computed here.

Parameters:

Name	Type	Description	Default
`*datasets`	`tuple`	One or more `(parameters, x_points, y_points, label)` tuples. `parameters` is `(c, r0, beta, kappa)` with `c`, `beta`, `kappa` > 0 and `r0` >= 0; the points are positive arrays of equal length.	`()`
`title`	`str`	Chart title.	`'Truncated power-law fits'`
`x_label`	`str`	Axis labels.	`'travel distance · km'`
`y_label`	`str`	Axis labels.	`'P(Δr)'`
`show_reference`	`bool`	Draw the González reference curve. Default True.	`True`
`reference_parameters`	`tuple of float`	`(r0, beta, kappa)` of the reference. Default `(1.5, 1.75, 400.0)`.	`(1.5, 1.75, 400.0)`
`reference_label`	`str`	Legend label of the reference.	`'González reference'`
`n_points`	`int`	Points per fitted curve, at least 2. Default 200.	`200`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The log-log figure.

Raises:

Type	Description
`ValueError`	If no dataset is given, a dataset is malformed, or a parameter is out of range.

Worked example: Mobility laws and their fits

`plot_lognormal_fits(*datasets, title='Daily visited locations', x_label='number of visited locations (N)', y_label='distribution f(N)', palette='warm', show_reference=True, reference_parameters=(1.0, 0.5), reference_label='Log-normal reference', n_points=200, width=600, height='420px', bundle_libs=True, display='html')`

Plot the distribution of daily visited locations with fitted log-normal curves.

Each dataset is drawn as empirical points with a log-normal curve, optionally beside a reference curve. The fit itself is not computed here.

Parameters:

Name	Type	Description	Default
`*datasets`	`tuple`	One or more `(x_points, y_points, mu, sigma, label)` tuples. `sigma` must be positive; the points are positive arrays of equal length.	`()`
`title`	`str`	Chart title.	`'Daily visited locations'`
`x_label`	`str`	Axis labels.	`'number of visited locations (N)'`
`y_label`	`str`	Axis labels.	`'distribution f(N)'`
`show_reference`	`bool`	Draw the reference curve. Default True.	`True`
`reference_parameters`	`tuple of float`	`(mu, sigma)` of the reference. Default `(1.0, 0.5)`.	`(1.0, 0.5)`
`reference_label`	`str`	Legend label of the reference.	`'Log-normal reference'`
`n_points`	`int`	Points per fitted curve, at least 2. Default 200.	`200`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The figure.

Raises:

Type	Description
`ValueError`	If no dataset is given, a dataset is malformed, or `sigma` is not positive.

Worked example: Mobility laws and their fits

`plot_distance_frequency_law(*datasets, title='Distance-frequency visitation law', x_label='r · f · km', y_label='ρᵢ(r,f) · visitors km⁻²', palette='warm', show_reference=True, reference_alpha=-2.0, reference_label='Schläpfer reference', n_points=200, width=600, height='420px', bundle_libs=True, display='html')`

Plot the distance-frequency visitation law with fitted curves.

Each dataset is drawn as empirical points of visitor density against the product of distance and visit frequency, on log-log axes, with the fitted curve and optionally the reference slope of Schläpfer et al. (2021). The fit itself is not computed here.

Parameters:

Name	Type	Description	Default
`*datasets`	`tuple`	One or more `(rf_points, rho_points, eta, mu, label)` tuples. `eta` and `mu` must be positive; the points are positive arrays of equal length.	`()`
`title`	`str`	Chart title.	`'Distance-frequency visitation law'`
`x_label`	`str`	Axis labels.	`'r · f · km'`
`y_label`	`str`	Axis labels.	`'ρᵢ(r,f) · visitors km⁻²'`
`show_reference`	`bool`	Draw the reference slope. Default True.	`True`
`reference_alpha`	`float`	Exponent of the reference line. Default -2.0.	`-2.0`
`reference_label`	`str`	Legend label of the reference.	`'Schläpfer reference'`
`n_points`	`int`	Points per fitted curve, at least 2. Default 200.	`200`
`palette`	`str or dict`	Name of a built-in palette (`"warm"`, `"ink"`, `"terracotta"`, `"forest"`) or a mapping with the same keys as `PALETTES`. Default `"warm"`.	`'warm'`
`width`	`int or str`	Chart width: an integer in pixels or a CSS length such as `"100%"`.	`600`
`height`	`str`	Chart height as a CSS length such as `"420px"`.	`'420px'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The log-log figure.

Raises:

Type	Description
`ValueError`	If no dataset is given, a dataset is malformed, or `eta` or `mu` is not positive.

Worked example: Mobility laws and their fits

`plot_stvd_comparison(layers, *, area_property='area', volume_diff_property='volume_diff_pct', peak_shift_property='peak_shift_hours', volume_threshold=3.0, zoom_to_resolution=None, center=None, zoom=10, tile_url=DEFAULT_TILE_URL, attribution=DEFAULT_ATTRIBUTION, title='STVD comparison', width='100%', height='600px', bundle_libs=True, display='html')`

Map a spatio-temporal visitation difference (STVD) comparison on a Leaflet basemap.

Every polygon is coloured by two things at once: how much the visit volume differs between the two datasets (percent) and how far the daily peak moved (hours). Several layers at different H3 resolutions can be given, and the layer that is drawn follows the map zoom. This chart needs an internet connection for the basemap tiles and has no static SVG form.

Parameters:

Name	Type	Description	Default
`layers`	`mapping`	H3 resolution to a GeoJSON FeatureCollection of Polygon or MultiPolygon features. Each feature's `properties` must hold the three properties below.	required
`area_property`	`str`	Property with the area name shown in the tooltip. Default `"area"`.	`'area'`
`volume_diff_property`	`str`	Property with the volume difference in percent. Default `"volume_diff_pct"`.	`'volume_diff_pct'`
`peak_shift_property`	`str`	Property with the peak shift in hours, between 0 and 12. Default `"peak_shift_hours"`.	`'peak_shift_hours'`
`volume_threshold`	`float`	Absolute volume difference (percent) that separates the colour bins. Must be positive. Default 3.0.	`3.0`
`zoom_to_resolution`	`mapping`	Map zoom level to the H3 resolution drawn from that zoom upward; must include zoom 0. Default: derived from the available layers.	`None`
`center`	`sequence of float`	Map centre as longitude, latitude. Default: the centre of the data.	`None`
`zoom`	`int`	Initial map zoom. Default 10.	`10`
`tile_url`	`str`	Basemap tile URL template. Default: OpenStreetMap.	`DEFAULT_TILE_URL`
`attribution`	`str`	Attribution text for the tiles.	`DEFAULT_ATTRIBUTION`
`title`	`str`	Chart title. Default `"STVD comparison"`.	`'STVD comparison'`
`height`	`int or str`	Map height. Default `"600px"`.	`'600px'`
`width`	`int or str`	Map width. Default `"100%"`.	`'100%'`
`bundle_libs`	`bool`	Embed the ECharts (and, for maps, Leaflet) JavaScript in the chart. Pass False when the page already loads it, for example with `get_resource_bundle`. Default True.	`True`
`display`	`('html', 'svg')`	How a notebook shows the chart: `"html"` is interactive, `"svg"` is a static picture that also renders where JavaScript is not run, such as this documentation. Default `"html"`.	`"html"`

Returns:

Type	Description
`EChartsFigure`	The map figure.

Raises:

Type	Description
`ValueError`	If a layer is not a FeatureCollection of polygons, a property is missing or non-finite, a peak shift is outside [0, 12], `volume_threshold` is not positive, or `zoom_to_resolution` is invalid.
`TypeError`	If a feature has no `properties` object or `attribution` is not a string.

Worked example: Maps, which are interactive only

Visualization

Choosing the output

Palettes

Motif reference data

ecdf(data, *, value_col, second=None, labels=('first', 'second'), title='Empirical cumulative distribution', x_label=None, x_unit='', cdf_cutoff=0.98, palette='warm', width=600, height='420px', bundle_libs=True, display='html')

bar(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')

scatter(data, *, x_col, y_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')

heatmap(data, *, x_col, y_col, value_col, title='', palette='warm', width=600, height='520px', bundle_libs=True, display='html')

boxplot(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')

map(geojson, *, title='Map', palette='warm', width='100%', height='600px', bundle_libs=True, display='html')

Chart dataclass

option property

render()

to_dict()

to_html(filepath)

to_json(filepath)

to_svg(filepath=None)

EChartsFigure dataclass

option property

option_json property

to_dict()

to_html(filepath)

to_json(filepath)

to_svg(filepath=None)

get_resource_bundle(*, echarts=True, leaflet=False)

plot_jump_lengths_ecdf(left, right, labels=('A', 'B'), title='Jump length ECDF', palette='warm', cdf_cutoff=0.98, x_label='jump length', x_unit='km', width=600, *, bundle_libs=True, display='html')

plot_radius_of_gyration_ecdf(left, right, labels=('A', 'B'), title='Radius of gyration ECDF', palette='warm', cdf_cutoff=0.98, x_label='radius of gyration', x_unit='km', width=600, *, bundle_libs=True, display='html')

plot_visits_frequency_ecdf(left, right, labels=('A', 'B'), title='Visits frequency ECDF', palette='warm', cdf_cutoff=0.98, x_label='number of visits', x_unit='', width=600, *, bundle_libs=True, display='html')

plot_trip_duration_ecdf(left, right, labels=('A', 'B'), title='Trip duration ECDF', palette='warm', cdf_cutoff=0.98, x_label='trip duration', x_unit='min', width=600, *, bundle_libs=True, display='html')

plot_dwell_time_ecdf(left, right, labels=('A', 'B'), title='Dwell time ECDF', palette='warm', cdf_cutoff=0.98, x_label='dwell time', x_unit='min', width=600, *, bundle_libs=True, display='html')

plot_visit_purpose_distribution(data, *, labels=None, title='Visit Purpose Distribution', palette='warm', width=600, height='420px', bundle_libs=True, display='html')

plot_visit_purpose_comparison(datasets, *, title='Visit Purpose Comparison', palette='warm', width=800, height='420px', bundle_libs=True, display='html')

plot_activity_transition_matrix(matrix_or_visits, *, title='Activity Transition Matrix', palette='warm', width=600, height='520px', bundle_libs=True, display='html')

plot_activity_transition_difference(first, second, *, labels=('first', 'second'), title='Activity Transition Difference', palette='warm', width=600, height='520px', bundle_libs=True, display='html')

plot_daily_activity_distribution(data, *, categories=None, n_bins=None, title='Daily Activity Distribution', palette='warm', width=900, height='420px', bundle_libs=True, display='html')

plot_daily_activity_difference(first, second, *, categories=None, n_bins=None, labels=('first', 'second'), title='Daily Activity Difference', palette='warm', width=900, height='420px', bundle_libs=True, display='html')

plot_mobility_profiles(profiles, *, profile_col='agent_type', profile_colors=None, title='Mobility profiles', palette='warm', width=520, height='420px', bundle_libs=True, display='html')

plot_profile_metrics(datasets, *, metrics=('regularity', 'diversity', 'stationarity', 'entropy'), profile_col='agent_type', profile_order=('Scouter', 'Regular', 'Routiner'), title='Mobility profile metrics', palette='warm', width=900, height='640px', bundle_libs=True, display='html')

plot_motif_literature_comparison(*, literature_df=None, reference_distribution=None, comparison_distribution=None, labels=('Reference', 'Simulation'), title='Motif Literature Comparison', palette='warm', width=900, height='560px', bundle_libs=True, display='html')

`ecdf(data, *, value_col, second=None, labels=('first', 'second'), title='Empirical cumulative distribution', x_label=None, x_unit='', cdf_cutoff=0.98, palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

`bar(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

`scatter(data, *, x_col, y_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

`heatmap(data, *, x_col, y_col, value_col, title='', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

`boxplot(data, *, category_col, value_col, series_col=None, title='', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

`map(geojson, *, title='Map', palette='warm', width='100%', height='600px', bundle_libs=True, display='html')`

`Chart` `dataclass`

`option` `property`

`render()`

`to_dict()`

`to_html(filepath)`

`to_json(filepath)`

`to_svg(filepath=None)`

`EChartsFigure` `dataclass`

`option` `property`

`option_json` `property`

`to_dict()`

`to_html(filepath)`

`to_json(filepath)`

`to_svg(filepath=None)`

`get_resource_bundle(*, echarts=True, leaflet=False)`

`plot_jump_lengths_ecdf(left, right, labels=('A', 'B'), title='Jump length ECDF', palette='warm', cdf_cutoff=0.98, x_label='jump length', x_unit='km', width=600, *, bundle_libs=True, display='html')`

`plot_radius_of_gyration_ecdf(left, right, labels=('A', 'B'), title='Radius of gyration ECDF', palette='warm', cdf_cutoff=0.98, x_label='radius of gyration', x_unit='km', width=600, *, bundle_libs=True, display='html')`

`plot_visits_frequency_ecdf(left, right, labels=('A', 'B'), title='Visits frequency ECDF', palette='warm', cdf_cutoff=0.98, x_label='number of visits', x_unit='', width=600, *, bundle_libs=True, display='html')`

`plot_trip_duration_ecdf(left, right, labels=('A', 'B'), title='Trip duration ECDF', palette='warm', cdf_cutoff=0.98, x_label='trip duration', x_unit='min', width=600, *, bundle_libs=True, display='html')`

`plot_dwell_time_ecdf(left, right, labels=('A', 'B'), title='Dwell time ECDF', palette='warm', cdf_cutoff=0.98, x_label='dwell time', x_unit='min', width=600, *, bundle_libs=True, display='html')`

`plot_visit_purpose_distribution(data, *, labels=None, title='Visit Purpose Distribution', palette='warm', width=600, height='420px', bundle_libs=True, display='html')`

`plot_visit_purpose_comparison(datasets, *, title='Visit Purpose Comparison', palette='warm', width=800, height='420px', bundle_libs=True, display='html')`

`plot_activity_transition_matrix(matrix_or_visits, *, title='Activity Transition Matrix', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

`plot_activity_transition_difference(first, second, *, labels=('first', 'second'), title='Activity Transition Difference', palette='warm', width=600, height='520px', bundle_libs=True, display='html')`

`plot_daily_activity_distribution(data, *, categories=None, n_bins=None, title='Daily Activity Distribution', palette='warm', width=900, height='420px', bundle_libs=True, display='html')`

`plot_daily_activity_difference(first, second, *, categories=None, n_bins=None, labels=('first', 'second'), title='Daily Activity Difference', palette='warm', width=900, height='420px', bundle_libs=True, display='html')`

`plot_mobility_profiles(profiles, *, profile_col='agent_type', profile_colors=None, title='Mobility profiles', palette='warm', width=520, height='420px', bundle_libs=True, display='html')`

`plot_profile_metrics(datasets, *, metrics=('regularity', 'diversity', 'stationarity', 'entropy'), profile_col='agent_type', profile_order=('Scouter', 'Regular', 'Routiner'), title='Mobility profile metrics', palette='warm', width=900, height='640px', bundle_libs=True, display='html')`

`plot_motif_literature_comparison(*, literature_df=None, reference_distribution=None, comparison_distribution=None, labels=('Reference', 'Simulation'), title='Motif Literature Comparison', palette='warm', width=900, height='560px', bundle_libs=True, display='html')`