diff --git a/NAMESPACE b/NAMESPACE index 8040bde..48a8846 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,6 +2,7 @@ export(download_aao) export(download_ao) +export(download_dmi) export(download_enso) export(download_mei) export(download_nao) diff --git a/NEWS.md b/NEWS.md index e8ae03f..4efdce0 100644 --- a/NEWS.md +++ b/NEWS.md @@ -5,6 +5,7 @@ * Skip some tests on CRAN and use CI services to catch errors. * Removed links causing this failures: > Check process probably crashed or hung up for 20 minutes ... killed +* Adds Dipole Mode Index. #42 ## rsoi v0.5.3 * Remove Extended PDO because data is no longer available. diff --git a/R/download-dmi.R b/R/download-dmi.R new file mode 100644 index 0000000..c7408f7 --- /dev/null +++ b/R/download-dmi.R @@ -0,0 +1,81 @@ +#' @export +#' @title Download Dipole Mode Index (DMI) +#' +#' @description Intensity of the IOD is represented by anomalous SST gradient +#' between the western equatorial Indian Ocean (50E-70E and 10S-10N) and the +#' south eastern equatorial Indian Ocean (90E-110E and 10S-0N). +#' This gradient is named as Dipole Mode Index (DMI). +#' When the DMI is positive then, the phenomenon is refereed as the positive +#' IOD and when it is negative, it is refereed as negative IOD. +#' +#' +#' @inheritParams download_oni +#' +#' @return +#' \itemize{ +#' \item Year: Year of record +#' \item Month: Month of record +#' \item Date: Date object that uses the first of the month as a placeholder. Date formatted as date on the first of the month because R only supports one partial of date time +#' \item DMI: Dipole Mode Index +#' } +#' +#' @examples +#' \dontrun{ +#' dmi <- download_dmi() +#' } +#' +#' @references \url{https://psl.noaa.gov/gcos_wgsp/Timeseries/DMI/} +download_dmi <- function(use_cache = FALSE, file = NULL) { + with_cache(use_cache = use_cache, file = file, + memoised = download_dmi_memoised, + unmemoised = download_dmi_unmemoised, + read_function = read_dmi) +} + +download_dmi_unmemoised = function() { + dmi_link = "https://psl.noaa.gov/gcos_wgsp/Timeseries/Data/dmi.had.long.data" + + res = tryCatch( + check_response(dmi_link), + error = function(e) { + message(e) + return(invisible(NULL)) + } + ) + + years = strsplit(trimws(readLines(res, n = 1)), " ")[[1]] + rows = diff(as.numeric(years)) + 1 + months = month.abb + + dmi = read.csv(check_response(dmi_link), # reset connection + header = FALSE, + col.names = c("Year", months), + nrows = rows, + skip = 1, + na.strings = "-9999.000", + sep = "", + stringsAsFactors = FALSE) + + grid = expand.grid(Year = dmi$Year, Month = months) + grid$DMI = c(as.matrix(dmi[, months])) + grid$Month = factor(grid$Month, levels = months) + grid$Date = as.Date(paste0(grid$Year, "-", as.numeric(grid$Month) ,"-01"), "%Y-%m-%d") + + grid <- grid[, c("Year", "Month", "Date", "DMI")] + class(grid) = c("tbl_df", "tbl", "data.frame") + + return(grid) +} + +download_dmi_memoised <- memoise::memoise(download_dmi_unmemoised) + + +read_dmi <- function(file) { + data <- read.csv(file) + data$Date <- as.Date(data$Date) + data$Month <- factor(data$Month, + levels = month.abb) + + class(data) <- c("tbl_df", "tbl", "data.frame") + data +} diff --git a/man/download_dmi.Rd b/man/download_dmi.Rd new file mode 100644 index 0000000..f523f17 --- /dev/null +++ b/man/download_dmi.Rd @@ -0,0 +1,40 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/download-dmi.R +\name{download_dmi} +\alias{download_dmi} +\title{Download Dipole Mode Index (DMI)} +\usage{ +download_dmi(use_cache = FALSE, file = NULL) +} +\arguments{ +\item{use_cache}{logical option to save and load from cache. If `TRUE`, results will be cached in memory +if `file` is `NULL` or on disk if `file` is not `NULL`.} + +\item{file}{optional character with the full path of a file to save the data. If `cache` is `FALSE` but +`file` is not `NULL`, the results will be downloaded from the internet and saved on disk.} +} +\value{ +\itemize{ +\item Year: Year of record +\item Month: Month of record +\item Date: Date object that uses the first of the month as a placeholder. Date formatted as date on the first of the month because R only supports one partial of date time +\item DMI: Dipole Mode Index +} +} +\description{ +Intensity of the IOD is represented by anomalous SST gradient +between the western equatorial Indian Ocean (50E-70E and 10S-10N) and the +south eastern equatorial Indian Ocean (90E-110E and 10S-0N). +This gradient is named as Dipole Mode Index (DMI). +When the DMI is positive then, the phenomenon is refereed as the positive +IOD and when it is negative, it is refereed as negative IOD. +} +\examples{ +\dontrun{ +dmi <- download_dmi() +} + +} +\references{ +\url{https://psl.noaa.gov/gcos_wgsp/Timeseries/DMI/} +} diff --git a/tests/testthat/test_download_.R b/tests/testthat/test_download_.R index 08027bc..60247e8 100644 --- a/tests/testthat/test_download_.R +++ b/tests/testthat/test_download_.R @@ -1,4 +1,4 @@ -indexes <- c("oni", "ao", "nao", "soi", "mei", "npgo", "aao", "pdo") +indexes <- c("oni", "ao", "nao", "soi", "mei", "npgo", "aao", "pdo", "dmi") context("Testing download")