---
title: "India state-level NTL with Bhuvan"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{India state-level NTL with Bhuvan}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
# Live downloads write to the user cache, so skip them on CRAN.
live_ok <- identical(Sys.getenv("NOT_CRAN"), "true") &&
  !is.null(tryCatch(lightson::bhuvan_stats(years = 2024), error = function(e) NULL))

knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  dev.args = list(bg = "transparent"),
  eval     = live_ok
)
```

```{r offline-notice, echo = FALSE, results = "asis", eval = !live_ok}
cat("_Live data were not downloaded when this vignette was built, so its examples were not run. Run this vignette locally to see the output._")
```


ISRO's Bhuvan NTL portal provides pre-aggregated mean radiance for all Indian
states from 2012 to 2024, and WMS raster tiles for any custom region, with no
authentication required.

## All states, all years

```{r}
library(lightson)

df <- bhuvan_stats()
dim(df)
head(df)
```

## Single state time series

```{r}
bihar <- bhuvan_stats(state = "BIHAR")
bihar
```

```{r plot-bihar, fig.width = 7, fig.height = 4}
library(ggplot2)
plot_ntl_trend(bihar,
  region = "Bihar",
  caption = "Source: ISRO Bhuvan NTL portal"
)
```

Radiance nearly 10x from 2012 to 2024.

## Compare states

```{r, fig.width = 7, fig.height = 4}
states <- c("Bihar", "Maharashtra", "Tamil Nadu", "Uttar Pradesh", "Kerala")
plot_ntl_trend(
  df[df$state %in% states, ],
  region   = states,
  subtitle = "Bhuvan state mean radiance (nW/cm^2/sr)",
  caption  = "Source: ISRO Bhuvan NTL portal"
)
```

## Nighttime India from space, 2012 to 2024


```{r}
states_sf <- get_india_admin("state")

years_sel <- c(2012, 2015, 2018, 2021, 2024)
rasters <- tryCatch(
  bhuvan_raster("IND", years = years_sel, bbox_pad = c(0, 0, 0, 3.5)),
  error = function(e) list()
)
```


```{r, fig.width = 11, fig.height = 8, eval = live_ok && length(rasters) > 0}
plot_ntl_panel(
  rasters,
  polygons = states_sf,
  title    = "India at night, 2012 to 2024",
  subtitle = "Bhuvan NTL radiance classes. Boundaries: LGD/SoI.",
  caption  = "Source: ISRO Bhuvan NTL portal",
  ncol     = 3L
)
```

All panels are drawn at the same radiance scale (reference zero). The
sharpest gains are in Bihar, UP, and Odisha after 2015, broadly tracking the
Saubhagya electrification scheme (2017-2019).

## Filter by year range

```{r}
post_2015 <- bhuvan_stats(years = 2015:2024)
nrow(post_2015)
```