# Package cartogramR: User guide

Pierre-André Cornillon, Florent Demoraes

## ► To cite this version:

Pierre-André Cornillon, Florent Demoraes. Package cartogramR: User guide. 2021. hal-03280009

HAL Id: hal-03280009

https://hal.science/hal-03280009

Submitted on 7 Jul 2021

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
# User Guide
## Package ‘cartogramR’

July 5, 2021

**Version** 0.9-9

**Date** 2021-06-30

**Title** Continuous Cartogram

**Description** Procedures for making continuous cartogram. Procedures available are: flow based cartogram (Gastner & Newman (2004) <doi:10.1073/pnas.0400280101>), fast flow based cartogram (Gastner, Seguy & More (2018) <doi:10.1073/pnas.1712674115>), rubber band based cartogram (Dougenik et al. (1985) <doi:10.1111/j.0033-0124.1985.00075.x>).

**Depends** R (>= 3.6.0)

**Imports** sf, data.table

**SystemRequirements** FFTW (>=3.3.1); possible package: fftw-devel (rpm), fftw-dev (deb) or fftw (brew).

**License** MIT + file LICENSE

**RoxygenNote** 7.1.1

**Encoding** UTF-8

**NeedsCompilation** yes

**Author** Pierre-Andre Cornillon [aut, cre], Florent Demoraes [aut], Flow-Based-Cartograms [cph] (Author of core C code for gsm and gn procedures)

**Maintainer** Pierre-Andre Cornillon <pierre-andre.cornillon@univ-rennes2.fr>

**Repository** CRAN

**Date/Publication** 2021-07-05 08:10:02 UTC

R topics documented:

<table><tr><td>as.sf</td><td>2</td></tr><tr><td>as.sf.cartogramR</td><td>3</td></tr><tr><td>as.sfc</td><td>3</td></tr><tr><td>as.sfc.cartogramR</td><td>4</td></tr><tr><td>as.sfmultipolygon</td><td>4</td></tr></table>
<table><tr><td>cartogramR</td><td>5</td></tr><tr><td>cartogramR_options</td><td>6</td></tr><tr><td>check_ring_dir</td><td>8</td></tr><tr><td>distBetweenVertices</td><td>9</td></tr><tr><td>france_dept</td><td>9</td></tr><tr><td>france_rivers</td><td>10</td></tr><tr><td>fromCoordPolygon</td><td>10</td></tr><tr><td>geomCartogramR</td><td>11</td></tr><tr><td>grid_analysis</td><td>12</td></tr><tr><td>makeLayer</td><td>13</td></tr><tr><td>plotCartogramR</td><td>13</td></tr><tr><td>plot.dbvCartogramR</td><td>14</td></tr><tr><td>plot.gridanalysis.cartogramR</td><td>15</td></tr><tr><td>precartogramR</td><td>16</td></tr><tr><td>printCartogramR</td><td>17</td></tr><tr><td>print_summary.cartogramR</td><td>18</td></tr><tr><td>residuals.cartogramR</td><td>18</td></tr><tr><td>summary.cartogramR</td><td>19</td></tr><tr><td>summary.dbvCartogramR</td><td>20</td></tr><tr><td>summary.gridanalysis.cartogramR</td><td>21</td></tr><tr><td>toCoordPolygon</td><td>22</td></tr><tr><td>usa</td><td>22</td></tr></table>

Index 24

as.sf Coerce an object to a sf object

Description

Coerce an object to a sf object

Usage

as.sf(x, ...)

Arguments

x object to be coerced

\dots arguments passed to or from other methods.

Value

an sf object
as.sf.cartogramR

Coerce a cartogramR to a sf object

**Description**

Coerce a cartogramR to a sf object returning the sf object used to construct the cartogram with the cartogram as geometry and some more attributes

**Usage**

## S3 method for class 'cartogramR'
as.sf(x, ...)

**Arguments**

<table><tr><td>x</td><td>a cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>

**Value**

a sf object including all the data (attributes) contained in the original sf object used to construct the cartogram and

* original areas of region (orig_area)

* final/deformed areas of region (final_area)

* target areas of region (target_area)

* original centers (x_origCenters and y_origCenters)

* final centers (x_finalCenters and y_finalCenters)

as.sfc

Coerce an object to a sfc object

**Description**

Coerce an object to a sfc object

**Usage**

as.sfc(x, ...)

**Arguments**

<table><tr><td>x</td><td>object to be coerced</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>
Value

a sfc object

as.sfc.cartogramR

Coerce a cartogramR to a sfc object

Description

Coerce a cartogramR to a sfc object extracting the component cartogram of the cartogramR object

Usage

## S3 method for class 'cartogramR'
as.sfc(x, ...)

Arguments

<table><tr><td>x</td><td>a cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>

Value

a sfc object

as.sfmultipolygon

Transform a sf object with several rows (polygons) by region to an sf object with one row by region and thus one multipolygon by region

Description

Transform a sf object with several rows (polygons) by region to an sf object with one row by region and thus one multipolygon by region

Usage

as.sfmultipolygon(data, idregion, closepolygon = FALSE)

Arguments

<table><tr><td>data</td><td>a sf object</td></tr><tr><td>idregion</td><td>a character string which indicates the name of the column (in data object) which contains the region identifier.</td></tr><tr><td>closepolygon</td><td>a boolean (default to FALSE) if TRUE it controls if polygons are closed and if not add the first vertice at the end.</td></tr></table>

Value

a sf object with one row by region and one multipolygon by region.
<table><tr><td>cartogramR</td><td>Make a continuous cartogram (density equalizing maps)</td></tr></table>

## Description

Make a continuous cartogram (density equalizing maps)

## Usage

```r
cartogramR(
  data,
  count,
  method = c("gsm", "gn", "dcn", "GastnerSeguyMore", "GastnerNewman",
    "DougenikChrismanNiemeyer"),
  options = NULL
)
```

## Arguments

<table><tr><td>data</td><td>a sf object which contains at least two columns: obviously a geometry column (giving the map) and a column which contains a count by region (leading to a density by region, density to be equalized by deformation). Each row of data is a region and contains the simple feature geometry of type POLYGON or MULTIPOLYGON. Polygon ring directions are not checked but exterior ring must counter clockwise and holes clockwise (use option check-ring-dir of sf::st_read to achieve the right orientation of ring direction on import or use check-ring-dir function)</td></tr><tr><td>count</td><td>a character string which indicates the name of the column (in data object) which contains the count by region.</td></tr><tr><td>method</td><td>the method to be used, can be one of the following: gsm or GastnerSeguyMore (default), gn or GastnerNewman, dcn or DougenikChrismanNiemeyer.</td></tr><tr><td>options</td><td>a named list given to cartogramR_options function which process options see cartogramR_options for details. Default to NULL.</td></tr></table>

## Value

A list with the following components:

* cartogram: a sf object (in the same order of data or sorted by idregion see reordered argument) which contains the cartogram (ie the initial polygons after deformation)

* orig_area: original areas of regions

* final_area: final areas of regions in the cartogram

* origCenters: the initial centers calculated with st_point_on Bási surface

* finalCenters: the centers after deformation
* `gridx`: (for flow-based method) final grid (x-axis) if requested (see `cartogramR_options` for details).

* `gridy`: (for flow-based method) final grid (y-axis) if requested (see `cartogramR_options` for details).

* `count`: the count by region

* `target_area`: target areas of regions

* `initial_data`: the initial `sf` object

* `details`: names of original data, `idcount` variable, algorithm

* `options`: values of options

## References

* Dougenik, J., Chrisman, R. & Niemeyer, D. (1985). An algorithm to construct continuous area cartograms. Professional Geographer **37**: 75-81.

* Gastner, M. & Newman, M.E.J. (2004). Diffusion-based method for producing density equalizing maps. *Proc. Natl. Acad. Sci. USA*, **101**:7499-7504

* Gastner, M., Seguy, V. & More, P. (2018). Fast flow-based algorithm for creating density-equalizing map projections. *Proceedings of the National Academy of Sciences USA*, **115**:E2156-E2164, website: [go-cart](https://go-cart.org/)

## Examples

```r
data(usa)
carto <- cartogramR(usa, "electors64")
plot(carto)
summary(carto)
```

`cartogramR_options` Set the options of cartogramR in the correct format

## Description

Set the options of cartogramR in the correct format

## Usage

```r
cartogramR_options(
  options,
  method = c("gsm", "gn", "dcn", "GastnerSeguyMore", "GastnerNewman",
    "DougenikChrismanNiemeyer")
)
```
## Arguments

<table><tr><td>options</td><td>a named list with some (or all) the following components:<ul><li>maxit: (all method) the maximum number of iterations, default to 50.</li><li>absrel: (all method) boolean, if TRUE relative convergence if FALSE absolute convergence (default to TRUE)</li><li>abserror: (all method) Areas on cartogram differ at most by an (absolute value of) error of abserror. That is, max_polygons larea_onCartogram - target_Areal &lt;= abserror (default to 10000)</li><li>abstol: ("dcn") the absolute convergence error tolerance: max_polygons larea(i) - area(i-1) &lt;= 1000</li><li>relerror: (all method) Areas on cartogram differ at most by an (absolute value of) relative error of relerror. That is, max_polygons larea_onCartogram / target_Area - 1 &lt;= relerror (default to 0.01)</li><li>reltol: ("dcn") the absolute convergence tolerance: max_polygons abs((area(i) - area(i-1))/area(i-1) &lt;= 1e-3</li><li>L: ("gsm" or "gn") integer, gives the value of L (default is 512), must be a power of two (for fftw)</li><li>mp: (all method) if a region contains exactly zero population, it will be replaced by mp times the smallest (strictly) positive population in any region (default to 0.2)</li><li>pf: ("gsm" or "gn") Determines space between map and boundary (default to 1.5)</li><li>sigma: ("gsm" or "gn") Width of Gaussian blur to smoothen the density (default to 5)</li><li>center: ("gsm" or "gn") either a character string (only possible choices are "centroid" or "point_onSurface") or a function. If the object is a function, it will be used to calculate the "center" of polygons; "point_onSurface" (the default) will use the function sf::st_point_onSurface while "centroid" will use sf::st_centroid.</li><li>verbose: (all method) integer giving the verbosity level (default to 0, not verbose)</li><li>grid: ("gsm" or "gn") boolean, if TRUE export the final grid from flow algorithm (default to TRUE). Setting to FALSE</li><li>check.ring.dir: (all method) boolean, if TRUE controls polygons orientation (default to TRUE)</li><li>check_only: (all method) boolean, if TRUE control only polygons orientation and no replacement is done (default to FALSE)</li></ul></td></tr><tr><td>method</td><td>the method to be used, can be one of the following: gsm or GastnerSeguyMore (default), gn or GastnerNewman, dcn or DougenikChrismanNiemeyer.</td></tr></table>

## Value

a list to be processed by cartogramR
## References

* Dougenik, J., Chrisman, R. & Niemeyer, D. (1985). An algorithm to construct continuous area cartograms. Professional Geographer **37**: 75-81.

* Gastner, M. & Newman, M. E. J. (2004). Diffusion-based method for producing density equalizing maps. *Proc. Natl. Acad. Sci. USA*, **101**:7499-7504

* Gastner, M., Seguy, V. & More, P. (2018). Fast flow-based algorithm for creating density-equalizing map projections. *Proceedings of the National Academy of Sciences USA*, **115**:E2156-E2164

## Examples

```r
data(usa)
carto1 <- cartogramR(usa, "electors64", options=list(verbose=1, L=256))
plot(carto1)
```

check_ring_dir

Polygon rings directions are checked and corrected if asked.

## Description

Polygon ring are seen from above: exterior ring counter clockwise, holes clockwise

## Usage

check_ring_dir(polygons, check_only = TRUE)

## Arguments

polygons a sfc object which contains simple feature geometry of types POLYGON or MULTIPOLYGON

check_only a boolean which indicates if the function only checks the ring direction (check_only=TRUE) or checks and corrects the polygon direction (check_only=FALSE)

## Value

Either a logical vector which indicates if line i of polygons is in the right direction (TRUE) or not or the corrected sfc object

## Examples

```r
data(usa)
all(check_ring_dir sf::st_geometry(usa), check_only=TRUE))
```
dist Between vertices Analyse some of the grid options

Description

Analyse some of the grid options

Usage

dist Between vertices (data)

Arguments

data a sf object to be used in cartogram.

Value

a ‘dbv.cartogramR‘ object which is a data-table which contains distance between vertices (‘dbv‘) and polygons names (‘L1‘, ‘L2‘, ‘L3‘) inherited from [sf::st coordinates]

Examples

data (usa)
dbv <- dist Between vertices (data = usa)
summary (dbv)

france \_dept

Map of the population of mainland France year 2018

Description

This data set is a basemap of mainland France with the population in 2018 (pop2018), the number of physicians in 2018 (n physicians), the number of general practitioner in 2018 (n gp) and the number of general practitioner for 100000 inhabitants in 2018 (n gp per 100000) in each depart- ment (dept_name or id).

Usage

data(france \_dept)

Format

A sf object containing 8 columns of data and the geometry Projected CRS: RGF93 / Lambert-93
(EPSG : 2154)
## Source

https://www.data.gouv.fr/fr/datasets/admin-express/#_

## References

* https://www.insee.fr/fr/statistiques/2012713#tableau-TCRD_004_tab1 departements

* https://www.insee.fr/fr/statistiques/2012677#tableau-TCRD_068_tab1 departements

france_rivers

Layer of the main rivers of France

## Description

This data set is a basemap of mainland french rivers (name or id).

## Usage

data(france_rivers)

## Format

A sf object containing 2 columns of data and the geometry Projected CRS: RGF93 / Lambert-93 (EPSG: 2154)

## Source

https://geoservices.ign.fr/documentation/diffusion/telechargement-donnees-libres.html

fromCoord_polygon

Transform from coordinates system used in the polygons to coordinates system used in flow based cartogram

## Description

Apply the mapping from the coordinates system used in the polygons (characterised by the CRS) to the coordinates system used in flow based cartogram

## Usage

fromCoord_polygon(coord, carto)
### Arguments

<table><tr><td>coord</td><td>a vector of length 2 or a two columns matrix containing xy coordinates to transform</td></tr><tr><td>carto</td><td>a cartogramR object</td></tr></table>

### Value

a vector of length 2 or a two columns matrix containing xy coordinates in the coordinate systems of polygons used to build the cartogram

### Examples

```r
data(usa)
carto <- cartogramR(usa, "electors64")
fromCoord_polygon(c(-0.007, -0.348), carto)
```

<table><tr><td>geomCartogramR</td><td>Apply the deformation used to build a cartogram to a set of simple geometry coordinates</td></tr></table>

### Description

Apply the deformation used to build a cartogram to a set of simple geometry coordinates. The resulting simple geometry object can be used to add geometry features on the cartogram.

### Usage

```
geomCartogramR(sfgeom, carto, verbose = FALSE)
```

### Arguments

<table><tr><td>sfgeom</td><td>a sf or a sfc object which contains simple feature geometry of types in the following POINT, MULTIPOINT, LINESTRING, MULTILINESTRING, POLYGON, 'MULTIPOLYGON'</td></tr><tr><td>carto</td><td>a cartogramR object</td></tr><tr><td>verbose</td><td>a boolean object to set on verbose mode (default to FALSE)</td></tr></table>

### Value

a sf or a sfc object which contains simple feature geometry transformed
## Examples

```
data(usa)
carto <- cartogramR(usa, "electors64")
LA <- sf::st_sfc(cf::st_point(c(-118.243685, 34.052234)))
sf::st_crs(LA) <- 4326
moregeom <- geomCartogramR(LA, carto)
plot(carto)
plot(moregeom, add=TRUE, col=2, pch=15)
```

<table><tr><td>grid_analysis</td><td>Analyse some of the grid options</td></tr></table>

## Description

Analyse some of the grid options

## Usage

`grid_analysis(data, gridpower2 = 8:11, pf = 1.5, verbose = FALSE)`

## Arguments

<table><tr><td>data</td><td>a sf object to be used in cartogram.</td></tr><tr><td>gridpower2</td><td>a vector of exponent (to be raised at the power of 2) that gives the log2(size) of the grid (default to '8:11')</td></tr><tr><td>pf</td><td>Determines space between map and boundary (default to 1.5)</td></tr><tr><td>verbose</td><td>a boolean object to set on verbose mode (default to 'TRUE')</td></tr></table>

## Value

a 'gridanalysis.cartogramR' object which is a matrix

## Examples

```
data(usa)
ga <- grid_analysis(data=usa, gridpower2=4:8, verbose=TRUE)
summary ga
```
<table><tr><td>makeLayer</td><td>Make a layer</td></tr></table>

**Description**

Create a sfc object containing final centers, original centers, centers displacement, original graticule or final graticule.

**Usage**

```
makeLayer(
  x,
  type = c("finalCenters", "originalCenters", "centersTranslation",
            "finalGraticule", "originalGraticule")
)
```

**Arguments**

<table><tr><td>x</td><td>a cartogramR object</td></tr><tr><td>type</td><td>a character string giving the type of layer: - "finalCenters": if method is dcn, <code>sf::st_centroid</code> is applied on deformed/cartogram region ; if method is gsm or gn (ie flow based), initial "centers" are calculated and the cartogram deformation is applied on these "centers" giving the finalCenters. - "originalCenters" if method is dcn, <code>sf::st_centroid</code> is applied on original regions); if method is gsm or gn (ie flow based), initial "centers" are calculated using cartogramR center option see <code>cartogramR_options</code>. - "centersTranslation" linestring giving the movement of centers due to the deformation used to have the cartogram - "finalGraticule" (method gsm or gn) graticule obtained by the cartogram algorithm - "originalGraticule" (method gsm or gn) graticule used by the cartogram algorithm</td></tr></table>

**Value**

a sfc object

<table><tr><td>plot.cartogramR</td><td>Plot a cartogram object</td></tr></table>

**Description**

Plot a cartogram object

**Usage**

```
## S3 method for class 'cartogramR'
plot(x, ...)
```
### Arguments

* `x` a cartogram object

* `\dots` arguments passed to or from other methods.

### Value

No return value, called for side effects

### Examples

```r
data(usa)
carto <- cartogramR(usa, "electors64")
plot(carto)
```

```r
plot.dbv.cartogramR Plot a dbv.cartogram object
```

### Description

Plot a dbv.cartogram object

### Usage

```r
## S3 method for class 'dbv.cartogramR'
plot(x, which = 1:2, ask = TRUE, key = TRUE, last = 10, probminx = 0.9, ...)
```

### Arguments

* `x` a dbv.cartogram object

* `which` if a subset of the plots is required, specify a subset of the numbers 1:2

* `ask` logical; if TRUE, the user is asked before each plot, see `par(ask=.)`

* `key` logical; if TRUE, a legend is drawn

* `last` draw the density of distance between vertices for the last coordinates

* `probminx` the sample quantiles (of distance between vertices) corresponding to the probability is used as a minimum of x-axis for the density plot (used only if last is NULL)

* `\dots` arguments passed to or from other methods.

### Details

The first plot is the density of distance between consecutive vertices by region. Only the upper quantiles are shown. The second plot is a barplot by region of the number of vertices divided by the perimeter of the region
Value

No return value, called for side effects

Examples

```r
data(usa)
precarto <- precartogramR(usa, method="dcn")
plot(precarto)
```

```r
plot.gridanalysis.cartogramR
```

Plot a gridanalysis.cartogram object

Description

Plot a gridanalysis.cartogram object

Usage

```r
## S3 method for class 'gridanalysis.cartogramR'
plot(
  x,
  nthsmallest = 5,
  redrawxaxis = TRUE,
  type = "b",
  xlab = NULL,
  ylab = NULL,
  ylim = c(0, 20),
  ...
)
```

Arguments

<table><tr><td>x</td><td>a gridanalysis.cartogram object</td></tr><tr><td>nthsmallest</td><td>plot only the nthsmallest values among all polygons</td></tr><tr><td>redrawxaxis</td><td>if TRUE redraw ticks and labels of x axe at grid size on log scale</td></tr><tr><td>type</td><td>character string (length 1 vector) or vector of 1-character strings indicating the type of plot for each polygons, see graphics::matplot for all possible types.</td></tr><tr><td>xlab</td><td>titles for x axe, as in graphics::matplot.</td></tr><tr><td>ylab</td><td>titles for y axe, as in graphics::matplot.</td></tr><tr><td>ylim</td><td>ranges of y axe, as in graphics::matplot.</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>
Value

No return value, called for side effects

Examples

```
data(usa)
precarto <- precartogramR(usa, method="gsm", pf=1.2, verbose=TRUE)
plot(precarto)
```

precartogramR

Make a pre cartogram analysis

Description

Make a pre cartogram analysis

Usage

```
precartogramR(
  data,
  method = c("gsm", "gn", "dcn", "GastnerSeguyMore", "GastnerNewman",
    "DougenikChrismanNiemeyer"),
  gridpower2 = 8:11,
  pf = 1.5,
  verbose = FALSE
)
```

Arguments

<table><tr><td>data</td><td>a sf object which contains at least two columns: obviously a geometry column (giving the map) and a column which contains a count by region (leading to a density by region, density to be equalized by deformation). Each row of data is a region and contains the simple feature geometry of type POLYGON or MULTIPOLYGON. Polygon ring directions are not checked but exterior ring must counter clockwise and holes clockwise (use option check-ring-dir of sf::st_read to achieve the right orientation of ring direction on import or use check-ring-dir function)</td></tr><tr><td>method</td><td>the method to be used, can be one of the following: gsm or GastnerSeguyMore (default), gn or GastnerNewman, dcn or DougenikChrismanNiemeyer.</td></tr><tr><td>gridpower2</td><td>a vector of exponent (to be raised at the power of 2) that gives the log2(size) of the grid (default to 8:11); meaningful for method gsm or GastnerSeguyMore (default), gn or GastnerNewman</td></tr><tr><td>pf</td><td>Determines space between map and boundary (default to 1.5); meaningful for method gsm or GastnerSeguyMore (default), gn or GastnerNewman</td></tr></table>
<table><tr><td>verbose</td><td>a boolean object to set on verbose mode (default to FALSE); meaningful for method gsm or GastnerSeguyMore (default), gn or GastnerNewman</td></tr></table>

### Value

either a `dbv.cartogramR` object (if method is `dcn` or `DougenikChrismanNiemeyer`) see `dist_between Vertices` for details or a `gridanalysis.cartogramR` (if method is `gsm` or `GastnerSeguyMore` (default), `gn` or `GastnerNewman`) see `grid_analysis` for details

### References

* Dougenik, J., Chrisman, R. & Niemeyer, D. (1985). An algorithm to construct continuous area cartograms. Professional Geographer **37**: 75-81.

* Gastner, M. & Newman, M.E.J. (2004). Diffusion-based method for producing density equalizing maps. *Proc. Natl. Acad. Sci. USA*, **101**:7499-7504

* Gastner, M., Seguy, V. & More, P. (2018). Fast flow-based algorithm for creating density-equalizing map projections. *Proceedings of the National Academy of Sciences USA*, **115**:E2156-E2164

### Examples

```r
data(usa)
precarto <- precartogramR(usa)
plot(precarto)
summary(precarto)
```

```r
print.cartogramR Print a cartogram object
```

### Description

Print a cartogram object

### Usage

```r
## S3 method for class 'cartogramR'
print(x, ...)
```

### Arguments

<table><tr><td>x</td><td>a cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>

### Value

No return value, called for side effects
print summaries of a cartogram object

## Description

Print a summary of a cartogram object

## Usage

## S3 method for class 'summary.cartogramR'
print(x, ...)

## Arguments

x a summary.cartogramR object

\dots arguments passed to or from other methods. The following argument is available at this level: digits, the number of significant digits to use when printing.

## Value

x.

## Examples

data(usa)
carto <- cartogramR(usa, "electors64")
summary(carto)

## Errors of a cartogram object

## Description

Errors of a cartogram object

## Usage

## S3 method for class 'cartogramR'
residuals(object, ...)
### Arguments

<table><tr><td>object</td><td>a cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods. The following arguments are available: - type; a character string giving the type of residuals (see details) - "relative error" - "error" - "symmetric difference" - center ; a character string giving the type of center: - "point_on Cole" (st_point_on Cole applied on original and on deformed/cartogram region). - "deformed_center" (the center function, see cartogramR_options, is applied on region and this center follows the deformation giving the center on the deformed/cartogram region) - "centroid" (centroid of original and deformed/cartogram region). Can be abbreviated.</td></tr></table>

### Details

The error vector contains the values of the differences between actual area of regions in the cartogram and theoretical area (obtained with conservation of total area and constant density over region in the final cartogram)

Relative error are the error vector divided by the theoretical area

Symmetric difference are the symmetric difference between actual area of regions in the cartogram and the original area. Each region is scaled to have an area equal to 1 and centered around the chosen center.

### Value

A numeric vector which contains for each region observed area minus theoretical area

### Examples

data(usa)
carto <- cartogramR(usa, "electors64")
residuals(carto)

summary.cartogramR Summary of a cartogram object

### Description

Summary of a cartogram object

### Usage

## S3 method for class 'cartogramR'
summary(object, ...)
### Arguments

<table><tr><td>object</td><td>a cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods. The following arguments are available: - digits integer, used for number formatting with signif if not specified (i.e., [missing](.), [signif]() will not be called anymore (since \R >= 3.4.0, where the default has been changed to only round in the print and format methods). - quantile.type integer code used in quantile(*, type=quantile.type). - center character string code used in residuals.cartogramR.</td></tr></table>

### Value

A summary.cartogramR object: a list with the following components:

* `qrr`, the summary of absolute relative residuals

* `qres`, the summary of absolute residuals

* `qsymdiff`, the summary of all pairwise symmetric difference between two scaled (multi)polygons representative of two regions.

### Examples

```r
data(usa)
carto <- cartogramR(usa, "electors64")
summary(carto)
```

```
summary.dbv.cartogramR
```

*Summary of a dbv.cartogram object*

### Description

Summary of a dbv.cartogram object

### Usage

```r
## S3 method for class 'dbv.cartogramR'
summary(object, ...)
```

### Arguments

<table><tr><td>object</td><td>a dbv.cartogramR object</td></tr><tr><td>\dots</td><td>arguments passed to or from other methods.</td></tr></table>
Value

a data-table which contains by region (L3)

• the sample quantiles corresponding to the probability 0.8, 0.85, ...,1

• the total number of vertices divided by the perimeter of the region (the sum of all polygons perimeter of the region, NbyPerim)

Examples

data(usa)
dbv <- dist_between Vertices(data=usa)
summary(dbv)

summary.gridanalysis.cartogramR

Summary of a gridanalysis.cartogram object

Description

Summary of a gridanalysis.cartogram object

Usage

## S3 method for class 'gridanalysis.cartogramR'
summary(object, ...)

Arguments

object a gridanalysis.cartogramR object

\dots arguments passed to or from other methods.

Value

A vector which indicate the grid size necessary to have more than *steps* grid points in each polygon

Examples

data(usa)
ga <- grid_analysis(data=usa, gridpower2=4:9)
summary(ga)
<table><tr><td>toCoord_polygon</td><td>Transform from coordinates system used in flow based cartogram to coordinates system used in the polygons</td></tr></table>

**Description**

Apply the mapping from the coordinates system used in flow based cartogram to the coordinates system used in the polygons (characterised by the CRS)

**Usage**

`toCoord_polygonkoponygon协调)`

**Arguments**

coord a vector of length 2 or a two columns matrix containing xy coordinates to transform

carto a cartogramR object

**Value**

a vector of length 2 or a two columns matrix containing xy coordinates in the coordinate systems of polygons used to build the cartogram

**Examples**

data(usa)
carto <- cartogramR(usa, "electors64")
toCoord_polygon(c(256,256), carto)

<table><tr><td>usa</td><td>Map of the number of electors in each state of the USA</td></tr></table>

**Description**

This data set is a basemap of the conterminous USA with the number of electors in the 49 states from 1964 to 2020.

**Usage**

`data(usa)`
Format

A sf object containing 24 columns of data and the geometry. Projected CRS: US National Atlas Equal Area (EPSG:2163)
Index

* datasets

france_dept, 9
france_rivers, 10
usa, 22

as.sf, 2
as.sf.cartogramR, 3
as.sfc, 3
as.sfc.cartogramR, 4
as.sfmultipolygon, 4

cartogramR, 5, 6, 7
cartogramR_options, 5, 6, 6, 13, 19
check_ring_dir, 5, 8, 16

dist_betweenVertices, 9, 17

france_dept, 9
france_rivers, 10
fromCoordPolygon, 10

geomCartogramR, 11
graphics::matplot, 15
grid_analysis, 12, 17

makeLayer, 13

par, 14
plot.cartogramR, 13
plot.dbv.cartogramR, 14
plot.gridanalysis.cartogramR, 15
precartogramR, 16
print.cartogramR, 17
print_summary.cartogramR, 18

residuals.cartogramR, 18, 20

sf::st_centroid, 7, 13
sf::st_point_onSurface, 7
sf::st_read, 5, 16
st_point_onSurface, 5, 19

summary.cartogramR, 19
summary.dbv.cartogramR, 20
summary.gridanalysis.cartogramR, 21
toCoordPolygon, 22

usa, 22