README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  message = FALSE,
  warning = FALSE,
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-"
)

bagyo_colours <- c(
  "#e5be72", "#4d4d4d", "#5ada3d", "#5630d3", "#e51707",
  "#9c5e60", "#465b92", "#4b876e", "#152127", "#5d0505"
)

library(bagyo)
library(tibble)
```

# bagyo: Philippine Tropical Cyclones Data <img src="man/figures/logo.png" width="200" align="right" />

<!-- badges: start -->
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
[![CRAN status](https://www.r-pkg.org/badges/version/bagyo)](https://CRAN.R-project.org/package=bagyo){.pkgdown-release}
[![cran checks](https://badges.cranchecks.info/worst/bagyo.svg)](https://cran.r-project.org/web/checks/check_results_bagyo.html)
[![CRAN](https://img.shields.io/cran/l/bagyo.svg)](https://CRAN.R-project.org/package=bagyo)
[![CRAN](http://cranlogs.r-pkg.org/badges/bagyo)](https://cran.r-project.org/package=bagyo)
[![CRAN](http://cranlogs.r-pkg.org/badges/grand-total/bagyo)](https://cran.r-project.org/package=bagyo)
[![R-CMD-check](https://github.com/panukatan/bagyo/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/panukatan/bagyo/actions/workflows/R-CMD-check.yaml)
[![R-hub](https://github.com/panukatan/bagyo/actions/workflows/rhub.yaml/badge.svg)](https://github.com/panukatan/bagyo/actions/workflows/rhub.yaml)
[![test-coverage](https://github.com/panukatan/bagyo/actions/workflows/test-coverage.yaml/badge.svg)](https://github.com/panukatan/bagyo/actions/workflows/test-coverage.yaml)
[![Codecov test coverage](https://codecov.io/gh/panukatan/bagyo/graph/badge.svg)](https://app.codecov.io/gh/panukatan/bagyo)
[![CodeFactor](https://www.codefactor.io/repository/github/panukatan/bagyo/badge)](https://www.codefactor.io/repository/github/panukatan/bagyo)
[![DOI](https://zenodo.org/badge/314686124.svg)](https://zenodo.org/doi/10.5281/zenodo.10972234){.pkgdown-release}
[![DOI](https://img.shields.io/badge/DOI-10.32614/CRAN.package.bagyo-blue)](https://doi.org/10.32614/CRAN.package.bagyo){.pkgdown-release}
<!-- badges: end -->

Oceans and seas significantly impact continental weather, with evaporation from the sea surface driving cloud formation and precipitation.
Tropical cyclones, warm-core low-pressure systems, form over warm oceans where temperatures exceed 26°C, precipitated by the release of latent heat from condensation.
These cyclones, known by various names depending on the region, have organised circulations and develop primarily in tropical and subtropical waters, except in regions with cooler sea surface temperatures and high vertical wind shears.
They reach peak intensity over warm tropical waters and weaken upon landfall, often causing extensive damage before dissipating.

The Philippines frequently experiences tropical cyclones (called ***bagyo*** - pronounced /baɡˈjo/, [bɐɡˈjo] - in the Filipino language) because of its geographical position.
These cyclones typically bring heavy rainfall, leading to widespread flooding, as well as strong winds that cause significant damage to human life, crops, and property.
Data on cyclones are collected and curated by the [Philippine Atmospheric, Geophysical, and Astronomical Services Administration (PAGASA)](https://www.pagasa.dost.gov.ph/).

This package contains Philippine tropical cyclones data from 2017 to 2022 in a machine-readable format.
It is hoped that this data package provides an interesting and unique dataset for data exploration and visualisation as an adjunct to the traditional [`iris`](https://stat.ethz.ch/R-manual/R-devel/library/datasets/html/iris.html) dataset and to the current [`palmerpenguins`](https://allisonhorst.github.io/palmerpenguins/) dataset.

## Installation

You can install `bagyo` from [CRAN](https://cran.r-project.org) with:

```{r install-cran, echo = TRUE, eval = FALSE}
install.packages("bagyo")
```

::: {.pkgdown-devel}
You can install the development version of `bagyo` from [GitHub](https://github.com/panukatan/bagyo) using `pak` with:

```R
## Install pak as needed ----
## install.packages("pak")
pak::pak("panukatan/bagyo")
```

You can also install `bagyo` from the [panukatan R Universe](https://panukatan.r-universe.dev) with:

```{r install-r-universe, eval = FALSE}
install.packages(
  "bagyo",
  repos = c('https://panukatan.r-universe.dev', 'https://cloud.r-project.org')
)
```
:::

Once the `bagyo` package has been installed, the `bagyo` dataset can be loaded into R as follows:

```{r load-dataset}
library(bagyo)
data(package = "bagyo")

bagyo
```

## Usage

### `bagyo` is interesting to summarise

```{r summary}
library(dplyr)

## Get cyclone category mean pressure and speed ----
bagyo |>
  group_by(category_name) |>
  summarise(
    n = n(),
    mean_pressure = mean(pressure), 
    mean_speed = mean(speed)
  )
```

### `bagyo` is useful in learning how to work with dates

```{r working-with-dates}
## Get cyclone category mean duration (in hours) ----
bagyo |>
  mutate(duration = end - start) |>
  group_by(category_name) |>
  summarise(mean_duration = mean(duration))
```

### `bagyo` is great to visualise

```{r barplot, echo = FALSE, fig.align = "center", fig.height = 4}
library(ggplot2)

## Get cyclone category mean duration (in hours) ----
bagyo |>
  mutate(duration = end - start) |>
  group_by(category_name) |>
  summarise(mean_duration = mean(duration)) |>
  ggplot(mapping = aes(x = mean_duration, y = category_name)) +
  geom_col(colour = "#4b876e", fill = "#4b876e", alpha = 0.5) +
  labs(
    title = "Mean duration of cyclones",
    subtitle = "By cyclone categories",
    x = "mean duration (hours)",
    y = NULL
  ) +
  theme_minimal() +
  theme(
    panel.grid.minor.x = element_blank(),
    panel.grid.major.y = element_blank(),
    panel.grid.minor.y = element_blank()
  )
```

```{r scatterplot, echo = FALSE, fig.align = "center", fig.height = 6, fig.width = 8}
## Cyclone speed by presssure ----
bagyo |>
  dplyr::mutate(year = factor(year)) |>
  ggplot(mapping = aes(x = speed, y = pressure)) +
  geom_point(mapping = aes(colour = category_name), size = 3, alpha = 0.5) +
  scale_colour_manual(
    name = NULL,
    values = c(
      "#9c5e60", "#4b876e", "#465b92", "#e5be72", "#5d0505"
    )
  ) +
  labs(
    title = "Cyclone maximum sustained wind speed and maximum central pressure",
    subtitle = "By cyclone categories and year",
    x = "wind speed (km/h)",
    y = "central pressure (hPa)"
  ) +
  facet_wrap(. ~ year, ncol = 3) +
  theme_bw() +
  theme(
    legend.position = "top",
    strip.background = element_rect(
      fill = alpha("#465b92", 0.7), colour = "#465b92"
    ),
    panel.border = element_rect(colour = "#465b92"),
    panel.grid.minor = element_blank()
  )
```

## Citation

To cite `bagyo` in your work, please use the citation provided by a call to the `citation()` function as follows:

```{r citation}
citation("bagyo")
```

You can also use the [citation provided by GitHub](https://github.com/panukatan/bagyo), generated from the information in the project's [CITATION.cff](https://github.com/panukatan/bagyo/blob/main/CITATION.cff) file.

## Community guidelines

Feedback, bug reports and feature requests are welcome; file issues or seek support [here](https://github.com/panukatan/bagyo/issues).
If you would like to contribute to the package, please see our [contributing guidelines](https://panukatan.io/bagyo/CONTRIBUTING.html).

This project is released with a [Contributor Code of Conduct](https://panukatan.io/bagyo/CODE_OF_CONDUCT.html).
By participating in this project you agree to abide by its terms.

<br>
<br>