---
title: "Visualizing Philippine Roll-on/Roll-off 'RoRo' Connectivity with roroph"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Visualizing Philippine Roll-on/Roll-off 'RoRo' Connectivity with roroph}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r dependencies, include=FALSE}
# Internal knitr settings
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

#Only execute the map if all dependencies are present
vignette_deps <- c("rnaturalearth", "rnaturalearthdata", "sf", 
                   "ggrepel", "dplyr", "ggspatial", "ggplot2")
all_present <- all(sapply(vignette_deps, requireNamespace, quietly = TRUE))
knitr::opts_chunk$set(eval = all_present)
```

The `roroph` package provides standardized & machine-readable data for the Philippine Nautical Highway as of the 2024-2026 operational state. This guide shows how to map the 108 bidirectional links to visualize regional connectivity within the Philippines.This is complete with GADM-standardized naming, geospatial coordinates, and metrics such as distance, travel time, and vessel frequency, supporting other analyses other than mere visualization.

# Setup

We will use `ggplot2` for plotting and `sf` for spatial handling.

```{r setup, message = FALSE, warning = FALSE}
library(roroph)       
library(rnaturalearth) 
library(sf)
library(ggrepel)
library(dplyr)
library(ggspatial)
library(ggplot2)

# Load the dataset
data("roro_routes")
```

# Mapping the Core Philippine Maritime Network

We can visualize the RoRo links as segments connecting provincial capitals. We'll color-code them by their MARINA Highway classification (Western, Central, Eastern, or Missionary).

```{r map-network, fig.width=6, fig.height=10, fig.align='center', out.width="100%"}

# 1. Required Libraries
library(roroph)
library(rnaturalearth)
library(sf)
library(ggrepel)
library(dplyr)
library(ggspatial)

# 2. Data Preparation
ph_land <- ne_countries(scale = "medium", country = "Philippines", returnclass = "sf")

roro_viz <- roro_routes %>%
  mutate(
    highway_type = case_when(
      grepl("WNH", marina_code) ~ "Western",
      grepl("CNH", marina_code) ~ "Central",
      grepl("ENH", marina_code) ~ "Eastern",
      grepl("MR", marina_code)  ~ "Missionary",
      TRUE ~ "Other"
    ),
    highway_type = factor(highway_type, levels = c("Western", "Central", "Eastern", "Missionary"))
  )

hubs_to_label <- roro_viz %>%
  group_by(from_prov) %>%
  summarise(
    total_freq = sum(freq_daily, na.rm = TRUE),
    lon = first(from_lon),
    lat = first(from_lat),
    .groups = "drop"
  ) %>%
  arrange(desc(total_freq)) %>%
  slice(unique(c(1:15, which(from_prov %in% c("Batanes", "Tawi-Tawi"))))) %>%
  mutate(
    lon = case_when(
      from_prov == "Cebu"      ~ 123.75, 
      from_prov == "Bohol"     ~ 124.20,
      from_prov == "Samal"     ~ 125.75, 
      from_prov == "Tawi-Tawi" ~ 119.95,
      TRUE ~ lon
    ),
    lat = case_when(
      from_prov == "Bohol"     ~ 9.85,
      from_prov == "Samal"     ~ 7.00,
      from_prov == "Tawi-Tawi" ~ 5.05,
      TRUE ~ lat
    )
  )

# 3. High-Fidelity Execution (Google Maps/Explorer Vibe)
ggplot() +
  # LAYER 1: The Routes (Placed FIRST so they are 'behind' the land)
  geom_segment(data = roro_viz %>% arrange(freq_daily), 
               aes(x = from_lon, y = from_lat, xend = to_lon, yend = to_lat, 
                   color = highway_type, linewidth = freq_daily), 
               alpha = 0.7, lineend = "round") + 

  # LAYER 2: The Landmass (Placed SECOND to act as a 'Shadow Mask')
  geom_sf(data = ph_land, fill = "#F8F9FA", color = "#DADCE0", linewidth = 0.3) +
  
  # LAYER 3: The Hub Markers (Destination Pins)
  geom_point(data = hubs_to_label, aes(x = lon, y = lat), 
             color = "white", fill = "#1A73E8", size = 1.2, shape = 21, stroke = 1) +
  
  # LAYER 4: Strategic Labels
  geom_text_repel(data = hubs_to_label, 
                  aes(x = lon, y = lat, label = from_prov),
                  size = 3, color = "#3C4043", fontface = "bold",
                  box.padding = 0.4, point.padding = 0.3,
                  segment.color = '#70757A', segment.alpha = 0.8) +

  # Google Palette Scales
  scale_linewidth_continuous(range = c(0.6, 4), name = "Trips per Day") +
  scale_color_manual(values = c(
    "Western"    = "#1A73E8", # Google Blue
    "Central"    = "#34A853", # Google Green
    "Eastern"    = "#EA4335", # Google Red
    "Missionary" = "#70757A"  # Google Grey
  ), name = "Highway System") +
  
  # Theme: Modern Explorer
  theme_minimal() +
  theme(
    # Entire background is now the Ocean Blue
    plot.background = element_rect(fill = "#AADAFF", color = NA),
    panel.background = element_rect(fill = "#AADAFF", color = NA),
    panel.grid = element_blank(),
    
    # Typography
    plot.title = element_text(color = "#202124", face = "bold", size = 18, hjust = 0.5),
    plot.subtitle = element_text(color = "#444b52", size = 10, hjust = 0.5),
    plot.caption = element_text(color = "#444b52", size = 8, hjust = 0.95),
    
    # Floating Legend Card
    legend.position = c(0.15, 0.85),
    legend.background = element_rect(fill = "white", color = "#DADCE0", linewidth = 0.5),
    legend.title = element_text(size = 8, face = "bold", color = "#202124"),
    legend.text = element_text(size = 7, color = "#3C4043"),
    
    axis.text = element_blank(),
    axis.title = element_blank()
  ) +
  labs(
    title = "Philippine Maritime Connectivity",
    subtitle = "RoRo Routes from Batanes to Tawi-Tawi",
    caption = "Data: MARINA/PPA (2026) | Package: roroph"
  ) +
  coord_sf(xlim = c(116.5, 127.5), ylim = c(4.5, 21.5), expand = FALSE)
```

# Network Interpretation and Validation

The network is interpreted through several logistical lenses:

**The Nautical Spine:** The map accurately recreates the Strong Republic Nautical Highway (SRNH) corridors. The heavy weighting of the Western Nautical Highway (Blue) from Batangas through the Mindoro-Panay-Negros corridor reflects its status as the primary logistics artery for consumer goods.

**The Matnog-Allen Bottleneck:** The thick orange segment of the Eastern Nautical Highway (ENH) between Sorsogon and Northern Samar represents the highest-frequency "water bridge" in the country. This link is the critical pivot point for the Pan-Philippine Highway (AH26), where maritime frequency directly dictates national land-trucking efficiency.

**Cebu as the Central Hub:** The "hub-and-spoke" topology of the Central Nautical Highway (Green) highlights Cebu’s role as the maritime heart of the Visayas, facilitating distributed connectivity rather than a linear transit spine.

**Missionary Route Expansion:** The presence of low-frequency Missionary Routes (Grey) extending to Batanes, Palawan, and Tawi-Tawi captures the MARINA 2026 initiatives designed to bridge the "connectivity gap" in geographically isolated and disadvantaged areas (GIDA).

# Transport Analysis: Capacity vs. Distance

The `roroph` package allows us to move beyond visualization and into **Transport Modeling.** By utilizing vessel frequency and nautical distance, we can identify how capacity is allocated across the archipelago's diverse geography.

```{r analysis, warning=FALSE, fig.width=8, fig.height=5, out.width="100%"}

# --- Step 1: Initialize the Capacity vs. Distance Analysis ---
# We map passenger capacity against nautical distance to identify regional archetypes
ggplot(roro_routes, aes(x = dist_nm, y = pax_cap, color = from_region)) +
  
  # Step 2: Plot the Data Points
  # We use jitter to separate overlapping points, revealing 'clusters' of standard vessel sizes
  geom_jitter(size = 2.2, alpha = 0.5, width = 1.5, height = 5) +
  
  # Step 3: Apply the "Maritime Reality" Curve
  # LOESS smoothing identifies non-linear patterns that a simple straight line would miss
  geom_smooth(method = "loess", se = TRUE, alpha = 0.1, linewidth = 1) +
  
  # Step 4: Regional Color Coding
  # Defining a consistent palette to distinguish Luzon, Visayas, and Mindanao logistics
  scale_color_manual(values = c("Luzon" = "#e74c3c", "Visayas" = "#3498db", "Mindanao" = "#2ecc71"), 
                     name = "Origin Region") +
  
  # Step 5: Branding and Documentation
  # Setting clear titles and integrating the dev's signature in the caption
  labs(
    title = "REGIONAL MARITIME CAPACITY SCALING",
    subtitle = "Vessel Capacity (Pax) vs. Nautical Distance across the Philippine Archipelago",
    x = "Route Distance (Nautical Miles)",
    y = "Passenger Capacity per Trip",
    caption = "Source: roroph | dev: NJ Talingting | 2026 Simulation Framework"
  ) +
  
  # Step 6: Professional Science Styling
  # Using theme_minimal for a clean, publication-ready aesthetic
  theme_minimal(base_size = 11) +
  theme(
    plot.title = element_text(face = "bold", size = 14, color = "#2c3e50"),
    plot.subtitle = element_text(size = 10, color = "#7f8c8d", margin = margin(b = 15)),
    
    # Refining the caption to act as a definitive 'Verdict' space
    plot.caption = element_text(size = 8.5, color = "#34495e", hjust = 0, lineheight = 1.2, margin = margin(t = 20)),
    
    panel.grid.minor = element_blank(),
    legend.position = "bottom",
    legend.title = element_text(face = "bold"),
    axis.title = element_text(face = "bold", size = 9)
  )

```

## Interpretation

This analysis reveals that Philippine maritime capacity does not follow a linear physics model. Instead, it is a reflection of Regional Logistics Archetypes:

**The Visayan "Short-Haul" Hub:** High density of large-capacity vessels over short distances, reflecting the intense connectivity of the Central Spine RoRo Route.

**Mindanao's Frontier Connectivity:** Longer distances with specialized vessel scaling, showing a reliance on strategic port hubs like Davao and Cagayan de Oro.

**Luzon's Hub-and-Spoke:** A clear stratification of capacity that centers on the Batangas-Mindoro corridor.

## Conclusion

The `roroph` package serves as a foundational tool for understanding the spatial architecture of the Philippine maritime network. By providing standardized GADM-compliant provincial links alongside critical transport metrics, it enables researchers to:

1.  Identify **logistical bottlenecks** within the National Nautical Highway.

2.  Model **regional accessibility** for economic development studies.

3.  Simulate **disaster-response scenarios** by identifying alternative inter-island routes.

As the first R-native dataset for this domain, `roroph` bridges the gap between raw administrative records and spatial analysis for the Philippines.

## Disclaimer

The maritime industry in the Philippines is highly dynamic. While the routes, distances, and MARINA codes in this package are based on official 2024–2026 administrative reports from the **Maritime Industry Authority (MARINA)** and the **Philippine Ports Authority (PPA)**, users should note:

**Operational Status:** Routes may be temporarily suspended due to weather (e.g., tropical cyclones), maintenance, or regulatory grounding of specific fleets.

**Variable Metrics:** Values for `freq_daily` (frequency) and `pax_cap` (capacity) are representative averages. Actual daily throughput fluctuates based on seasonal demand (e.g., Holy Week, Christmas) and private operator schedules.

**Navigational Use:** This dataset is for **statistical and spatial modeling purposes only**. It is **NOT** intended for actual marine navigation. Always consult official Notices to Mariners (NOTAMs) and PPA port advisories for real-time travel planning.

**User Responsibility:** Users are encouraged to verify critical data points against the latest [MARINA sectoral releases](https://marina.gov.ph) when using this package for policy-making, logistics planning, among other academic and commercial usage.