---
title: <br><center>Cartographical maps and networks</center>
date:  "August 2022" 
author: 
  - name: <center>Antonio Rivero Ostoic</center><div style="margin-bottom:-20px;"> </div>
    affiliation: <center>Aarhus University</center><div style="margin-bottom:-20px;"> </div>
    email: <center>jaro@cas.au.dk</center>
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Cartographical maps and networks}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

<style type="text/css">
h1.title {
  text-align: center; font-size: 20pt; color: #400040; 
}
h2 {
  font-size: 18pt; color: #400040;
}
h3 {
  font-size: 14pt; color: #400080;
}
h4 {
  text-align: center; color: DarkRed;
}
</style>



```{r setup, echo=FALSE, message=FALSE}
knitr::opts_chunk$set(echo=TRUE,error=TRUE)
knitr::opts_chunk$set(comment = "")
library("sdam")
```

```{r set-options, echo=FALSE, cache=FALSE}
options(width = 96)
```


<div style="margin-bottom:20px;"> </div>


### Preliminaries
Install and load a version of `"sdam"` package.

```{r, echo=TRUE, eval=FALSE}
install.packages("sdam") # from CRAN
devtools::install_github("sdam-au/sdam") # development version
devtools::install_github("mplex/cedhar", subdir="pkg/sdam") # legacy version R 3.6.x
```
<div style="margin-bottom:10px;"> </div>
```{r}
# load and check versions
library(sdam)
packageVersion("sdam")
```

<div style="margin-bottom:40px;"> </div>


## Cartographical maps

Cartographical maps of Roman provinces under Emperors Trajan and Hadrian (year 117AD), and Italian regions 
under Emperor Augustus (year 27 BC) are part of the suite of datasets of the `"sdam"` package. 
For instance, four cartographical maps related to the Roman Empire in the antiquity period are available in 
dataset `"retn"` that is loaded by function `plot.map()` to depict cartographical maps and transportation systems. 
`plot.map()` is an interface that also invokes datasets `"rpmp"` for names and vector shapes of Roman provinces and 
regions, and dataset `"rpmcd"` for including map captions and dates in the plot. 


### Political division

Plotting political divisions of the Roman Empire needs the `'type'` argument of function `plot.map()` as well. 


<div class="repdiv">
<div class="row">
<div class="col-md-6">
```{r}
# Roman provinces
plot.map(type="rp")
```
</div>
<div class="col-md-6">
```{r}
# senatorial/imperial division
plot.map(type="si", main="Roman Empire (AD 117)")
```
</div>
</div>
</div>


<div style="margin-bottom:40px;"> </div>


### Roman provinces and regions

* Roman provinces and regions shapes and colours for `plot.map()` are in dataset `"rpmp"`, 
while the acronyms in `x` are as in dataset `"rp"`. 



<div class="repdiv">
<div class="row">
<div class="col-md-4">
```{r}
# Italian peninsula silhouette
plot.map(x="Ita")
```
</div>
<div class="col-md-4">
```{r}
# Roman province with establishment date
plot.map(x="Bri", date=TRUE)
```
</div>
<div class="col-md-4">
```{r}
# Italian region
plot.map(x="VeH", cap=FALSE, fsize=12)
```
</div>
</div>
</div>

<div style="margin-bottom:40px;"> </div>


### Transportation system

A `plain` cartographical map with a Roman transportation system made of settlements and terrestrial and maritime routes 
is possible with the `type` argument in `plot.map()`, or else by specifying with arguments 
`settl`, `roads`, and `shipr` for the settlements and this routes in the transportation system.

<div class="retnet">
<div class="row">
<div class="col-md-6">
```{r}
# settlements and main roads
plot.map(type="plain", settl=TRUE, roads=TRUE)
```
</div>
<div class="col-md-6">
```{r}
# settlements and main shipping routes
plot.map(type="plain", settl=TRUE, shipr=TRUE)
```
</div>
</div>
</div>


<div style="margin-bottom:60px;"> </div>


## Graphs

### Shipwrecks network

Graph representations of the transport network is possible with packages `"multigraph"` and 
`"multiplex"`. 

Access to the shipwrecks dataset.

```{r}
# shipwrecks dataset
sw <- system.file("extdata","StraussShipwrecks.csv",package="sdam") |> 
  read.csv(sep=";")
```

```{r}
# variables are checked
colnames(sw)
```

<div style="margin-bottom:20px;"> </div>

A system of maritime routes is found in variables `Place.of.origin` and `Place.of.destination`, 
which correspond to columns 20 to 21 in `sw`. 
This edge list needs some transformations with functions from packages `"sdam"` and `"multiplex"` 
to be able to plot the shipwrecks network as a directed graph with loops with a force directed layout. 


```{r}
# graph of shipwrecks network
sw[, 20:21] |> 
  sdam::cln(level=2, what=c("(",")"), case=1, na.rm=TRUE) |> 
  multiplex::transf(type="toarray") |> 
  multigraph::multigraph(layout="force", seed=123, loops=TRUE, ecol=4, sel="Rome")
```

<div style="margin-bottom:20px;"> </div>

In this case, a single node is labeled in the graph that represents the shipwrecks network without missing information. 
To keep records with `NA` in the data, function `cln()` has the `'na.rm'` argument to be set to `FALSE`. 

<div style="margin-bottom:40px;"> </div>

References for shipwrecks data are in 

- Vignette [Datasets in `"sdam"` package](../doc/Intro.html) 


<div style="margin-bottom:60px;"> </div>


<div style="margin-bottom:60px;"> </div>

&uml;

<div style="margin-bottom:60px;"> </div>



### See also

#### Vignettes

* [Datasets in `"sdam"` package](../doc/Intro.html)

* [Re-encoding `people` in the `EDH` dataset](../doc/Encoding.html)

* [Dates and missing dating data](../doc/Dates.html)


<div style="margin-bottom:30px;"> </div>

#### Reference Manual

* [sdam: Digital Tools for the SDAM Project at Aarhus University](../html/sdam-package.html)
* [`"sdam"` manual](https://github.com/mplex/cedhar/blob/master/typesetting/reports/sdam.pdf)

<div style="margin-bottom:30px;"> </div>

#### Project

* [Release candidate version](https://github.com/sdam-au/sdam)
* [Code snippets using `"sdam"`](https://github.com/sdam-au/R_code)
* [Social Dynamics and complexity in the Ancient Mediterranean project](https://sdam-au.github.io/sdam-au/)

<div style="margin-bottom:60px;"> </div>

&nbsp;
