Title: | Turn Place Names into Map Data |
---|---|
Description: | A tool for easily matching spatial data when you have a list of place/region names. You might have a data frame that came from a spreadsheet tracking some data by suburb or state. This package can convert it into a spatial data frame ready for plotting. The actual map data is provided by other packages (or your own code). |
Authors: | Carl Suster [aut, cre] , Western Sydney Local Health District, NSW Health [cph] |
Maintainer: | Carl Suster <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.2.1.9000 |
Built: | 2024-10-24 04:14:22 UTC |
Source: | https://github.com/cidm-ph/cartographer |
Cartographer is a framework for easily matching spatial data when you have a list of standardised place names. You might have a data frame that came from a spreadsheet tracking some data by suburb or state. This package can convert it into a spatial data frame ready for plotting. The actual map data is provided by other packages (or your own code) that register the data with cartographer.
Maintainer: Carl Suster [email protected] (ORCID)
Other contributors:
Western Sydney Local Health District, NSW Health [copyright holder]
Useful links:
Report bugs at https://github.com/cidm-ph/cartographer/issues
Convert input data frame into a spatial data frame
add_geometry(x, location, feature_type = NA, geom_name = "geometry")
add_geometry(x, location, feature_type = NA, geom_name = "geometry")
x |
Data frame with a feature name column. |
location |
Feature names (tidy evaluation). |
feature_type |
The registered map corresponding to values in |
geom_name |
Name for the new column to contain the geometry. |
A spatial data frame containing all of the columns from the input data frame.
add_geometry(nc_type_example_2, county, feature_type = "sf.nc")
add_geometry(nc_type_example_2, county, feature_type = "sf.nc")
This gives the list of feature names that are part of the specified map data.
The list includes any aliases defined when the map was registered. Note that
the location
column matching is case insensitive (see Details below).
feature_names(feature_type)
feature_names(feature_type)
feature_type |
Type of map feature. See |
Character vector of feature names.
register_map()
and resolve_feature_names()
head(feature_names("sf.nc"))
head(feature_names("sf.nc"))
Each feature type corresponds to map data that has been registered.
feature_types()
feature_types()
Character vector of registered feature types.
feature_types()
feature_types()
Retrieve a map outline registered with cartographer.
map_outline(feature_type)
map_outline(feature_type)
feature_type |
Type of map feature. See |
The map outline that was registered under feature_type
. Note that
the outline is optional, so this will return NULL
if none was registered.
map_outline("sf.nc")
map_outline("sf.nc")
Retrieve map data registered with cartographer.
map_sf(feature_type)
map_sf(feature_type)
feature_type |
Type of map feature. See |
The spatial data frame that was registered under feature_type
.
map_sf("sf.nc")
map_sf("sf.nc")
Retrieve geometry of a single location.
map_sfc(feature_names, feature_type)
map_sfc(feature_names, feature_type)
feature_names |
Name of the feature(s) to retrieve. This must be an exact case-sensitive match, and aliases are not consulted. |
feature_type |
Type of map feature. See |
The geometry as a sfc
object.
map_sfc("Ashe", "sf.nc") map_sfc(c("Craven", "Buncombe"), "sf.nc")
map_sfc("Ashe", "sf.nc") map_sfc(c("Craven", "Buncombe"), "sf.nc")
This dataset contains random data compatible with the sf.nc
example
map data for illustrating cartographer's features. nc_type_example_1
contains a deliberate error in the county name for a single row, whereas
nc_type_example_2
contains correct data.
nc_type_example_1 nc_type_example_2
nc_type_example_1 nc_type_example_2
Objects of class data.frame
with 50 and 200 rows respectively, and 2 columns:
Feature names that match the NAME field of the nc dataset
Arbitrary categorical data
This adds a new feature type that can then be used by all the geoms in this
package. If registering from another package, this should occur in the
.onLoad()
hook in the package.
register_map( feature_type, data, feature_column, aliases = NULL, outline = NULL, lazy = TRUE )
register_map( feature_type, data, feature_column, aliases = NULL, outline = NULL, lazy = TRUE )
feature_type |
Name of the type. If registering from within a package,
the suggested format is |
data |
A simple feature data frame with the map data, or a function
that returns a data frame. When |
feature_column |
Name of the column of |
aliases |
Optional named character vector or list that maps aliases to values that appear in the feature column. This allows abbreviations or alternative names to be supported. |
outline |
Optional sf geometry containing just the outline of the map,
or a function returning such a geometry. When |
lazy |
When |
Registration supports delayed evaluation (lazy loading). This is particularly useful for larger datasets, so that they are not loaded into memory until they are accessed.
No return value; this updates the global feature registry.
vignette("registering_maps")
# register a map of the states of Italy from rnaturalearth using the # Italian names, and providing an outline of the country register_map( "italy", data = rnaturalearth::ne_states(country = "italy", returnclass = "sf"), feature_column = "name_it", outline = rnaturalearth::ne_countries(country = "italy", returnclass = "sf", scale = "large") )
# register a map of the states of Italy from rnaturalearth using the # Italian names, and providing an outline of the country register_map( "italy", data = rnaturalearth::ne_states(country = "italy", returnclass = "sf"), feature_column = "name_it", outline = rnaturalearth::ne_countries(country = "italy", returnclass = "sf", scale = "large") )
Names are resolved by checking for the first match using:
case sensitive match, then
case sensitive match using aliases, then
case insensitive match, then
case insensitive match using aliases.
resolve_feature_names(feature_names, feature_type, unmatched = "error")
resolve_feature_names(feature_names, feature_type, unmatched = "error")
feature_names |
Character vector of feature names in the data. |
feature_type |
Type of map feature. See |
unmatched |
Controls behaviour when |
Character vector of the canonicalised names.
resolve_feature_names(c("LEE", "ansoN"), feature_type = "sf.nc") resolve_feature_names(c("LEE", "ansoNe"), feature_type = "sf.nc", unmatched = "pass")
resolve_feature_names(c("LEE", "ansoN"), feature_type = "sf.nc") resolve_feature_names(c("LEE", "ansoNe"), feature_type = "sf.nc", unmatched = "pass")
If feature_type
is provided, this simply checks that the type has been
registered. If it is NA
, however, an attempt it made to guess the
appropriate choice. This is done by comparing the example values provided
as feature_names
with the names of all registered map datasets. If there
is an unambiguous match, that will be filled in.
resolve_feature_type(feature_type, feature_names)
resolve_feature_type(feature_type, feature_names)
feature_type |
Type of map feature. See |
feature_names |
Character vector of feature names in the data. This can be a subset of the values. |
Cartographer lazy loads map data for registered maps. In order to compare
the example feature_names
with registered maps, it might be necessary
to force some of these datasets to load. To minimise the impact, any maps
that have already been loaded are checked first. Other maps are then
loaded one at a time until any matches are found. Consequently, the result
returned by this function is not deterministic.
In the worst case where none of the registered maps matches, all of them will be loaded. This might take several seconds and occupy some memory, depending on which maps are registered. If a match is found, however, it will be found quickly on subsequent calls since the data will have already been loaded.
The best way to avoid these issues is to explicitly specify the
feature_type
.
The resolved feature type as a scalar character.
resolve_feature_type("sf.nc") resolve_feature_type(NA, feature_names = c("ANSON", "Stanly"))
resolve_feature_type("sf.nc") resolve_feature_type(NA, feature_names = c("ANSON", "Stanly"))