diff --git a/DESCRIPTION b/DESCRIPTION index 31281b8..def0fc1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -22,7 +22,7 @@ Imports: sidrar, stringr, janitor, - labelled + labelled, Suggests: testthat (>= 3.0.0), rmarkdown, diff --git a/R/series-database.R b/R/series-database.R index ee153a4..c0d90d5 100644 --- a/R/series-database.R +++ b/R/series-database.R @@ -1,154 +1,214 @@ -# R/series-database.R +utils::globalVariables("br_available_series") + +# ------------------------------------------------------------------- +# Dataset documentation +# ------------------------------------------------------------------- #' Brazilian Economic Series Database #' #' A comprehensive database of Brazilian economic and financial time series #' available through the Central Bank of Brazil's SGS system. #' -#' @format A tibble with 9 rows and 16 columns: +#' @docType data +#' +#' @format A tibble with multiple rows and the following columns: #' \describe{ #' \item{series_id}{SGS code from Central Bank of Brazil} -#' \item{source}{Data source ("BCB" for Central Bank of Brazil)} -#' \item{source_system}{Source system ("SGS" for Time Series Management System)} -#' \item{short_name}{Short name/abbreviation of the series} -#' \item{long_name}{Full descriptive name of the series} -#' \item{description}{Detailed description of what the series measures} -#' \item{category}{Main category (e.g., "Macroeconomic")} -#' \item{sub_category}{Sub-category (e.g., "Inflation", "Exchange Rate")} -#' \item{frequency}{Data frequency ("daily", "monthly")} -#' \item{unit}{Measurement unit ("percent", "BRL")} -#' \item{seasonally_adjusted}{Logical indicating if series is seasonally adjusted} +#' \item{source}{Data source} +#' \item{source_system}{Source system} +#' \item{short_name}{Short name of the series} +#' \item{long_name_pt}{Full name in Portuguese} +#' \item{long_name_en}{Full name in English} +#' \item{description_pt}{Description in Portuguese} +#' \item{description_en}{Description in English} +#' \item{category_pt}{Category in Portuguese} +#' \item{category_en}{Category in English} +#' \item{sub_category_pt}{Sub-category in Portuguese} +#' \item{sub_category_en}{Sub-category in English} +#' \item{frequency}{Data frequency} +#' \item{unit}{Measurement unit} +#' \item{seasonally_adjusted}{Logical} #' \item{start_date}{Series start date} -#' \item{end_date}{Series end date (NA if ongoing)} -#' \item{default_transform}{Suggested default transformation for analysis} -#' \item{suggested_scale}{Suggested scale for visualization} -#' \item{notes}{Additional notes and comments} +#' \item{end_date}{Series end date} +#' \item{default_transform}{Suggested transformation} +#' \item{suggested_scale}{Suggested visualization scale} +#' \item{notes_pt}{Notes in Portuguese} +#' \item{notes_en}{Notes in English} #' } #' -#' @source Central Bank of Brazil - Time Series Management System (SGS) +#' @source Central Bank of Brazil — SGS #' #' @examples -#' # View the entire database #' br_available_series #' -#' # Filter for inflation series -#' dplyr::filter(br_available_series, sub_category == "Inflation") -#' -#' # Find series by ID #' br_available_series[br_available_series$series_id == "433", ] #' +#' br_available_series[br_available_series$series_id == "433", ] "br_available_series" + +# ------------------------------------------------------------------- +# Browse available series +# ------------------------------------------------------------------- + #' Browse Available Economic Series #' -#' Displays a searchable table of available economic and financial series in Brazil. +#' Displays a searchable table of available Brazilian economic series. #' #' @param category Filter by category (optional) #' @param sub_category Filter by sub-category (optional) #' @param source Filter by source (optional) #' @param frequency Filter by frequency (optional) #' @param search_text Text search across all columns (optional) +#' @param language Language for returned labels. Either \code{"pt"} or \code{"en"}. #' #' @return A tibble with available series matching the criteria #' #' @examples -#' # View all available series #' browse_series() -#' -#' # Filter by category #' browse_series(category = "Macroeconomic") -#' -#' # Search for inflation series #' browse_series(search_text = "inflação") #' #' @export -browse_series <- function(category = NULL, sub_category = NULL, - source = NULL, frequency = NULL, search_text = NULL) { - # Verificar se o pacote está carregado - if (!exists("br_available_series")) { - data("br_available_series", package = "brfinance") - } +browse_series <- function(category = NULL, + sub_category = NULL, + source = NULL, + frequency = NULL, + search_text = NULL, + language = c("pt", "en")) { + + language <- match.arg(language) + + data <- get("br_available_series", envir = asNamespace("brfinance")) - data <- br_available_series + # Mapeamento de colunas por idioma + long_name_col <- paste0("long_name_", language) + category_col <- paste0("category_", language) + sub_category_col <- paste0("sub_category_", language) - # Aplicar filtros if (!is.null(category)) { - data <- data[data$category == category, ] + data <- data[data[[category_col]] == category, , drop = FALSE] } if (!is.null(sub_category)) { - data <- data[data$sub_category == sub_category, ] + data <- data[data[[sub_category_col]] == sub_category, , drop = FALSE] } if (!is.null(source)) { - data <- data[data$source == source, ] + data <- data[data$source == source, , drop = FALSE] } if (!is.null(frequency)) { - data <- data[data$frequency == frequency, ] + data <- data[data$frequency == frequency, , drop = FALSE] } - # Busca textual if (!is.null(search_text)) { search_text <- tolower(search_text) - matches <- apply(data, 1, function(row) { - any(grepl(search_text, tolower(row))) - }) - data <- data[matches, ] - } - # Ordenar por short_name - data <- data[order(data$short_name), ] + matches <- apply( + as.data.frame(data), + 1, + function(row) { + any(grepl(search_text, tolower(as.character(row)), fixed = TRUE)) + } + ) - # Retornar apenas colunas mais importantes para visualização - cols_to_show <- c("series_id", "short_name", "long_name", "category", - "sub_category", "frequency", "unit", "start_date") + data <- data[matches, , drop = FALSE] + } - return(data[, cols_to_show]) + # Colunas finais (neutras) + out <- data.frame( + series_id = data$series_id, + short_name = data$short_name, + long_name = data[[long_name_col]], + category = data[[category_col]], + sub_category = data[[sub_category_col]], + frequency = data$frequency, + unit = data$unit, + start_date = data$start_date, + stringsAsFactors = FALSE + ) + + out[order(out$short_name), ] } +# ------------------------------------------------------------------- +# Series information +# ------------------------------------------------------------------- + #' Get Series Information #' -#' Returns detailed information about a specific economic series. +#' Returns detailed metadata about a specific economic series. #' -#' @param series_id The series ID (SGS code from BCB) -#' @param field Specific field to return (optional). If NULL, returns all information. +#' @param series_id The series ID (SGS code) +#' @param field Specific field to return (optional) +#' @param language Language for returned labels. Either \code{"pt"} or \code{"en"}. #' -#' @return A list or character with series information +#' @return A list with series metadata or a single value #' #' @examples -#' # Get all information about IPCA #' get_series_info("433") -#' -#' # Get only the description -#' get_series_info("433", field = "description") +#' get_series_info("433", field = "description", language = "en") #' #' @export -get_series_info <- function(series_id, field = NULL) { - # Verificar se o pacote está carregado - if (!exists("br_available_series")) { - data("br_available_series", package = "brfinance") - } +get_series_info <- function(series_id, + field = NULL, + language = c("pt", "en")) { - data <- br_available_series + language <- match.arg(language) + + data <- get("br_available_series", envir = asNamespace("brfinance")) if (!series_id %in% data$series_id) { - stop("Series ID not found in database. Use browse_series() to see available series.") + stop( + "Series ID not found. Use browse_series() to see available series.", + call. = FALSE + ) } - info <- data[data$series_id == series_id, ] + info <- data[data$series_id == series_id, , drop = FALSE] - if (nrow(info) == 0) { - stop("Series ID not found: ", series_id) - } + # Mapeamento neutro → bilingue + field_map <- c( + long_name = paste0("long_name_", language), + description = paste0("description_", language), + category = paste0("category_", language), + sub_category = paste0("sub_category_", language), + notes = paste0("notes_", language) + ) if (!is.null(field)) { + if (field %in% names(field_map)) { + return(info[[field_map[field]]][[1]]) + } + if (!field %in% names(info)) { - stop("Field '", field, "' not available. Available fields: ", - paste(names(info), collapse = ", ")) + stop( + "Field '", field, "' not available.", + call. = FALSE + ) } - return(info[[field]]) + + return(info[[field]][[1]]) } - return(as.list(info)) + # Retorno completo, já normalizado + list( + series_id = info$series_id, + source = info$source, + source_system = info$source_system, + short_name = info$short_name, + long_name = info[[paste0("long_name_", language)]], + description = info[[paste0("description_", language)]], + category = info[[paste0("category_", language)]], + sub_category = info[[paste0("sub_category_", language)]], + frequency = info$frequency, + unit = info$unit, + seasonally_adjusted = info$seasonally_adjusted, + start_date = info$start_date, + end_date = info$end_date, + default_transform = info$default_transform, + suggested_scale = info$suggested_scale, + notes = info[[paste0("notes_", language)]] + ) } diff --git a/data-raw/create_series_database.R b/data-raw/create_series_database.R index 3ef9c7f..af2ea16 100644 --- a/data-raw/create_series_database.R +++ b/data-raw/create_series_database.R @@ -4,11 +4,10 @@ #' This script creates the comprehensive dataset of Brazilian economic series #' that is included in the brfinance package. -library(tibble) -library(dplyr) -library(readr) - # Dataset completo com 31 séries principais do BCB + +br_available_series <- NULL + br_available_series <- tibble::tibble( series_id = c( # Inflação (6) diff --git a/data/test_series.rda b/data/test_series.rda deleted file mode 100644 index 4e307c4..0000000 Binary files a/data/test_series.rda and /dev/null differ diff --git a/man/br_available_series.Rd b/man/br_available_series.Rd index 54a8d9c..48ff6cb 100644 --- a/man/br_available_series.Rd +++ b/man/br_available_series.Rd @@ -5,28 +5,33 @@ \alias{br_available_series} \title{Brazilian Economic Series Database} \format{ -A tibble with 9 rows and 16 columns: +A tibble with multiple rows and the following columns: \describe{ \item{series_id}{SGS code from Central Bank of Brazil} -\item{source}{Data source ("BCB" for Central Bank of Brazil)} -\item{source_system}{Source system ("SGS" for Time Series Management System)} -\item{short_name}{Short name/abbreviation of the series} -\item{long_name}{Full descriptive name of the series} -\item{description}{Detailed description of what the series measures} -\item{category}{Main category (e.g., "Macroeconomic")} -\item{sub_category}{Sub-category (e.g., "Inflation", "Exchange Rate")} -\item{frequency}{Data frequency ("daily", "monthly")} -\item{unit}{Measurement unit ("percent", "BRL")} -\item{seasonally_adjusted}{Logical indicating if series is seasonally adjusted} +\item{source}{Data source} +\item{source_system}{Source system} +\item{short_name}{Short name of the series} +\item{long_name_pt}{Full name in Portuguese} +\item{long_name_en}{Full name in English} +\item{description_pt}{Description in Portuguese} +\item{description_en}{Description in English} +\item{category_pt}{Category in Portuguese} +\item{category_en}{Category in English} +\item{sub_category_pt}{Sub-category in Portuguese} +\item{sub_category_en}{Sub-category in English} +\item{frequency}{Data frequency} +\item{unit}{Measurement unit} +\item{seasonally_adjusted}{Logical} \item{start_date}{Series start date} -\item{end_date}{Series end date (NA if ongoing)} -\item{default_transform}{Suggested default transformation for analysis} -\item{suggested_scale}{Suggested scale for visualization} -\item{notes}{Additional notes and comments} +\item{end_date}{Series end date} +\item{default_transform}{Suggested transformation} +\item{suggested_scale}{Suggested visualization scale} +\item{notes_pt}{Notes in Portuguese} +\item{notes_en}{Notes in English} } } \source{ -Central Bank of Brazil - Time Series Management System (SGS) +Central Bank of Brazil — SGS } \usage{ br_available_series @@ -36,14 +41,10 @@ A comprehensive database of Brazilian economic and financial time series available through the Central Bank of Brazil's SGS system. } \examples{ -# View the entire database br_available_series -# Filter for inflation series -dplyr::filter(br_available_series, sub_category == "Inflation") - -# Find series by ID br_available_series[br_available_series$series_id == "433", ] +br_available_series[br_available_series$series_id == "433", ] } \keyword{datasets} diff --git a/man/browse_series.Rd b/man/browse_series.Rd index 15e5f0a..f25180d 100644 --- a/man/browse_series.Rd +++ b/man/browse_series.Rd @@ -9,7 +9,8 @@ browse_series( sub_category = NULL, source = NULL, frequency = NULL, - search_text = NULL + search_text = NULL, + language = c("pt", "en") ) } \arguments{ @@ -22,21 +23,18 @@ browse_series( \item{frequency}{Filter by frequency (optional)} \item{search_text}{Text search across all columns (optional)} + +\item{language}{Language for returned labels. Either \code{"pt"} or \code{"en"}.} } \value{ A tibble with available series matching the criteria } \description{ -Displays a searchable table of available economic and financial series in Brazil. +Displays a searchable table of available Brazilian economic series. } \examples{ -# View all available series browse_series() - -# Filter by category browse_series(category = "Macroeconomic") - -# Search for inflation series browse_series(search_text = "inflação") } diff --git a/man/get_series_info.Rd b/man/get_series_info.Rd index d5623d4..dd65603 100644 --- a/man/get_series_info.Rd +++ b/man/get_series_info.Rd @@ -4,24 +4,23 @@ \alias{get_series_info} \title{Get Series Information} \usage{ -get_series_info(series_id, field = NULL) +get_series_info(series_id, field = NULL, language = c("pt", "en")) } \arguments{ -\item{series_id}{The series ID (SGS code from BCB)} +\item{series_id}{The series ID (SGS code)} -\item{field}{Specific field to return (optional). If NULL, returns all information.} +\item{field}{Specific field to return (optional)} + +\item{language}{Language for returned labels. Either \code{"pt"} or \code{"en"}.} } \value{ -A list or character with series information +A list with series metadata or a single value } \description{ -Returns detailed information about a specific economic series. +Returns detailed metadata about a specific economic series. } \examples{ -# Get all information about IPCA get_series_info("433") - -# Get only the description -get_series_info("433", field = "description") +get_series_info("433", field = "description", language = "en") }