forked from ateucher/rmapshaper
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
149 lines (109 loc) · 6.75 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
output:
md_document:
variant: markdown_github
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "fig/README-"
)
```
[](https://travis-ci.org/ateucher/rmapshaper)
[](https://ci.appveyor.com/project/ateucher/rmapshaper)
[](https://codecov.io/github/ateucher/rmapshaper?branch=master)
[](https://cran.r-project.org/package=rmapshaper)
[](http://cran.rstudio.com/web/packages/rmapshaper/index.html)
[](http://cran.rstudio.com/web/packages/rmapshaper/index.html)
## rmapshaper
An R package providing access to the awesome [mapshaper](https://github.com/mbloch/mapshaper/) tool by Matthew Bloch, which has both a [Node.js command-line tool](https://github.com/mbloch/mapshaper/wiki/Introduction-to-the-Command-Line-Tool) as well as an [interactive web tool](http://mapshaper.org/).
I started this package so that I could use mapshaper's [Visvalingam](http://bost.ocks.org/mike/simplify/) simplification method in R. There is, as far as I know, no other R package that performs topologically-aware multi-polygon simplification. (This means that shared boundaries between adjacent polygons are always kept intact, with no gaps or overlaps, even at high levels of simplification).
But mapshaper does much more than simplification, so I am working on wrapping
most of the core functionality of mapshaper into R functions.
So far, `rmapshaper` provides the following functions:
- `ms_simplify` - simplify polygons or lines
- `ms_clip` - clip an area out of a layer using a polygon layer or a bounding box. Works on polygons, lines, and points
- `ms_erase` - erase an area from a layer using a polygon layer or a bounding box. Works on polygons, lines, and points
- `ms_dissolve` - aggregate polygon features, optionally specifying a field to aggregate on. If no field is specified, will merge all polygons into one.
- `ms_explode` - convert multipart shapes to single part. Works with polygons, lines, and points in geojson format, but currently only with polygons and lines in the `Spatial` classes (not `SpatialMultiPoints` and `SpatialMultiPointsDataFrame`).
- `ms_lines` - convert polygons to topological boundaries (lines)
- `ms_innerlines` - convert polygons to shared inner boundaries (lines)
- `ms_points` - create points from a polygon layer
- `ms_filter_fields` - Remove fields from the attributes
- `ms_filter_islands` - Remove small detached polygons
If you run into any bugs or have any feature requests, please file an [issue](https://github.com/ateucher/rmapshaper/issues/)
### Installation
`rmapshaper` is on CRAN. Install the current version with:
```r
install.packages("rmapshaper")
```
You can install the development version from github with `devtools`:
```r
## install.packages("devtools")
library(devtools)
install_github("ropensci/geojsonio")
install_github("ateucher/rmapshaper")
```
### Usage
rmapshaper works with geojson strings (character objects of class `geo_json`) and `list`
geojson objects of class `geo_list`. These classes are defined in the `geojsonio`
package. It also works with `Spatial` classes from the `sp` package.
We will use the `states` dataset from the `geojsonio` package and first turn it
into a `geo_json` object:
```{r}
library(geojsonio)
library(rmapshaper)
library(sp)
## First convert to json
states_json <- geojson_json(states, geometry = "polygon", group = "group")
## For ease of illustration via plotting, we will convert to a `SpatialPolygonsDataFrame`:
states_sp <- geojson_sp(states_json)
## Plot the original
plot(states_sp)
## Now simplify using default parameters, then plot the simplified states
states_simp <- ms_simplify(states_sp)
plot(states_simp)
```
You can see that even at very high levels of simplification, the mapshaper
simplification algorithm preserves the topology, including shared boudaries:
```{r}
states_very_simp <- ms_simplify(states_sp, keep = 0.001)
plot(states_very_simp)
```
Compare this to the output using `rgeos::gSimplify`, where overlaps and gaps are evident:
```{r}
library(rgeos)
states_gsimp <- gSimplify(states_sp, tol = 1, topologyPreserve = TRUE)
plot(states_gsimp)
```
All of the functions are quite fast with `geo_json` character objects and `geo_list`
list objects. They are slower with the `Spatial` classes due to internal conversion
to/from json. If you are going to do multiple operations on large `Spatial` objects,
it's recommended to first convert to json using `geojson_list` or `geojson_json` from
the `geojsonio` package. All of the functions have the input object as the first argument,
and return the same class of object as the input. As such, they can be chained together.
For a totally contrived example, using `states_sp` as created above:
```{r}
library(geojsonio)
library(rmapshaper)
library(sp)
library(magrittr)
## First convert 'states' dataframe from geojsonio pkg to json
states_json <- geojson_json(states, lat = "lat", lon = "long", group = "group",
geometry = "polygon")
states_json %>%
ms_erase(bbox = c(-107, 36, -101, 42)) %>% # Cut a big hole in the middle
ms_dissolve() %>% # Dissolve state borders
ms_simplify(keep_shapes = TRUE, explode = TRUE) %>% # Simplify polygon
geojson_sp() %>% # Convert to SpatialPolygonsDataFrame
plot(col = "blue") # plot
```
### Thanks
This package uses the [V8](https://cran.r-project.org/package=V8) package to provide an environment in which to run mapshaper's javascript code in R. It relies heavily on all of the great spatial packages that already exist (especially `sp` and `rgdal`), the `geojsonio` package for converting between geo_list, geo_json, and `sp` objects, and the `jsonlite` package for converting between json strings and R objects.
Thanks to [timelyportfolio](https://github.com/timelyportfolio) for helping me wrangle the javascript to the point where it works in V8. He also wrote the [mapshaper htmlwidget](https://github.com/timelyportfolio/mapshaper_htmlwidget), which provides access to the mapshaper web inteface, right in your R session. We have plans to combine the two in the future.
### Code of Conduct
Please note that this project is released with a [Contributor Code of Conduct](CONDUCT.md). By participating in this project you agree to abide by its terms.
### LICENSE
MIT