Privacy risk

How identifiable is each person if an attacker knows some of their places, visit counts, order or times? These functions return a re-identification risk for each user.

Privacy location comparisons use H3 cells at resolution 12 by default, which groups small GPS jitter into one representative location. Every function accepts h3_resolution from 0 through 15. Forced-instance output gives each known place as the lat and lng of its H3 cell centre.

Catalogue

Attacks on places and sequences

API	Description	Example
`location_risk`	Assess re-identification risk from visited locations.	Risk from places the attacker knows
`unique_location_risk`	Assess re-identification risk from each user's distinct locations.	Other attacker models
`location_sequence_risk`	Assess re-identification risk from ordered location sequences.	Other attacker models
`location_time_risk`	Assess re-identification risk from locations and the time of the visit.	Other attacker models

Attacks on visit frequency

API	Description	Example
`location_frequency_risk`	Assess re-identification risk from locations and their visit counts.	Other attacker models
`location_probability_risk`	Assess re-identification risk from locations and visit probabilities.	Other attacker models
`location_proportion_risk`	Assess re-identification risk from locations and their share of the most visited place.	Other attacker models

Home and work

API	Description	Example
`home_work_risk`	Assess re-identification risk from a person's two most visited places.	Other attacker models

`location_risk(traj, knowledge_length, *, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from visited locations.

The attacker knows knowledge_length places a person visited, without knowing how often or when, and looks for the users who visited all of them. The candidate knowledge sets are enumerated over visit records: a place visited three times is three records, so it appears as three instances. Use unique_location_risk to enumerate distinct places instead.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many places of a person's history the attacker knows (at least 1).	required
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Risk from places the attacker knows

`unique_location_risk(traj, knowledge_length, *, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from each user's distinct locations.

The attacker knows knowledge_length places, enumerated over the set of distinct places a user visited, so a place visited several times is one instance. This is the difference from location_risk, which enumerates visit records. For knowledge_length=1 the two give the same per-user risk; for larger values location_risk can be higher, because it also lets the attacker know the same place twice.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many places of a person's history the attacker knows (at least 1).	required
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`location_sequence_risk(traj, knowledge_length, *, targets=None, force_instances=False, datetime_col=None, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from ordered location sequences.

The attacker knows knowledge_length consecutive places in the order the person visited them.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns, and a datetime column. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many consecutive places of a person's history the attacker knows (at least 1).	required
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`location_time_risk(traj, knowledge_length, *, time_precision='Hour', targets=None, force_instances=False, datetime_col=None, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from locations and the time of the visit.

The attacker knows knowledge_length (place, time) pairs, with time given at time_precision.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns, and a datetime column. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many (place, time) pairs of a person's history the attacker knows (at least 1).	required
`time_precision`	`str`	Time resolution of the known visits, for example `"Hour"` or `"Day"`. Default `"Hour"`.	`'Hour'`
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`location_frequency_risk(traj, knowledge_length, *, tolerance=0.0, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from locations and their visit counts.

The attacker knows knowledge_length places and how many times the person visited each.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many places with their visit counts of a person's history the attacker knows (at least 1).	required
`tolerance`	`float`	Allowed relative error (0 to 1) on the known visit count. Default 0 (exact).	`0.0`
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`location_probability_risk(traj, knowledge_length, *, tolerance=0.0, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from locations and visit probabilities.

The attacker knows knowledge_length places and the probability of visiting each (visits to that place divided by all visits).

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many places with their visit probabilities of a person's history the attacker knows (at least 1).	required
`tolerance`	`float`	Allowed relative error (0 to 1) on the known probability. Default 0 (exact).	`0.0`
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`location_proportion_risk(traj, knowledge_length, *, tolerance=0.0, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from locations and their share of the most visited place.

The attacker knows knowledge_length places and, for each, the number of visits as a proportion of the visits to the person's most visited place (1 for the top place, 0.5 for a place visited half as often). tolerance allows a relative error on that proportion.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude and longitude columns. A user column is required: the risk is computed for each user against all the others.	required
`knowledge_length`	`int`	How many places with their relative visit frequency of a person's history the attacker knows (at least 1).	required
`tolerance`	`float`	Allowed relative error (0 to 1) on the known proportion. Default 0 (exact).	`0.0`
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `False` (default) return one row per user with `risk`, the highest probability over all possible attacker knowledge sets of this size. If `True` return one row per knowledge instance with its probability `prob`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) used to turn coordinates into places. Coarser cells (lower values) make people harder to tell apart. Default 12 (about 10 m). Ignored when `locations` is given.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its location ids, to use your own places instead of H3 cells.	`'location_id'`

Returns:

Type	Description
`DataFrame`	With `force_instances=False`: columns `uid` and `risk` (a probability between 0 and 1; 1 means some knowledge set of this size matches only that user). With `force_instances=True`: one row per knowledge instance with `uid`, `instance`, the known element(s) and `prob`. Known places are given as `lat` and `lng` of the H3 cell centre. The result is in the input's dataframe type.

Notes

The risk is relative to the other users in traj: with few users almost any knowledge identifies a person. Risk is 1 divided by the number of users whose history is compatible with the knowledge.

Worked example: Other attacker models

`home_work_risk(traj, *, targets=None, force_instances=False, lat_col=None, lng_col=None, uid_col=None, h3_resolution=12, locations=None, location_id_col='location_id')`

Assess re-identification risk from a person's two most visited places.

The attacker knows the two places a person visits most often (typically home and work), without knowing which is which, and looks for the users with the same two top places.

Parameters:

Name	Type	Description	Default
`traj`	`dataframe`	Trajectory table (any eager dataframe) with latitude, longitude and a user column.	required
`targets`	`array - like`	Users to assess; `None` assesses every user.	`None`
`force_instances`	`bool`	If `True`, return the knowledge instance of each user with its probability `prob` instead of `risk`.	`False`
`lat_col`	`str`	Column names; auto-detected when `None`.	`None`
`lng_col`	`str`	Column names; auto-detected when `None`.	`None`
`uid_col`	`str`	Column names; auto-detected when `None`.	`None`
`h3_resolution`	`int`	H3 resolution (0 to 15) that turns coordinates into places. Coarser cells make people harder to tell apart. Default 12.	`12`
`locations`	`optional`	A global `Locations` catalogue and the column of `traj` holding its ids, to use your own places.	`None`
`location_id_col`	`optional`	A global `Locations` catalogue and the column of `traj` holding its ids, to use your own places.	`'location_id'`

Returns:

Type	Description
`DataFrame`	Columns `uid` and `risk`, a probability between 0 and 1 (1 means no other user shares the two top places), in the input's dataframe type.

Worked example: Other attacker models