diff --git a/.github/workflows/r.yml b/.github/workflows/r.yml index 76d78a84..ef6a7852 100644 --- a/.github/workflows/r.yml +++ b/.github/workflows/r.yml @@ -24,18 +24,25 @@ jobs: matrix: r-version: ['3.6.3', '4.1.1'] - steps: + steps: - uses: actions/checkout@v3 - uses: r-lib/actions/setup-pandoc@v2 - name: Set up R ${{ matrix.r-version }} uses: r-lib/actions/setup-r@f57f1301a053485946083d7a45022b278929a78a with: r-version: ${{ matrix.r-version }} - - name: Install dependencies + cran: https://cran-archive.r-project.org + - name: Install dependencies run: | install.packages(c("remotes", "rcmdcheck")) - remotes::install_deps(dependencies = TRUE) + remotes::install_deps(dependencies = TRUE, type = "binary") shell: Rscript {0} + env: + R_LIBS_USER: /Users/runner/work/_temp/Library + TZ: UTC + _R_CHECK_SYSTEM_CLOCK_: FALSE + NOT_CRAN: true + timeout-minutes: 30 - name: Check run: rcmdcheck::rcmdcheck(args = "--no-manual", error_on = "error") shell: Rscript {0} diff --git a/DESCRIPTION b/DESCRIPTION index 4ee272e9..a8182516 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -22,7 +22,9 @@ Imports: stringr, curl, tibble, - rvest + rvest, + withr, + httr Suggests: knitr, rmarkdown, @@ -30,6 +32,8 @@ Suggests: remotes, tidyverse, testthat (>= 3.0.0) +Config/Needs/website: + tidyverse/tidytemplate RoxygenNote: 7.2.3 BugReports: https://github.com/davidycliao/legisTaiwan/issues URL: https://davidycliao.github.io/legisTaiwan/ diff --git a/NAMESPACE b/NAMESPACE index 82c23102..34c4d4c5 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,10 +1,5 @@ # Generated by roxygen2: do not edit by hand -export(.onAttach) -export(api_check) -export(check_date) -export(check_date2) -export(check_internet) export(get_bills) export(get_bills_2) export(get_caucus_meetings) @@ -16,16 +11,15 @@ export(get_parlquestions) export(get_public_debates) export(get_speech_video) export(get_variable_info) -export(review_session_info) -export(transformed_date_bill) -export(transformed_date_meeting) -export(website_availability2) importFrom(attempt,stop_if_all) importFrom(attempt,stop_if_not) importFrom(curl,has_internet) +importFrom(httr,GET) +importFrom(httr,content) importFrom(jsonlite,fromJSON) importFrom(rvest,html_text2) importFrom(rvest,read_html) importFrom(stringr,str_split_1) importFrom(stringr,str_sub) importFrom(tibble,as_tibble) +importFrom(withr,with_options) diff --git a/NEWS.md b/NEWS.md index a1bcad40..90dc5c5a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,6 @@ +# `legisTaiwan` 0.1.6 + + # `legisTaiwan` 0.1.4 (development version) * re-documentation and inserting handlers. diff --git a/R/bill.R b/R/bill.R index 53cc9b30..04113f5d 100644 --- a/R/bill.R +++ b/R/bill.R @@ -1,102 +1,93 @@ -#'The Records of the Bills 法律提案 -#' -#'@author David Liao (davidycliao@@gmail.com) -#' -#'@param start_date numeric Must be formatted in Minguo (Taiwan) calendar, e.g. 1090101. -#' -#'@param end_date numeric Must be formatted in Minguo (Taiwan) calendar, e.g. 1090102. -#' -#'@param proposer The default value is NULL, which means all bill proposed by all legislators -#' are included between the starting date and the ending date. -#' -#'@param verbose logical, indicates whether `get_bills` should print out -#'detailed output when retrieving the data. The default value is TRUE. -#' -#'@return list, which contains: \describe{ -#' \item{`title`}{the meeting records of cross-caucus session} -#' \item{`query_time`}{the query time} -#' \item{`retrieved_number`}{the number of observation} -#' \item{`meeting_unit`}{the meeting unit} -#' \item{`start_date_ad`}{the start date in POSIXct} -#' \item{`end_date_ad`}{the end date in POSIXct} -#' \item{`start_date`}{the start date in ROC Taiwan calendar} -#' \item{`url`}{the retrieved json url} -#' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153}; or use legisTaiwan::get_variable_info("get_bills")} -#' \item{`data`}{a tibble dataframe, whose variables include: -#' \describe{\item{`term`}{屆別} -#' \item{`sessionPeriod`}{會期} -#' \item{`sessionTimes`}{會次} -#' \item{`meetingTimes`}{提案日期} -#' \item{`billName`}{提案名稱} -#' \item{`billProposer`}{主提案人} -#' \item{`billCosignatory`}{連署提案} -#' \item{`billStatus`}{議案狀態} -#' \item{`date_ad`}{西元年} -#' } -#' } -#' } -#' -#'@importFrom attempt stop_if_all -#'@importFrom jsonlite fromJSON -#' -#'@export -#' -#'@examples -#' ## query bill records by a period of the dates in Taiwan ROC calender format -#' ## 輸入「中華民國民年」下載立法委員提案資料 -#'get_bills(start_date = 1060120, end_date = 1070310, verbose = FALSE) -#' -#' ## query bill records by a period of the dates in Taiwan ROC calender format -#' ## and a specific legislator -#' ## 輸入「中華民國民年」與「指定立法委員」下載立法委員提案資料 -#'get_bills(start_date = 1060120, end_date = 1070310, proposer = "孔文吉") -#' -#' ## query bill records by a period of the dates in Taiwan ROC calender format -#' ## and multiple legislators -#' ## 輸入「中華民國民年」與「指定多個立法委員」下載立法委員提案資料 -#'get_bills(start_date = 1060120, end_date = 1060510, proposer = "孔文吉&鄭天財") -#' -#'@details `get_bills` produces a list, which contains `query_time`, -#'`retrieved_number`, `meeting_unit`, `start_date_ad`, `end_date_ad`, `start_date`, -#'`end_date`, `url`, `variable_names`, `manual_info` and `data`. -#' -#'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_bills")` -#' or visit the API manual at \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153}. -#' 資料似乎不一致，待確認。委員發言（取得最早時間不詳，待檢查。） -#' -#'@seealso -#'`get_variable_info("get_bills_2")`,`review_session_info()` -#' -#'@seealso -#'Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. - +#'The Records of the Bills: 法律提案 +#' +#' @param start_date numeric. Must be formatted in the ROC Taiwan calendar, e.g., 1090101. +#' @param end_date numeric. Must be formatted in the ROC Taiwan calendar, e.g., 1090102. +#' @param proposer The default value is NULL, indicating that bills proposed by all legislators +#' are included between the start and end dates. +#' @param verbose logical. Specifies whether `get_bills` should print out +#' detailed output when retrieving the data. The default value is TRUE. +#' +#' @return A list, which contains: +#' \describe{ +#' \item{`title`}{Records of cross-caucus sessions} +#' \item{`query_time`}{Query timestamp} +#' \item{`retrieved_number`}{Number of observations retrieved} +#' \item{`meeting_unit`}{Meeting unit} +#' \item{`start_date_ad`}{Start date in POSIXct format} +#' \item{`end_date_ad`}{End date in POSIXct format} +#' \item{`start_date`}{Start date in the ROC Taiwan calendar} +#' \item{`url`}{URL of the retrieved JSON data} +#' \item{`variable_names`}{Variable names of the tibble dataframe} +#' \item{`manual_info`}{Official manual. See \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153} or use get_variable_info("get_bills")} +#' \item{`data`}{A tibble dataframe with the following variables: +#' \describe{\item{`term`}{Session number} +#' \item{`sessionPeriod`}{Session period} +#' \item{`sessionTimes`}{Session count} +#' \item{`meetingTimes`}{Proposal date} +#' \item{`billName`}{Bill name} +#' \item{`billProposer`}{Primary proposer} +#' \item{`billCosignatory`}{Co-signatories of the bill} +#' \item{`billStatus`}{Status of the bill} +#' \item{`date_ad`}{Date in the Gregorian calendar} +#' } +#' } +#' } +#' +#' @importFrom httr GET +#' @importFrom httr content +#' @importFrom jsonlite fromJSON +#' @importFrom tibble as_tibble +#' @importFrom withr with_options +#' +#' @export +#' +#' @examples +#' \dontrun{ +#' ## Query bill records by a date range in the Taiwan ROC calendar format +#' get_bills(start_date = 1060120, end_date = 1070310, verbose = FALSE) +#' +#' ## Query bill records by a date range and a specific legislator +#' get_bills(start_date = 1060120, end_date = 1070310, proposer = "孔文吉") +#' +#' ## Query bill records by a date range and multiple legislators +#' get_bills(start_date = 1060120, end_date = 1060510, proposer = "孔文吉&鄭天財") +#' } +#' +#' @details The `get_bills` function returns a list that contains `query_time`, +#' `retrieved_number`, `meeting_unit`, `start_date_ad`, `end_date_ad`, `start_date`, +#' `end_date`, `url`, `variable_names`, `manual_info`, and `data`. +#' +#' @note To retrieve the user manual and more details about the data frame, use `get_variable_info("get_bills")`. +#' Further checks are required as the user manual seems to be inconsistent with the actual data. +#' +#' @seealso +#' \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153} get_bills <- function(start_date = NULL, end_date = NULL, proposer = NULL, verbose = TRUE) { - legisTaiwan::check_internet() - legisTaiwan::api_check(start_date = legisTaiwan::check_date(start_date), end_date = legisTaiwan::check_date(end_date)) + check_internet() + api_check(start_date = check_date(start_date), end_date = check_date(end_date)) + validate_dates_format(start_date, end_date) set_api_url <- paste("https://www.ly.gov.tw/WebAPI/LegislativeBill.aspx?from=", start_date, "&to=", end_date, "&proposer=", proposer, "&mode=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") - df["date_ad"] <- do.call("c", lapply(df$date, legisTaiwan::transformed_date_bill)) + df["date_ad"] <- do.call("c", lapply(df$date, transformed_date_bill)) if (isTRUE(verbose)) { cat(" Retrieved URL: \n", set_api_url, "\n") cat(" Retrieved Bill Sponsor(s): ", proposer, "\n") - cat(" Retrieved date between:", as.character(legisTaiwan::check_date(start_date)), "and", as.character(legisTaiwan::check_date(end_date)) , "\n") + cat(" Retrieved date between:", as.character(check_date(start_date)), "and", as.character(check_date(end_date)) , "\n") cat(" Retrieved Num:", nrow(df), "\n") } list_data <- list("title" = "the records of bill sponsor and co-sponsor", "query_time" = Sys.time(), "retrieved_number" = nrow(df), "proposer" = proposer, - "start_date_ad" = legisTaiwan::check_date(start_date), - "end_date_ad" = legisTaiwan::check_date(end_date), + "start_date_ad" = check_date(start_date), + "end_date_ad" = check_date(end_date), "start_date" = start_date, "end_date" = end_date, "url" = set_api_url, @@ -112,35 +103,31 @@ get_bills <- function(start_date = NULL, end_date = NULL, proposer = NULL, } -#'The Records of Legislation and the Executives Proposals 委員及政府議案提案資訊 -#' -#'@author David Liao (davidycliao@@gmail.com) -#' -#'@param term numeric or null. The data is only available from 8th term. -#'The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。 -#' -#'@param session_period integer, numeric or NULL. Available -#'options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to NULL. -#'參數必須為數值。 -#'`review_session_info()` generates each session period available option period -#'in Minguo (Taiwan) calendar. -#' -#'@param verbose The default value is TRUE, displaying the description of data -#'retrieved in number, url and computing time. -#' -#'@return list list, which contains: \describe{ -#' \item{`title`}{the meeting records of cross-caucus session} -#' \item{`query_time`}{the query time} -#' \item{`retrieved_number`}{the number of observation} -#' \item{`meeting_unit`}{the meeting unit} -#' \item{`start_date_ad`}{the start date in POSIXct} -#' \item{`end_date_ad`}{the end date in POSIXct} -#' \item{`start_date`}{the start date in ROC Taiwan calendar} -#' \item{`url`}{the retrieved json url} -#' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=20}; or use legisTaiwan::get_variable_info("get_bills_2")} -#' \item{`data`}{a tibble dataframe, whose variables include: -#' \describe{\item{`term`}{屆別} +#' The Records of Legislation and the Executives Proposals: 委員及政府議案提案資訊 +#' +#' @author David Liao (davidycliao@@gmail.com) +#' +#' @param term A numeric or NULL value. Data is available from the 8th term onwards. +#' Default is set to 8. 參數必須為數值。資料從第8屆開始，預設值為8。 +#' +#' @param session_period An integer, numeric, or NULL. Valid options for the session are: +#' 1, 2, 3, 4, 5, 6, 7, and 8. Default is set to NULL. +#' 參數必須為數值。 +#' `review_session_info()` provides available session periods based on the Minguo (Taiwan) calendar. +#' +#' @param verbose Default value is TRUE. Displays details of the retrieved data, including the number, URL, and computing time. +#' +#' @return A list containing: +#' \item{`title`}{Records of questions answered by the executives} +#' \item{`query_time`}{Query time} +#' \item{`retrieved_number`}{Number of observations} +#' \item{`retrieved_term`}{Retrieved term} +#' \item{`url`}{Retrieved JSON URL} +#' \item{`variable_names`}{Variables of the tibble dataframe} +#' \item{`manual_info`}{Official manual: \url{https://data.ly.gov.tw/getds.action?id=20} or use `get_variable_info("get_bills_2")`} +#' \item{`data`}{A tibble dataframe with variables such as: +#' \describe{ +#' \item{`term`}{屆別} #' \item{`sessionPeriod`}{會期} #' \item{`sessionTimes`}{會次} #' \item{`meetingTimes`}{臨時會會次} @@ -150,79 +137,95 @@ get_bills <- function(start_date = NULL, end_date = NULL, proposer = NULL, #' \item{`billProposer`}{主提案人} #' \item{`billCosignatory`}{連署提案} #' \item{`billStatus`}{議案狀態} -#' \item{`pdfUrl`}{關係文書pdf檔案下載位置} -#' \item{`docUrl`}{關係文書doc檔案下載位置} -#' \item{`selectTerm`}{屆別期別篩選條件} +#' \item{`pdfUrl`}{PDF download link for related documents} +#' \item{`docUrl`}{DOC download link for related documents} +#' \item{`selectTerm`}{Filtering criteria based on term} #' } #' } -#' } #' -#'@importFrom attempt stop_if_all -#'@importFrom jsonlite fromJSON +#' @importFrom attempt stop_if_all +#' @importFrom jsonlite fromJSON +#' @importFrom httr GET +#' @importFrom tibble as_tibble +#' @importFrom withr with_options #' -#'@export +#' @export #' -#'@examples -#' ## query the Executives' answered response by term and the session period. -#' ## 輸入「立委屆期」與「會期」下載「質詢事項 (行政院答復部分)」 -#'get_bills_2(term = 8, session_period = 1) +#' @examples +#' \dontrun{ +#' ## Query the executives' responses by term and session period. +#' ## 輸入「立委屆期」與「會期」以下載「質詢事項 (行政院答復部分)」 +#' get_bills_2(term = 8, session_period = 1) +#' } #' -#'@details `get_bills_2` produces a list, which contains `query_time`, -#'`retrieved_number`, `meeting_unit`, `start_date_ad`, `end_date_ad`, `start_date`, -#'`end_date`, `url`, `variable_names`, `manual_info` and `data`. To retrieve the user -#'manual and more information about the data frame, please use `legisTaiwan::get_variable_info("get_bills_2")`. +#' @details The `get_bills_2` function produces a list, which includes `query_time`, +#' `retrieved_number`, `retrieved_term`, `url`, `variable_names`, `manual_info`, and `data`. +#' For the user manual and more information about the dataframe, use `get_variable_info("get_bills_2")`. #' -#'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_bills_2")` +#' @note For more details about the dataframe's variables, use `get_variable_info("get_bills_2")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=20}. -#' 議事類: 提供委員及政府之議案提案資訊 (自第8屆第1會期起)。 +#' 議事類: 提供委員及政府之議案提案資訊 (從第8屆第1會期開始)。 #' -#'@seealso -#'`get_variable_info("get_bills_2")`,`review_session_info()` - +#' @seealso +#' `get_variable_info("get_bills_2")`,`review_session_info()` +# Define the function get_bills_2 get_bills_2 <- function(term = 8, session_period = NULL, verbose = TRUE) { - legisTaiwan::check_internet() + + # Check for internet connectivity + check_internet() + + # If the term is not specified if (is.null(term)) { - options(timeout = max(1000, getOption("timeout"))) - set_api_url <- paste("https://data.ly.gov.tw/odw/ID20Action.action?term=", - term, "&sessionPeriod=", - "&sessionTimes=&meetingTimes=&billName=&billOrg=&billProposer=&billCosignatory=&fileType=json", - sep = "") - message(" term is not defined...\n You are now requesting full data from the API. Please make sure your connectivity is stable until its completion.\n") + # Set the base API URL without specifying any term + set_api_url <- "https://data.ly.gov.tw/odw/ID20Action.action?term=&sessionPeriod=&sessionTimes=&meetingTimes=&billName=&billOrg=&billProposer=&billCosignatory=&fileType=json" + # Display a notification message + message("The term is not defined...\nYou are now requesting full data from the API. Please ensure a stable internet connection until completion.\n") } else { - attempt::stop_if_all(term, is.character, msg = "use numeric format only.") + # If the term is in character format, stop execution and display an error message + attempt::stop_if_all(term, is.character, msg = "Please use numeric format only.") + + # If term length is one, format the term to two digits if (length(term) == 1) { - term <- sprintf("%02d", as.numeric(term))} - else if (length(term) > 1) { - # options(timeout = max(1000, getOption("timeout"))) - term <- paste(sprintf("%02d", as.numeric(term)), collapse = "&") - message("The API is unable to query multiple terms and the retrieved data might not be complete.")} + term <- sprintf("%02d", as.numeric(term)) + } else if (length(term) > 1) { # If multiple terms are provided + stop("The API doesn't support querying multiple terms. Consider implementing batch processing. Please refer to the tutorial for guidance.") + } + + # Convert session period to two-digit format, if it's not NULL + session_str <- ifelse(is.null(session_period), "", sprintf("%02d", as.numeric(session_period))) + + # Construct the complete API URL + set_api_url <- paste0("https://data.ly.gov.tw/odw/ID20Action.action?term=", + term, "&sessionPeriod=", session_str, + "&sessionTimes=&meetingTimes=&billName=&billOrg=&billProposer=&billCosignatory=&fileType=json") } - set_api_url <- paste("https://data.ly.gov.tw/odw/ID20Action.action?term=", - term, "&sessionPeriod=", - sprintf("%02d", as.numeric(session_period)), - "&sessionTimes=&meetingTimes=&billName=&billOrg=&billProposer=&billCosignatory=&fileType=json", sep = "") + + # Try to fetch the data and process it tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) + # If the returned data is empty, stop execution and display an error message attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { - cat(" Retrieved URL: \n", set_api_url, "\n") - cat(" Retrieved Term: ", term, "\n") - cat(" Retrieved Num: ", nrow(df), "\n") + cat("Retrieved URL: ", set_api_url, "\n") + cat("Retrieved Term: ", term, "\n") + cat("Retrieved Number of Records: ", nrow(df), "\n") } - list_data <- list("title" = "the records of the questions answered by the executives", - "query_time" = Sys.time(), - "retrieved_number" = nrow(df), - "retrieved_term" = term, - "url" = set_api_url, - "variable_names" = colnames(df), - "manual_info" = "https://data.ly.gov.tw/getds.action?id=2", - "data" = df) - return(list_data) + # Construct the result list + list_data <- list( + "title" = "The records of the questions answered by the executives", + "query_time" = Sys.time(), + "retrieved_number" = nrow(df), + "retrieved_term" = term, + "url" = set_api_url, + "variable_names" = colnames(df), + "manual_info" = "https://data.ly.gov.tw/getds.action?id=2", + "data" = df + ) + return(list_data) # Return the result list }, - error = function(error_message) { + error = function(error_message) { # Handle any errors message(error_message) } ) diff --git a/R/info.R b/R/info.R index 27d4ff51..eb91c04f 100644 --- a/R/info.R +++ b/R/info.R @@ -30,72 +30,139 @@ #'@importFrom rvest html_text2 read_html #'@importFrom tibble as_tibble #' -#'@export +#' @export #' -#'@seealso -#'`review_session_info()` +#' @seealso `review_session_info()`. +#' +#' @examples +#' \dontrun{ +#' get_variable_info("get_bills") +#' } +# get_variable_info <- function(param_) { +# check_internet() +# attempt::stop_if_all(website_availability(), isFALSE, msg = "the error from the API.") +# attempt::stop_if_all(param_, is.numeric, msg = "use string format only.") +# attempt::stop_if_all(param_, is.null, msg = "use correct funtion names.") +# attempt::stop_if(param_ , ~ length(.x) >1, msg = "only allowed to query one function.") +# if (param_ == "get_parlquestions") { +# url <- "https://data.ly.gov.tw/getds.action?id=6" +# } +# else if (param_ == "get_legislators") { +# url <- "https://data.ly.gov.tw/getds.action?id=16" +# } +# else if (param_ == "get_committee_record") { +# url <- "https://data.ly.gov.tw/getds.action?id=46" +# } +# else if (param_ == "get_executive_response") { +# url <- "https://data.ly.gov.tw/getds.action?id=2" +# } +# else if (param_ == "get_caucus_meetings") { +# url <- "https://data.ly.gov.tw/getds.action?id=8" +# } +# else if (param_ == "get_speech_video") { +# url <- "https://data.ly.gov.tw/getds.action?id=148" +# } +# else if (param_ == "get_bills_2") { +# url <- "https://data.ly.gov.tw/getds.action?id=20" +# } +# else if (param_ == "get_public_debates") { +# url <- "https://data.ly.gov.tw/getds.action?id=7" +# } +# else if (param_ %in% c("get_bills", "get_meetings")) { +# if (param_ == "get_meetings") { +# url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=154" +# } +# else if (param_ == "get_bills") { +# url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=153" +# } +# html_info <- rvest::html_text2(rvest::html_nodes(rvest::html_nodes(rvest::read_html(url), "*[id='form_Query']"), "div") ) +# page_info <- list(page_info = strsplit(html_info[14], split = "\n")[[1]], reference_url = url) +# return(page_info) +# } +# else { +# stop("Use correct funtion names below in character format: +# get_bills: the records of the bills +# get_bills_2: the records of legislators and the government proposals +# get_meetings: the spoken meeting records +# get_caucus_meetings: the meeting records of cross-caucus session +# get_speech_video: the full video information of meetings and committees +# get_public_debates: the records of national public debates +# get_parlquestions: the records of parliamentary questions +# get_executive_response: the records of the questions answered by the executives") +# } +# html <- rvest::html_nodes(rvest::read_html(url), "*[id='content']") +# title <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "h2"))) +# +# content <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "span"))) +# df <- data.frame(content[seq(1, length(content), 2 )], +# content[seq(1, length(content) + 1, 2 ) -1]) +# colnames(df) <- c(title[2], title[1]) +# df <- tibble::as_tibble(df) +# page_info <- list(page_info = df, reference_url = url) +# return(page_info) +# } get_variable_info <- function(param_) { - legisTaiwan::check_internet() - attempt::stop_if_all(website_availability(), isFALSE, msg = "the error from the API.") - attempt::stop_if_all(param_, is.numeric, msg = "use string format only.") - attempt::stop_if_all(param_, is.null, msg = "use correct funtion names.") - attempt::stop_if(param_ , ~ length(.x) >1, msg = "only allowed to query one function.") - if (param_ == "get_parlquestions") { - url <- "https://data.ly.gov.tw/getds.action?id=6" - } - else if (param_ == "get_legislators") { - url <- "https://data.ly.gov.tw/getds.action?id=16" - } - else if (param_ == "get_committee_record") { - url <- "https://data.ly.gov.tw/getds.action?id=46" - } - else if (param_ == "get_executive_response") { - url <- "https://data.ly.gov.tw/getds.action?id=2" - } - else if (param_ == "get_caucus_meetings") { - url <- "https://data.ly.gov.tw/getds.action?id=8" - } - else if (param_ == "get_speech_video") { - url <- "https://data.ly.gov.tw/getds.action?id=148" - } - else if (param_ == "get_bills_2") { - url <- "https://data.ly.gov.tw/getds.action?id=20" + # Ensure internet and website availability + check_internet() + attempt::stop_if_not(website_availability(), msg = "the error from the API.") + + # Parameter checks + attempt::stop_if(param_, is.numeric, msg = "use string format only.") + attempt::stop_if(param_, is.null, msg = "use correct function names.") + attempt::stop_if(param_, ~ length(.x) > 1, msg = "only allowed to query one function.") + + # Dictionary for URL mapping + url_mapping <- list( + get_parlquestions = "https://data.ly.gov.tw/getds.action?id=6", + get_legislators = "https://data.ly.gov.tw/getds.action?id=16", + get_committee_record = "https://data.ly.gov.tw/getds.action?id=46", + get_executive_response = "https://data.ly.gov.tw/getds.action?id=2", + get_caucus_meetings = "https://data.ly.gov.tw/getds.action?id=8", + get_speech_video = "https://data.ly.gov.tw/getds.action?id=148", + get_bills_2 = "https://data.ly.gov.tw/getds.action?id=20", + get_public_debates = "https://data.ly.gov.tw/getds.action?id=7" + ) + if (!(param_ %in% names(url_mapping) || param_ %in% c("get_bills", "get_meetings"))) { + stop("Use correct function names below in character format: + get_bills: the records of the bills + get_bills_2: the records of legislators and the government proposals + get_meetings: the spoken meeting records + get_caucus_meetings: the meeting records of cross-caucus session + get_speech_video: the full video information of meetings and committees + get_public_debates: the records of national public debates + get_parlquestions: the records of parliamentary questions + get_executive_response: the records of the questions answered by the executives") } - else if (param_ == "get_public_debates") { - url <- "https://data.ly.gov.tw/getds.action?id=7" + + + # Fetch URL from dictionary or process special cases + if (param_ %in% names(url_mapping)) { + url <- url_mapping[[param_]] + } else if (param_ == "get_meetings") { + url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=154" + } else if (param_ == "get_bills") { + url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=153" + } else { + stop("Use correct function names below in character format.") } - else if (param_ %in% c("get_bills", "get_meetings")) { - if (param_ == "get_meetings") { - url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=154" - } - else if (param_ == "get_bills") { - url <- "https://www.ly.gov.tw/Pages/List.aspx?nodeid=153" - } - html_info <- rvest::html_text2(rvest::html_nodes(rvest::html_nodes(rvest::read_html(url), "*[id='form_Query']"), "div") ) + + if (param_ %in% c("get_bills", "get_meetings")) { + html_info <- rvest::html_text2(rvest::html_nodes(rvest::html_nodes(rvest::read_html(url), "*[id='form_Query']"), "div")) page_info <- list(page_info = strsplit(html_info[14], split = "\n")[[1]], reference_url = url) return(page_info) } - else { - stop("Use correct funtion names below in character format: - get_bills: the records of the bills - get_bills_2: the records of legislators and the government proposals - get_meetings: the spoken meeting records - get_caucus_meetings: the meeting records of cross-caucus session - get_speech_video: the full video information of meetings and committees - get_public_debates: the records of national public debates - get_parlquestions: the records of parliamentary questions - get_executive_response: the records of the questions answered by the executives") - } - html <- rvest::html_nodes(rvest::read_html(url), "*[id='content']") - title <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "h2"))) - - content <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "span"))) - df <- data.frame(content[seq(1, length(content), 2 )], - content[seq(1, length(content) + 1, 2 ) -1]) - colnames(df) <- c(title[2], title[1]) - df <- tibble::as_tibble(df) - page_info <- list(page_info = df, reference_url = url) + + html <- rvest::html_nodes(rvest::read_html(url), "*[id='content']") + title <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "h2"))) + + content <- gsub("[[:space:]]", "", rvest::html_text2(rvest::html_nodes(html, "span"))) + df <- data.frame(content[seq(1, length(content), 2)], + content[seq(1, length(content) + 1, 2) - 1]) + colnames(df) <- c(title[2], title[1]) + df <- tibble::as_tibble(df) + page_info <- list(page_info = df, reference_url = url) + return(page_info) } @@ -115,28 +182,55 @@ get_variable_info <- function(param_) { #'@importFrom rvest html_text2 read_html #'@importFrom tibble as_tibble #' -#'@export +#' @seealso +#' Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. #' -#'@seealso -#'Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. +#' @examples +#' \dontrun{ +#' review_session_info(7) +#' } + +# review_session_info <- function(term){ +# attempt::stop_if_all(website_availability2(), isFALSE, msg = "the error from the API.") +# attempt::stop_if_all(term, is.null, msg = "use correct `term`") +# attempt::stop_if_all(term %in% 1:11, isFALSE, msg = "use correct `term`") +# url <- paste("https://npl.ly.gov.tw/do/www/appDate?status=0&expire=", +# sprintf("%02d", as.numeric(term)), +# "&startYear=0", sep ="") +# html_ <- rvest::html_nodes(rvest::read_html(url), "*[class='section_wrapper']") +# title <- stringr::str_split_1(rvest::html_text2(rvest::html_nodes(html_, "[class='tt_titlebar2']")), "\t\r")[1:2] +# o <- rvest::html_text2(rvest::html_nodes(html_, "[class='tt_listrow_odd']")) +# e <- rvest::html_text2(rvest::html_nodes(html_, "[class='tt_listrow_even']")) +# s <- lapply(lapply(c(o, e),function(.){stringr::str_split_1(., "\r\r" )}), +# function(.){gsub("[[:space:]]", "", .)}) +# df <- do.call(rbind, s) +# colnames(df) <- title +# df <- tibble::as_tibble(df) +# return(df) +# } +# +# + + + +review_session_info <- function(term) { + attempt::stop_if_not(website_availability2(), msg = "the error from the API.") + attempt::stop_if(term, is.null, msg = "use correct `term`.") + attempt::stop_if_not(term %in% 1:11, msg = "use correct `term`.") -review_session_info <- function(term){ - attempt::stop_if_all(legisTaiwan::website_availability2(), isFALSE, msg = "the error from the API.") - attempt::stop_if_all(term, is.null, msg = "use correct `term`") - attempt::stop_if_all(term %in% 1:11, isFALSE, msg = "use correct `term`") url <- paste("https://npl.ly.gov.tw/do/www/appDate?status=0&expire=", sprintf("%02d", as.numeric(term)), "&startYear=0", sep ="") + html_ <- rvest::html_nodes(rvest::read_html(url), "*[class='section_wrapper']") title <- stringr::str_split_1(rvest::html_text2(rvest::html_nodes(html_, "[class='tt_titlebar2']")), "\t\r")[1:2] o <- rvest::html_text2(rvest::html_nodes(html_, "[class='tt_listrow_odd']")) e <- rvest::html_text2(rvest::html_nodes(html_, "[class='tt_listrow_even']")) - s <- lapply(lapply(c(o, e),function(.){stringr::str_split_1(., "\r\r" )}), - function(.){gsub("[[:space:]]", "", .)}) + s <- lapply(lapply(c(o, e), function(.) {stringr::str_split_1(., "\r\r")}), + function(.) {gsub("[[:space:]]", "", .)}) df <- do.call(rbind, s) colnames(df) <- title df <- tibble::as_tibble(df) - return(df) - } - + return(df) +} diff --git a/R/legislators.R b/R/legislators.R index 4a7fa2b7..30b31e46 100644 --- a/R/legislators.R +++ b/R/legislators.R @@ -33,6 +33,7 @@ #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' @@ -45,7 +46,7 @@ #'`queried_term`, `url`, `variable_names`, `manual_info` and `data`. #' #'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_legislators")` +#' frame, please use `get_variable_info("get_legislators")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=16}. #' 提供委員基本資料，最早資料可追溯至第2屆。 #' @@ -53,7 +54,7 @@ #'`get_variable_info("get_legislators")`, `review_session_info()` get_legislators <- function(term = NULL, verbose = TRUE) { - legisTaiwan::check_internet() + check_internet() if (is.null(term)) { set_api_url <- paste("https://data.ly.gov.tw/odw/ID16Action.action?name=&sex=&party=&partyGroup=&areaName=&term=", term, "=&fileType=json", sep = "") @@ -71,7 +72,7 @@ get_legislators <- function(term = NULL, verbose = TRUE) { } tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") term <- paste(sort(as.numeric(unique(df$term))), collapse = " ", sep = ",") diff --git a/R/meeting.R b/R/meeting.R index 44f38933..aeed4d71 100644 --- a/R/meeting.R +++ b/R/meeting.R @@ -22,7 +22,7 @@ #' \item{`start_date`}{the start date in ROC Taiwan calendar} #' \item{`url`}{the retrieved json url} #' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the offical manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}; or use legisTaiwan::get_variable_info("get_meetings")} +#' \item{`manual_info`}{the offical manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}; or use get_variable_info("get_meetings")} #' \item{`data`}{a tibble dataframe, whose variables include: #' \describe{\item{`smeeting_date`}{會議日期} #' \item{`meeting_status`}{會議狀態} @@ -37,6 +37,7 @@ #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' @@ -55,7 +56,7 @@ #'`end_date`, `url`, `variable_names`, `manual_info` and `data`. #' #'@note To retrieve the user manual and more information about variable of the data -#'frame, please use `legisTaiwan::get_variable_info("get_meetings")` or visit +#'frame, please use `get_variable_info("get_meetings")` or visit #'the API manual at \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}. #'資料似乎不一致，待確認。委員發言（取得最早時間不詳，待檢查。） #' @@ -67,28 +68,28 @@ get_meetings <- function(start_date = NULL, end_date = NULL, meeting_unit = NULL, verbose = TRUE) { - legisTaiwan::check_internet() - legisTaiwan::api_check(start_date = legisTaiwan::check_date(start_date), end_date = legisTaiwan::check_date(end_date)) + check_internet() + api_check(start_date = check_date(start_date), end_date = check_date(end_date)) set_api_url <- paste("https://www.ly.gov.tw/WebAPI/LegislativeSpeech.aspx?from=", start_date, "&to=", end_date, "&meeting_unit=", meeting_unit, "&mode=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") - df["date_ad"] <- do.call("c", lapply(df$smeeting_date, legisTaiwan::transformed_date_meeting)) + df["date_ad"] <- do.call("c", lapply(df$smeeting_date, transformed_date_meeting)) if (isTRUE(verbose)) { cat(" Retrieved URL: \n", set_api_url, "\n") cat(" Retrieved via :", meeting_unit, "\n") - cat(" Retrieved date between:", as.character(legisTaiwan::check_date(start_date)), "and", as.character(legisTaiwan::check_date(end_date)), "\n") + cat(" Retrieved date between:", as.character(check_date(start_date)), "and", as.character(check_date(end_date)), "\n") cat(" Retrieved number:", nrow(df), "\n") } list_data <- list("title" = "the spoken meeting records", "query_time" = Sys.time(), "retrieved_number" = nrow(df), "meeting_unit" = meeting_unit, - "start_date_ad" = legisTaiwan::check_date(start_date), - "end_date_ad" = legisTaiwan::check_date(end_date), + "start_date_ad" = check_date(start_date), + "end_date_ad" = check_date(end_date), "start_date" = start_date, "end_date" = end_date, "url" = set_api_url, @@ -127,7 +128,7 @@ get_meetings <- function(start_date = NULL, end_date = NULL, meeting_unit = NULL #' \item{`start_date`}{the start date in ROC Taiwan calendar} #' \item{`url`}{the retrieved json url} #' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=8}; or use legisTaiwan::get_variable_info("get_caucus_meetings")} +#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=8}; or use get_variable_info("get_caucus_meetings")} #' \item{`data`}{a tibble dataframe, whose variables include: #' \describe{\item{`comYear`}{卷} #' \item{`comVolume`}{期} @@ -149,6 +150,7 @@ get_meetings <- function(start_date = NULL, end_date = NULL, meeting_unit = NULL #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' @@ -165,7 +167,7 @@ get_meetings <- function(start_date = NULL, end_date = NULL, meeting_unit = NULL #'\\ifelse{html}{\\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\\strong{[Experimental]}} #' #'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_caucus_meetings")` +#' frame, please use `get_variable_info("get_caucus_meetings")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=8}. #' 議事類:提供公報之黨團協商資訊 (自第8屆第1會期起) #' @@ -177,26 +179,26 @@ get_meetings <- function(start_date = NULL, end_date = NULL, meeting_unit = NULL # get_caucus_meetings <- function(start_date = NULL, end_date = NULL, verbose = TRUE) { - legisTaiwan::check_internet() - legisTaiwan::api_check(start_date = legisTaiwan::transformed_date_meeting(start_date), - end_date = legisTaiwan::transformed_date_meeting(end_date)) + check_internet() + api_check(start_date = transformed_date_meeting(start_date), + end_date = transformed_date_meeting(end_date)) set_api_url <- paste("https://data.ly.gov.tw/odw/ID8Action.action?comYear=&comVolume=&comBookId=&term=&sessionPeriod=&sessionTimes=&meetingTimes=&meetingDateS=", start_date, "&meetingDateE=", end_date, "&fileType=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { cat(" Retrieved URL: \n", set_api_url, "\n") - cat(" Retrieved date between:", as.character(legisTaiwan::transformed_date_meeting(start_date)), "and", as.character(legisTaiwan::transformed_date_meeting(end_date)), "\n") + cat(" Retrieved date between:", as.character(transformed_date_meeting(start_date)), "and", as.character(transformed_date_meeting(end_date)), "\n") cat(" Retrieved number:", nrow(df), "\n") } list_data <- list("title" = "the meeting records of cross-caucus session", "query_time" = Sys.time(), "retrieved_number" = nrow(df), - "start_date_ad" = legisTaiwan::transformed_date_meeting(start_date), - "end_date_ad" = legisTaiwan::transformed_date_meeting(end_date), + "start_date_ad" = transformed_date_meeting(start_date), + "end_date_ad" = transformed_date_meeting(end_date), "start_date" = start_date, "end_date" = end_date, "url" = set_api_url, @@ -233,7 +235,7 @@ get_caucus_meetings <- function(start_date = NULL, end_date = NULL, #' \item{`start_date`}{the start date in ROC Taiwan calendar} #' \item{`url`}{the retrieved json url} #' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=148}; or use legisTaiwan::get_variable_info("get_speech_video")} +#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=148}; or use get_variable_info("get_speech_video")} #' \item{`data`}{a tibble dataframe, whose variables include: #' \describe{\item{`term`}{屆別} #' \item{`sessionPeriod`}{會期} @@ -256,6 +258,7 @@ get_caucus_meetings <- function(start_date = NULL, end_date = NULL, #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' @@ -269,10 +272,10 @@ get_caucus_meetings <- function(start_date = NULL, end_date = NULL, #'@details `get_speech_video` produces a list, which contains `title`, `query_time`, #'`retrieved_number`, `meeting_unit`, `start_date_ad`, `end_date_ad`, `start_date`, #'`end_date`, `url`, `variable_names`, `manual_info` and `data.` To retrieve the user -#'manual and more information about the data frame, please use `legisTaiwan::get_variable_info("get_speech_video")`. +#'manual and more information about the data frame, please use `get_variable_info("get_speech_video")`. #' #'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_speech_video")` +#' frame, please use `get_variable_info("get_speech_video")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=148}. #' 會議類:提供立法院院會及委員會之委員發言片段相關影片資訊 (自第9屆第1會期起)。 #' @@ -280,10 +283,10 @@ get_caucus_meetings <- function(start_date = NULL, end_date = NULL, #'`get_variable_info("get_speech_video")` get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) { - legisTaiwan::check_internet() - legisTaiwan::api_check(start_date = legisTaiwan::transformed_date_meeting(start_date), end_date = legisTaiwan::transformed_date_meeting(end_date)) + check_internet() + api_check(start_date = transformed_date_meeting(start_date), end_date = transformed_date_meeting(end_date)) # # 自第9屆第1會期起 2016 民國 105 - # queried_year <- format(legisTaiwan::transformed_date_meeting(start_date), format = "%Y") + # queried_year <- format(transformed_date_meeting(start_date), format = "%Y") # attempt::warn_if(queried_year < 2016, # isTRUE, # msg = paste("The query retrieved from", queried_year, "may not be complete.", "The data is only available from the 6th session of the 8th legislative term in 2015/104 in ROC.")) @@ -294,19 +297,19 @@ get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) "&meetingTime=&legislatorName=&fileType=json" , sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { cat(" Retrieved URL: \n", set_api_url, "\n") - cat(" Retrieved date between:", as.character(legisTaiwan::transformed_date_meeting(start_date)), "and", as.character(legisTaiwan::transformed_date_meeting(end_date)), "\n") + cat(" Retrieved date between:", as.character(transformed_date_meeting(start_date)), "and", as.character(transformed_date_meeting(end_date)), "\n") cat(" Retrieved number:", nrow(df), "\n") } list_data <- list("title" = "the meeting records of cross-caucus session", "query_time" = Sys.time(), "retrieved_number" = nrow(df), - "start_date_ad" = legisTaiwan::transformed_date_meeting(start_date), - "end_date_ad" = legisTaiwan::transformed_date_meeting(end_date), + "start_date_ad" = transformed_date_meeting(start_date), + "end_date_ad" = transformed_date_meeting(end_date), "start_date" = start_date, "end_date" = end_date, "url" = set_api_url, @@ -346,7 +349,7 @@ get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) #' \item{`start_date`}{the start date in ROC Taiwan calendar} #' \item{`url`}{the retrieved json url} #' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=7}; or use legisTaiwan::get_variable_info("get_public_debates")} +#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=7}; or use get_variable_info("get_public_debates")} #' \item{`data`}{a tibble dataframe, whose variables include: #' \describe{\item{`term`}{屆別} #' \item{`sessionPeriod`}{會期} @@ -365,6 +368,7 @@ get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' @@ -379,7 +383,7 @@ get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) #' #'@note #' To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_public_debates")` +#' frame, please use `get_variable_info("get_public_debates")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=7}. #' 議事類: 提供公報之國是論壇資訊，並包含書面意見。自第8屆第1會期起，但實測資料從第10屆。 #' @@ -390,7 +394,7 @@ get_speech_video <- function(start_date = NULL, end_date = NULL, verbose = TRUE) #' Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. get_public_debates <- function(term = NULL, session_period = NULL, verbose = TRUE) { - legisTaiwan::check_internet() + check_internet() if (is.null(term)) { set_api_url <- paste("https://data.ly.gov.tw/odw/ID7Action.action?term=", term, "&sessionPeriod=", @@ -412,7 +416,7 @@ get_public_debates <- function(term = NULL, session_period = NULL, verbose = TRU sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { @@ -441,60 +445,115 @@ get_public_debates <- function(term = NULL, session_period = NULL, verbose = TRU #' #'@author David Yen-Chieh Liao #' -#'@param term numeric or null. The data is only available from 8th term. -#'The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。 +#'@param term numeric or null. Data is available only from the 8th term. +#'The default is set to 10. 參數必須為數值。提供委員會會議審查之議案項目。(自第10屆第1會期起) +#' +#'@param session_period integer, numeric or NULL. +#'`review_session_info()` provides each session period's available options based on the +#' Minguo (Taiwan) calendar. +#' +#'@param verbose logical. This indicates whether `get_executive_response` should +#'print a detailed output during data retrieval. Default is TRUE. +#' +#'@return A list containing: +#' \item{`title`}{Records of questions answered by executives} +#' \item{`query_time`}{Time of query} +#' \item{`retrieved_number`}{Total number of observations} +#' \item{`retrieved_term`}{Queried term} +#' \item{`url`}{Retrieved JSON URL} +#' \item{`variable_names`}{Variables of the tibble dataframe} +#' \item{`manual_info`}{Official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use get_variable_info("get_committee_record")} +#' \item{`data`}{A tibble dataframe with variables: +#' \describe{ +#' \item{`term`}{Term number} +#' \item{`sessionPeriod`}{Session} +#' \item{`meetingNo`}{Meeting number} +#' \item{`billNo`}{Bill number} +#' \item{`selectTerm`}{Term selection filter} +#' } +#' } #' -#'@param session_period integer, numeric or NULL. Available -#'options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to NULL. 參數必須為數值。 -#'`review_session_info()` generates each session period available option period -#' in Minguo (Taiwan) calendar. +#'@importFrom attempt stop_if_all +#'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' -#'@param verbose logical, indicates whether `get_executive_response` should -#'print out detailed output when retrieving the data. The default is TRUE -#' -#'@return list contains: \describe{ -#' \item{`title`}{the records of the questions answered by the executives} -#' \item{`query_time`}{the queried time} -#' \item{`retrieved_number`}{the total number of observations} -#' \item{`retrieved_term`}{the queried term} -#' \item{`url`}{the retrieved json url} -#' \item{`variable_names`}{the variables of the tibble dataframe} -#' \item{`manual_info`}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use legisTaiwan::get_variable_info("get_committee_record")} -#' \item{`data`}{a tibble dataframe, whose variables include: -#' \describe{\item{`term`}{屆別} -#' \item{`sessionPeriod`}{會期} -#' \item{`meetingNo`}{會議編號} -#' \item{`billNo`}{議案編號} -#' \item{`selectTerm`}{屆別期別篩選條件} +#'@export +#' +#'@examples +#' ## Query the committee record by term and session period. +#' ## 輸入「立委屆期」與「會期」下載「委員會審議之議案」 +#'get_committee_record(term = 10, session_period = 1) +#' +#'@details `get_committee_record` provides a list which includes `title`, +#'`query_time`, `retrieved_number`, `retrieved_term`, `url`, `variable_names`, +#' `manual_info`, and `data`. +#' +#'@note +#' To access the user manual and more information about the data frame's variables, +#' please refer to `get_variable_info("get_committee_record")` or check the API manual at +#' \url{https://data.ly.gov.tw/getds.action?id=46}. +#' This provides agenda items reviewed in committee meetings (from the 10th term, 1st session onwards). +#' +#'@seealso +#'`get_variable_info("get_committee_record")`, `review_session_info()` +#' The Records of Reviewed Items in the Committees 委員會會議審查之議案項目 +#' +#'@author David Yen-Chieh Liao +#' +#'@param term numeric or null. Data is available only from the 8th term. +#'The default is set to 10. 參數必須為數值。提供委員會會議審查之議案項目。(自第10屆第1會期起) +#' +#'@param session_period integer, numeric or NULL. +#'`review_session_info()` provides each session period's available options based on the +#' Minguo (Taiwan) calendar. +#' +#'@param verbose logical. This indicates whether `get_executive_response` should +#'print a detailed output during data retrieval. Default is TRUE. +#' +#'@return A list containing: +#' \item{`title`}{Records of questions answered by executives} +#' \item{`query_time`}{Time of query} +#' \item{`retrieved_number`}{Total number of observations} +#' \item{`retrieved_term`}{Queried term} +#' \item{`url`}{Retrieved JSON URL} +#' \item{`variable_names`}{Variables of the tibble dataframe} +#' \item{`manual_info`}{Official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use get_variable_info("get_committee_record")} +#' \item{`data`}{A tibble dataframe with variables: +#' \describe{ +#' \item{`term`}{Term number} +#' \item{`sessionPeriod`}{Session} +#' \item{`meetingNo`}{Meeting number} +#' \item{`billNo`}{Bill number} +#' \item{`selectTerm`}{Term selection filter} #' } #' } -#' } #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON +#'@importFrom withr with_options #' #'@export #' #'@examples -#' ## query the committee record by term and the session period. +#' ## Query the committee record by term and session period. #' ## 輸入「立委屆期」與「會期」下載「委員會審議之議案」 -#'get_committee_record(term = 8, session_period = 1) +#'get_committee_record(term = 10, session_period = 1) #' -#'@details `get_committee_record` produces a list, which contains `title`, +#'@details `get_committee_record` provides a list which includes `title`, #'`query_time`, `retrieved_number`, `retrieved_term`, `url`, `variable_names`, -#' `manual_info` and `data`. +#' `manual_info`, and `data`. #' #'@note -#' To retrieve the user manual and more information -#' about variable of the data frame, please use `legisTaiwan::get_variable_info("get_committee_record")` -#' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=46}. -#' 議事類: 提供委員會會議審查之議案項目 (自第8屆第1會期起)。 +#' To access the user manual and more information about the data frame's variables, +#' please refer to `get_variable_info("get_committee_record")` or check the API manual at +#' \url{https://data.ly.gov.tw/getds.action?id=46}. +#' This provides agenda items reviewed in committee meetings (from the 10th term, 1st session onwards). #' #'@seealso #'`get_variable_info("get_committee_record")`, `review_session_info()` -get_committee_record <- function(term = 8, session_period = NULL, verbose = TRUE) { - legisTaiwan::check_internet() +get_committee_record <- function(term = 10, session_period = NULL, verbose = TRUE) { + check_internet() if (is.null(term)) { set_api_url <- paste("https://data.ly.gov.tw/odw/ID46Action.action?term=", term, "&sessionPeriod=", @@ -514,7 +573,7 @@ get_committee_record <- function(term = 8, session_period = NULL, verbose = TRUE "&sessionTimes=01&meetingTimes=&fileType=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { diff --git a/R/parlquestions.R b/R/parlquestions.R index d7da8909..1f390be0 100644 --- a/R/parlquestions.R +++ b/R/parlquestions.R @@ -1,82 +1,78 @@ -#'The Records of Parliamentary Questions 委員質詢事項資訊 +#' The Records of Parliamentary Questions 委員質詢事項資訊 #' -#'@author David Liao (davidycliao@@gmail.com) +#' @author David Liao (davidycliao@@gmail.com) #' -#'@param term numeric or NULL. The data is only available from 8th term. -#'The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。 +#' @param term numeric or NULL. The data is only available from 8th term. +#' The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。 #' -#'@param session_period integer, numeric or NULL. Available -#'options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to 8 參數必須為數值。 -#'`review_session_info()` generates each session period available option period +#' @param session_period integer, numeric or NULL. Available +#' options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to 8 參數必須為數值。 +#' `review_session_info()` generates each session period available option period #' in Minguo (Taiwan) calendar. #' -#'@param verbose logical, indicates whether `get_parlquestions` should print out -#'detailed output when retrieving the data. The default is TRUE -#' -#'@return list contains: \describe{ -#'\item{`title`}{the records of parliamentary questions} -#'\item{`query_time`}{the queried time} -#'\item{`retrieved_number`}{the total number of observations} -#'\item{`retrieved_term`}{the queried term} -#'\item{`url`}{the retrieved json url} -#'\item{`variable_names`}{the variables of the tibble dataframe} -#'\item{`manual_info`}{the offical manual from \url{https://data.ly.gov.tw/getds.action?id=6}, or use legisTaiwan::get_variable_info("get_parlquestions")} -#'\item{`data`}{a tibble dataframe, whose variables include: -#' \describe{\item{`term`}{屆別} -#' \item{`sessionPeriod`}{會期} -#' \item{`sessionTimes`}{會次} -#' \item{`item`}{項目} -#' \item{`selectTerm`}{屆別期別篩選條件} -#' } -#' } -#' } -#' -#'@importFrom attempt stop_if_all -#'@importFrom jsonlite fromJSON -#' -#'@export -#' -#'@examples -#' ## query parliamentary questions by term. +#' @param verbose logical, indicates whether `get_parlquestions` should print out +#' detailed output when retrieving the data. The default is TRUE. +#' +#' @return A list containing: +#' \describe{ +#' \item{`title`}{the records of parliamentary questions} +#' \item{`query_time`}{the queried time} +#' \item{`retrieved_number`}{the total number of observations} +#' \item{`retrieved_term`}{the queried term} +#' \item{`url`}{the retrieved json url} +#' \item{`variable_names`}{the variables of the tibble dataframe} +#' \item{`manual_info`}{the offical manual from \url{https://data.ly.gov.tw/getds.action?id=6}, or use get_variable_info("get_parlquestions")} +#' \item{`data`}{a tibble dataframe, whose variables include: +#' \describe{ +#' \item{`term`}{屆別} +#' \item{`sessionPeriod`}{會期} +#' \item{`sessionTimes`}{會次} +#' \item{`item`}{項目} +#' \item{`selectTerm`}{屆別期別篩選條件} +#' } +#' } +#' } +#' +#' @importFrom attempt stop_if_all +#' @importFrom jsonlite fromJSON +#' @importFrom withr with_options +#' @export +#' +#' @examples +#' ## Query parliamentary questions by term. #' ## 輸入「立委會期」下載立委質詢資料 -#'get_parlquestions(term = 8) +#' get_parlquestions(term = 8) #' -#' ## query parliamentary questions by term. +#' ## Query parliamentary questions by term and session period. #' ## 輸入「立委屆期」與「會期」下載立委質詢資料 -#'get_parlquestions(term = 8, session_period = 2) -#' -#' ## query parliamentary questions by term. -#' ## 輸入「空白」下載立委全部質詢資料 -#'get_parlquestions(term = 8, session_period = 2) +#' get_parlquestions(term = 8, session_period = 2) #' -#'@details get_parlquestions` produces a list, which contains `title`, -#'`query_time`, `retrieved_number`, `retrieved_term`, `url`, `variable_names`, -#' `manual_info` and `data`. +#' @details `get_parlquestions` produces a list, which contains `title`, +#' `query_time`, `retrieved_number`, `retrieved_term`, `url`, `variable_names`, +#' `manual_info`, and `data`. #' -#'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_parlquestions")` +#' @note To retrieve the user manual and more information about variable of the data +#' frame, please use `get_variable_info("get_parlquestions")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=6}. #' 質詢類: 提供議事日程本院委員之質詢事項資訊(自第8屆第1會期起)。 #' -#'@seealso -#'`get_variable_info("get_parlquestions")` - +#' @seealso `get_variable_info("get_parlquestions")` get_parlquestions <- function(term = 8, session_period = NULL, verbose = TRUE) { - legisTaiwan::check_internet() + check_internet() if (is.null(term)) { - options(timeout = max(1000, getOption("timeout"))) - set_api_url <- paste("https://data.ly.gov.tw/odw/ID6Action.action?term=", term, - "&sessionPeriod=", - "&sessionTimes=&item=&fileType=json", sep = "") - message(" term is not defined...\n You are now requesting full data from the API. Please make sure your connectivity is stable until its completion.\n") + set_api_url <- paste("https://data.ly.gov.tw/odw/ID6Action.action?term=", term, + "&sessionPeriod=", + "&sessionTimes=&item=&fileType=json", sep = "") + message(" term is not defined...\n You are now requesting full data from the API. Please make sure your connectivity is stable until its completion.\n") } else { attempt::stop_if_all(term, is.character, msg = "use numeric format only.") if (length(term) == 1) { term <- sprintf("%02d", as.numeric(term))} else if (length(term) > 1) { - options(timeout = max(1000, getOption("timeout"))) - term <- paste(sprintf("%02d", as.numeric(term)), collapse = "&") - message("The API is unable to query multiple terms and the retrieved data might not be complete.")} + options(timeout = max(1000, getOption("timeout"))) + term <- paste(sprintf("%02d", as.numeric(term)), collapse = "&") + stop("The API is unable to query multiple terms.") + } } set_api_url <- paste("https://data.ly.gov.tw/odw/ID6Action.action?term=", term, "&sessionPeriod=", @@ -84,7 +80,7 @@ get_parlquestions <- function(term = 8, session_period = NULL, verbose = TRUE) { "&sessionTimes=&item=&fileType=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { @@ -151,7 +147,7 @@ get_parlquestions <- function(term = 8, session_period = NULL, verbose = TRUE) { #' #'@importFrom attempt stop_if_all #'@importFrom jsonlite fromJSON -#' +#'@importFrom withr with_options #'@export #' #'@examples @@ -162,11 +158,11 @@ get_parlquestions <- function(term = 8, session_period = NULL, verbose = TRUE) { #'@details **`get_executive_response`** produces a list, which contains `title`, #'`query_time`, `retrieved_number`, `retrieved_term`, `url`, `variable_names`, #' `manual_info` and `data`. To retrieve the user manual and more information, please -#' use `legisTaiwan::get_variable_info("get_executive_response")`. +#' use `get_variable_info("get_executive_response")`. #' #' #'#'@note To retrieve the user manual and more information about variable of the data -#' frame, please use `legisTaiwan::get_variable_info("get_executive_response")` +#' frame, please use `get_variable_info("get_executive_response")` #' or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=2}. #' 質詢類: 提供公報質詢事項行政院答復資訊 (自第8屆第1會期起)。 #' @@ -175,21 +171,20 @@ get_parlquestions <- function(term = 8, session_period = NULL, verbose = TRUE) { get_executive_response <- function(term = NULL, session_period = NULL, verbose = TRUE) { - legisTaiwan::check_internet() + check_internet() if (is.null(term)) { - options(timeout = max(1000, getOption("timeout"))) - set_api_url <- paste("https://data.ly.gov.tw/odw/ID2Action.action?term=", - term, "&sessionPeriod=", - "&sessionTimes=&item=&fileType=json", sep = "") - message(" term is not defined...\n You are now requesting full data from the API. Please make sure your connectivity is stable until its completion.\n") + set_api_url <- paste("https://data.ly.gov.tw/odw/ID2Action.action?term=", + term, "&sessionPeriod=", + "&sessionTimes=&item=&fileType=json", sep = "") + message(" term is not defined...\n You are now requesting full data from the API. Please make sure your connectivity is stable until its completion.\n") } else { attempt::stop_if_all(term, is.character, msg = "use numeric format only.") if (length(term) == 1) { term <- sprintf("%02d", as.numeric(term))} else if (length(term) > 1) { - options(timeout = max(1000, getOption("timeout"))) term <- paste(sprintf("%02d", as.numeric(term)), collapse = "&") - message("The API is unable to query multiple terms and the retrieved data might not be complete.")} + stop("The API is unable to query multiple terms.") + } } set_api_url <- paste("https://data.ly.gov.tw/odw/ID2Action.action?term=", term, "&sessionPeriod=", @@ -197,7 +192,7 @@ get_executive_response <- function(term = NULL, session_period = NULL, verbose = "&sessionTimes=&item=&fileType=json", sep = "") tryCatch( { - json_df <- jsonlite::fromJSON(set_api_url) + with_options(list(timeout = max(1000, getOption("timeout"))),{json_df <- jsonlite::fromJSON(set_api_url)}) df <- tibble::as_tibble(json_df$dataList) attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.") if (isTRUE(verbose)) { diff --git a/R/utils.R b/R/utils.R index ea44f72f..b499a690 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,19 +1,38 @@ -### Package Utility Functions - -#' @export .onAttach -.onAttach <- function(...) { - packageStartupMessage("## legisTaiwan ###") - packageStartupMessage("## An R package connecting to the Taiwan Legislative API. ###") - +#' Validate Date Formats +#' +#' This function checks if the provided start and end dates are in the correct numeric format. +#' +#' @param start_date A string representing the start date. Expected format is numeric, e.g., "1090101". +#' @param end_date A string representing the end date. Expected format is numeric, e.g., "1090101". +#' @return NULL. If the dates are not in the expected format, an error is thrown. +#' @examples +#' # This should throw an error: +#' \dontrun{ +#' validate_dates_format("10901", "1100101") +#' } +#' @keywords internal +validate_dates_format <- function(start_date, end_date) { + valid_date_format <- function(date) { + return(grepl("^\\d{7}$", date)) + } + + if (!valid_date_format(start_date) || !valid_date_format(end_date)) { + stop("Dates should be in numeric format. E.g., 1090101.") + } } -#'A Check for the Website Availability I + +#' Check for the Website Availability I #' -#'@param site https://data.ly.gov.tw/index.action +#' This function checks the availability of a specified website by trying to read +#' the first line of the site's content. #' -#'@seealso -#' `check_internet()`, - +#' @param site A website URL to check. Default is "https://data.ly.gov.tw/index.action". +#' +#' @seealso +#' `check_internet()` +#' +#' @keywords internal website_availability <- function(site = "https://data.ly.gov.tw/index.action") { tryCatch({ readLines(site, n = 1) @@ -23,15 +42,16 @@ website_availability <- function(site = "https://data.ly.gov.tw/index.action") { error = function(e) FALSE) } -#'A Check for the Website Availability II +#' Check for the Website Availability II #' -#'@param site https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0 +#' This function checks the availability of a specified website by trying to read +#' the first line of the site's content. #' -#'@seealso -#' `check_internet()`, `website_availability()` -#'@export - -website_availability2 <- function(site = "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0n") { +#' @param site A website URL to check. Default is "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0". +#' +#' @keywords internal +#' @seealso `check_internet()` and `website_availability()`. +website_availability2 <- function(site = "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0") { tryCatch({ readLines(site, n = 1) TRUE @@ -51,11 +71,10 @@ website_availability2 <- function(site = "https://npl.ly.gov.tw/do/www/appDate?s #' #'@importFrom curl has_internet #' -#'@export - +#'@keywords internal check_internet <- function(x = curl::has_internet()) { attempt::stop_if_not(.x = x, - msg = "Please check the internet connetion") + msg = "Please check the internet connection") } #' A General Check for Taiwan Legislative Yuan API @@ -65,46 +84,61 @@ check_internet <- function(x = curl::has_internet()) { #'@param end_date end_date is inherited from global env. #' #'@importFrom attempt stop_if_not -#' -#'@export - +#'@keywords internal +# api_check <- function(start_date = start_date, end_date = end_date) { +# attempt::stop_if_all(start_date > as.Date(Sys.time()), +# isTRUE, msg = "The start date should not be after the system time") +# attempt::stop_if_all(end_date > as.Date(Sys.time()), +# isTRUE, msg = "The end date should not be after the system time") +# attempt::stop_if_all(start_date, is.character, msg = "use numeric format") +# attempt::stop_if_all(end_date, is.character, msg = "use numeric format") +# attempt::stop_if_all(start_date, is.null, msg = "start_date is missing") +# attempt::stop_if_all(end_date, is.null, msg = "end_date is missing") +# attempt::stop_if_all(end_date > start_date, isFALSE, +# msg = paste("The start date, ", start_date, ",", " should not be later than the end date, ", +# end_date, ".", sep = "")) +# } api_check <- function(start_date = start_date, end_date = end_date) { + attempt::stop_if_all(start_date > as.Date(Sys.time()), - isTRUE, msg = "The start date should not be after the system time") + isTRUE, msg = "The start date should not be after the current system time.") attempt::stop_if_all(end_date > as.Date(Sys.time()), - isTRUE, msg = "The end date should not be after the system time") - attempt::stop_if_all(start_date, is.character, msg = "use numeric format") - attempt::stop_if_all(end_date, is.character, msg = "use numeric format") - attempt::stop_if_all(start_date, is.null, msg = "start_date is missing") - attempt::stop_if_all(end_date, is.null, msg = "end_date is missing") + isTRUE, msg = "The end date should not be after the current system time.") + attempt::stop_if_all(start_date, is.character, + msg = "Use numeric format for start_date.") + attempt::stop_if_all(end_date, is.character, + msg = "Use numeric format for end_date.") + attempt::stop_if_all(start_date, is.null, + msg = "The parameter 'start_date' is missing.") + attempt::stop_if_all(end_date, is.null, + msg = "The parameter 'end_date' is missing.") attempt::stop_if_all(end_date > start_date, isFALSE, - msg = paste("The start date,", start_date, ",", "should not be later than the end date,", - end_date, ".", sep = " ")) + msg = paste("The start date, ", start_date, ",", " should not be later than the end date, ", + end_date, ".", sep = "")) } #' Transforming Minguo (Taiwan) Calendar to A.D. Calendar I #' -#'@description `transformed_date_meeting()` transforms Minguo (Taiwan) Calendar -#'to A.D. calendar in POSIXct for `get_meetings()`, `get_caucus_meetings()`, -#'and `get_speech_video()`, +#' @description `transformed_date_meeting()` transforms Minguo (Taiwan) Calendar +#' to A.D. calendar in POSIXct for `get_meetings()`, `get_caucus_meetings()`, +#' and `get_speech_video()`, #' +#' @param roc_date Date format in Minguo (Taiwan) calendar (e.g., "105/05/31") as a +#' string vector #' -#'@param roc_date Date format in Minguo (Taiwan) calendar (e.g., "105/05/31") as a -#'string vector +#' @return date in POSIXct #' -#'@return date in POSIXct -#' -#'@importFrom stringr str_split_1 +#' @importFrom stringr str_split_1 #' -#'@export +#' @keywords internal #' -#'@examples -#'transformed_date_meeting("105/05/31") +#' @examples +#' \dontrun{ +#' transformed_date_meeting("105/05/31") +#' } #' -#'@details `check_date` transforms ROC date to a date in POSIXct, e.g. "105/05/31" to "2016-05-31". - - +#' @details `check_date` transforms ROC date to a date in POSIXct, e.g. "105/05/31" to "2016-05-31". transformed_date_meeting <- function(roc_date) { roc_date <- stringr::str_split_1(roc_date, "/") date_ad <- as.Date(as.POSIXct(paste(as.numeric(roc_date[1]) + 1911, @@ -117,17 +151,21 @@ transformed_date_meeting <- function(roc_date) { #' Transforming Minguo (Taiwan) Calendar to A.D. Calendar II #' -#'@description `transformed_date_meeting()` transforms Minguo (Taiwan) Calendar -#'to A.D. format in POSIXct for `get_bill()`, e.g. "1050531" to "2016-05-31". +#' @description `transformed_date_meeting()` transforms Minguo (Taiwan) Calendar +#' to A.D. format in POSIXct for `get_bill()`, e.g. "1050531" to "2016-05-31". #' -#'@param roc_date date format in Taiwan ROC calendar (e.g., "1050531") in a character vector +#' @param roc_date date format in Taiwan ROC calendar (e.g., "1050531") in a character vector #' -#'@return date in POSIXct +#' @return date in POSIXct #' -#'@importFrom stringr str_sub +#' @importFrom stringr str_sub #' -#'@export - +#' @keywords internal +#' +#' @examples +#' \dontrun{ +#' transformed_date_bill("1050531") +#' } transformed_date_bill <- function(roc_date) { day <- stringr::str_sub(roc_date, -2, -1) month <- stringr::str_sub(roc_date, -4, -3) @@ -151,8 +189,7 @@ transformed_date_bill <- function(roc_date) { #' #'@importFrom stringr str_sub #' -#'@export - +#'@keywords internal check_date <- function(roc_date) { day <- stringr::str_sub(roc_date, -2, -1) month <- stringr::str_sub(roc_date, -4, -3) @@ -177,13 +214,14 @@ check_date <- function(roc_date) { #' #'@importFrom stringr str_split_1 #' -#'@export +#'@keywords internal #' -#'@examples -#'check_date2("105/05/31") +#' @examples +#' \dontrun{ +#' check_date2("105/05/31") +#' } #' #'@details `check_date` transforms ROC date to a date in POSIXct, e.g. "105/05/31" to "2016-05-31". - check_date2 <- function(roc_date) { roc_date <- stringr::str_split_1(roc_date, "/") date_ad <- as.Date(as.POSIXct(paste(as.numeric(roc_date[1]) + 1911, diff --git a/R/zzz.R b/R/zzz.R new file mode 100644 index 00000000..31493d64 --- /dev/null +++ b/R/zzz.R @@ -0,0 +1,8 @@ +### Package Utility Functions +#' On package attach, display a startup message to the user. +#' +#' @keywords internal +.onAttach <- function(...) { + packageStartupMessage("## legisTaiwan ##") + packageStartupMessage("## An R package connecting to the Taiwan Legislative API. ##") +} diff --git a/README.md b/README.md index aea4ad94..81755306 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,8 @@ coverage](https://github.com/davidycliao/legisTaiwan/actions/workflows/test-cove `legisTaiwan` is designed to download the real-time archives of Taiwan legislative data easily. This package includes many streamlined functions to access [Taiwan Legislative Yuan -API](https://data.ly.gov.tw/index.action) and efficiently perform -analysis and natural language processing tasks in R without any hassle -or runarounds. +API](https://data.ly.gov.tw/index.action) in R without any hassle or +runarounds. @@ -37,21 +36,21 @@ remotes::install_github("davidycliao/legisTaiwan", force = TRUE) ``` r library(legisTaiwan) -#> ## legisTaiwan ### -#> ## An R package connecting to the Taiwan Legislative API. ### +#> ## legisTaiwan ## +#> ## An R package connecting to the Taiwan Legislative API. ## ``` ## Caution:
-`legisTaiwan` requires stable internet connectivity for any data -retrieval function from the API. Most functions can be directly used to -retrieve a long period of data but are extremely bandwidth-intensive, -given the download sizes of these data stores. When downloading a more -extended period of data, I suggest using **get_variable_info()** to -double-check the current size of files on the API manual and write a -loop with appropriate handlers recording the progress of file input to -make sure the requested data is complete. +`legisTaiwan` requires a stable internet connection to retrieve data +from the API. While most functions can fetch data spanning a long +period, they tend to be bandwidth-intensive due to the size of the +datasets. If you plan to download data over an extended period, I +recommend using get_variable_info() first to verify the current file +sizes on the API manual. Also, consider writing a batch retrieval +process with appropriate handlers to track the progress of file input, +ensuring the completeness of the requested data.
diff --git a/_pkgdown.yml b/_pkgdown.yml index 3f2cffcb..ae430b7f 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -33,17 +33,6 @@ reference: - get_legislators - get_variable_info - review_session_info -- title: Utility - desc: internal functions supports `legisTaiwan` function -- contents: - - website_availability - - website_availability2 - - check_internet - - api_check - - check_date - - check_date2 - - transformed_date_meeting - - transformed_date_bill authors: David Yen-Chieh Liao: @@ -102,6 +91,8 @@ navbar: - icon: fa-newspaper-o text: News menu: + - text: "0.1.6" + href: news/index.html#legistaiwan-016-development-version - text: "0.1.4" href: news/index.html#legistaiwan-014-development-version - text: "0.1.3" diff --git a/inst/.DS_Store b/inst/.DS_Store new file mode 100644 index 00000000..82c0810f Binary files /dev/null and b/inst/.DS_Store differ diff --git a/CONDUCT.md b/inst/CONDUCT.md similarity index 100% rename from CONDUCT.md rename to inst/CONDUCT.md diff --git a/README.Rmd b/inst/README.Rmd similarity index 72% rename from README.Rmd rename to inst/README.Rmd index 6782bfc1..f1fa4220 100644 --- a/README.Rmd +++ b/inst/README.Rmd @@ -11,9 +11,18 @@ knitr::opts_chunk$set( fig.path = "man/figures/README-", out.width = "100%" ) + ``` -# Real-time and Archives of Taiwan Legislative Data in R + +```{r setup2, include = FALSE} +library(rmarkdown) + +render("README.Rmd", output_format = "github_document", output_dir = "..") + +``` + +# Real-time and Archives of Taiwan Legislative Data in R [![R](https://github.com/davidycliao/legisTaiwan/actions/workflows/r.yml/badge.svg)](https://github.com/davidycliao/legisTaiwan/actions/workflows/r.yml) [![codecov](https://codecov.io/gh/davidycliao/legisTaiwan/branch/master/graph/badge.svg?token=HVVTCOE90D)](https://codecov.io/gh/davidycliao/legisTaiwan) @@ -26,7 +35,7 @@ knitr::opts_chunk$set(
-`legisTaiwan` is designed to download the real-time archives of Taiwan legislative data easily. This package includes many streamlined functions to access [Taiwan Legislative Yuan API](https://data.ly.gov.tw/index.action) and efficiently perform analysis and natural language processing tasks in R without any hassle or runarounds. +`legisTaiwan` is designed to download the real-time archives of Taiwan legislative data easily. This package includes many streamlined functions to access [Taiwan Legislative Yuan API](https://data.ly.gov.tw/index.action) in R without any hassle or runarounds.
@@ -48,6 +57,9 @@ library(legisTaiwan) ## Caution:
-`legisTaiwan` requires stable internet connectivity for any data retrieval function from the API. Most functions can be directly used to retrieve a long period of data but are extremely bandwidth-intensive, given the download sizes of these data stores. When downloading a more extended period of data, I suggest using __get_variable_info()__ to double-check the current size of files on the API manual and write a loop with appropriate handlers recording the progress of file input to make sure the requested data is complete. + +`legisTaiwan` requires a stable internet connection to retrieve data from the API. While most functions can fetch data spanning a long period, they tend to be bandwidth-intensive due to the size of the datasets. If you plan to download data over an extended period, I recommend using get_variable_info() first to verify the current file sizes on the API manual. Also, consider writing a batch retrieval process with appropriate handlers to track the progress of file input, ensuring the completeness of the requested data.
+ + diff --git a/man/api_check.Rd b/man/api_check.Rd index 54329880..79fc5efd 100644 --- a/man/api_check.Rd +++ b/man/api_check.Rd @@ -14,3 +14,4 @@ api_check(start_date = start_date, end_date = end_date) \description{ A General Check for Taiwan Legislative Yuan API } +\keyword{internal} diff --git a/man/check_date.Rd b/man/check_date.Rd index a0c4713a..2a675c11 100644 --- a/man/check_date.Rd +++ b/man/check_date.Rd @@ -17,3 +17,4 @@ date in POSIXct \code{transformed_date_meeting()} transforms Minguo (Taiwan) Calendar to A.D. format in POSIXct for \code{get_bill()}, e.g. "1050531" to "2016-05-31". } +\keyword{internal} diff --git a/man/check_date2.Rd b/man/check_date2.Rd index c3a3b138..f7b0c7ca 100644 --- a/man/check_date2.Rd +++ b/man/check_date2.Rd @@ -21,6 +21,9 @@ to A.D. format in POSIXct for \code{get_bill()}, e.g. "1050531" to "2016-05-31". \code{check_date} transforms ROC date to a date in POSIXct, e.g. "105/05/31" to "2016-05-31". } \examples{ +\dontrun{ check_date2("105/05/31") +} } +\keyword{internal} diff --git a/man/check_internet.Rd b/man/check_internet.Rd index a300b84e..c3948189 100644 --- a/man/check_internet.Rd +++ b/man/check_internet.Rd @@ -13,3 +13,4 @@ internet connectivity check.} \description{ A Check for Internet Connectivity. } +\keyword{internal} diff --git a/man/dot-onAttach.Rd b/man/dot-onAttach.Rd new file mode 100644 index 00000000..90879cf7 --- /dev/null +++ b/man/dot-onAttach.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/zzz.R +\name{.onAttach} +\alias{.onAttach} +\title{On package attach, display a startup message to the user.} +\usage{ +.onAttach(...) +} +\description{ +On package attach, display a startup message to the user. +} +\keyword{internal} diff --git a/man/get_bills.Rd b/man/get_bills.Rd index a0dea76c..07300360 100644 --- a/man/get_bills.Rd +++ b/man/get_bills.Rd @@ -2,82 +2,73 @@ % Please edit documentation in R/bill.R \name{get_bills} \alias{get_bills} -\title{The Records of the Bills 法律提案} +\title{The Records of the Bills: 法律提案} \usage{ get_bills(start_date = NULL, end_date = NULL, proposer = NULL, verbose = TRUE) } \arguments{ -\item{start_date}{numeric Must be formatted in Minguo (Taiwan) calendar, e.g. 1090101.} +\item{start_date}{numeric. Must be formatted in the ROC Taiwan calendar, e.g., 1090101.} -\item{end_date}{numeric Must be formatted in Minguo (Taiwan) calendar, e.g. 1090102.} +\item{end_date}{numeric. Must be formatted in the ROC Taiwan calendar, e.g., 1090102.} -\item{proposer}{The default value is NULL, which means all bill proposed by all legislators -are included between the starting date and the ending date.} +\item{proposer}{The default value is NULL, indicating that bills proposed by all legislators +are included between the start and end dates.} -\item{verbose}{logical, indicates whether \code{get_bills} should print out +\item{verbose}{logical. Specifies whether \code{get_bills} should print out detailed output when retrieving the data. The default value is TRUE.} } \value{ -list, which contains: \describe{ -\item{\code{title}}{the meeting records of cross-caucus session} -\item{\code{query_time}}{the query time} -\item{\code{retrieved_number}}{the number of observation} -\item{\code{meeting_unit}}{the meeting unit} -\item{\code{start_date_ad}}{the start date in POSIXct} -\item{\code{end_date_ad}}{the end date in POSIXct} -\item{\code{start_date}}{the start date in ROC Taiwan calendar} -\item{\code{url}}{the retrieved json url} -\item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153}; or use legisTaiwan::get_variable_info("get_bills")} -\item{\code{data}}{a tibble dataframe, whose variables include: -\describe{\item{\code{term}}{屆別} -\item{\code{sessionPeriod}}{會期} -\item{\code{sessionTimes}}{會次} -\item{\code{meetingTimes}}{提案日期} -\item{\code{billName}}{提案名稱} -\item{\code{billProposer}}{主提案人} -\item{\code{billCosignatory}}{連署提案} -\item{\code{billStatus}}{議案狀態} -\item{\code{date_ad}}{西元年} +A list, which contains: +\describe{ +\item{\code{title}}{Records of cross-caucus sessions} +\item{\code{query_time}}{Query timestamp} +\item{\code{retrieved_number}}{Number of observations retrieved} +\item{\code{meeting_unit}}{Meeting unit} +\item{\code{start_date_ad}}{Start date in POSIXct format} +\item{\code{end_date_ad}}{End date in POSIXct format} +\item{\code{start_date}}{Start date in the ROC Taiwan calendar} +\item{\code{url}}{URL of the retrieved JSON data} +\item{\code{variable_names}}{Variable names of the tibble dataframe} +\item{\code{manual_info}}{Official manual. See \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153} or use get_variable_info("get_bills")} +\item{\code{data}}{A tibble dataframe with the following variables: +\describe{\item{\code{term}}{Session number} +\item{\code{sessionPeriod}}{Session period} +\item{\code{sessionTimes}}{Session count} +\item{\code{meetingTimes}}{Proposal date} +\item{\code{billName}}{Bill name} +\item{\code{billProposer}}{Primary proposer} +\item{\code{billCosignatory}}{Co-signatories of the bill} +\item{\code{billStatus}}{Status of the bill} +\item{\code{date_ad}}{Date in the Gregorian calendar} } } } } \description{ -The Records of the Bills 法律提案 +The Records of the Bills: 法律提案 } \details{ -\code{get_bills} produces a list, which contains \code{query_time}, +The \code{get_bills} function returns a list that contains \code{query_time}, \code{retrieved_number}, \code{meeting_unit}, \code{start_date_ad}, \code{end_date_ad}, \code{start_date}, -\code{end_date}, \code{url}, \code{variable_names}, \code{manual_info} and \code{data}. +\code{end_date}, \code{url}, \code{variable_names}, \code{manual_info}, and \code{data}. } \note{ -To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_bills")} -or visit the API manual at \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153}. -資料似乎不一致，待確認。委員發言（取得最早時間不詳，待檢查。） +To retrieve the user manual and more details about the data frame, use \code{get_variable_info("get_bills")}. +Further checks are required as the user manual seems to be inconsistent with the actual data. } \examples{ -## query bill records by a period of the dates in Taiwan ROC calender format -## 輸入「中華民國民年」下載立法委員提案資料 +\dontrun{ +## Query bill records by a date range in the Taiwan ROC calendar format get_bills(start_date = 1060120, end_date = 1070310, verbose = FALSE) -## query bill records by a period of the dates in Taiwan ROC calender format -## and a specific legislator -## 輸入「中華民國民年」與「指定立法委員」下載立法委員提案資料 +## Query bill records by a date range and a specific legislator get_bills(start_date = 1060120, end_date = 1070310, proposer = "孔文吉") -## query bill records by a period of the dates in Taiwan ROC calender format -## and multiple legislators -## 輸入「中華民國民年」與「指定多個立法委員」下載立法委員提案資料 +## Query bill records by a date range and multiple legislators get_bills(start_date = 1060120, end_date = 1060510, proposer = "孔文吉&鄭天財") - } -\seealso{ -\code{get_variable_info("get_bills_2")},\code{review_session_info()} -Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. } -\author{ -David Liao (davidycliao@gmail.com) +\seealso{ +\url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153} } diff --git a/man/get_bills_2.Rd b/man/get_bills_2.Rd index debdfa46..aa24eb83 100644 --- a/man/get_bills_2.Rd +++ b/man/get_bills_2.Rd @@ -2,37 +2,33 @@ % Please edit documentation in R/bill.R \name{get_bills_2} \alias{get_bills_2} -\title{The Records of Legislation and the Executives Proposals 委員及政府議案提案資訊} +\title{The Records of Legislation and the Executives Proposals: 委員及政府議案提案資訊} \usage{ get_bills_2(term = 8, session_period = NULL, verbose = TRUE) } \arguments{ -\item{term}{numeric or null. The data is only available from 8th term. -The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。} +\item{term}{A numeric or NULL value. Data is available from the 8th term onwards. +Default is set to 8. 參數必須為數值。資料從第8屆開始，預設值為8。} -\item{session_period}{integer, numeric or NULL. Available -options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to NULL. +\item{session_period}{An integer, numeric, or NULL. Valid options for the session are: +1, 2, 3, 4, 5, 6, 7, and 8. Default is set to NULL. 參數必須為數值。 -\code{review_session_info()} generates each session period available option period -in Minguo (Taiwan) calendar.} +\code{review_session_info()} provides available session periods based on the Minguo (Taiwan) calendar.} -\item{verbose}{The default value is TRUE, displaying the description of data -retrieved in number, url and computing time.} +\item{verbose}{Default value is TRUE. Displays details of the retrieved data, including the number, URL, and computing time.} } \value{ -list list, which contains: \describe{ -\item{\code{title}}{the meeting records of cross-caucus session} -\item{\code{query_time}}{the query time} -\item{\code{retrieved_number}}{the number of observation} -\item{\code{meeting_unit}}{the meeting unit} -\item{\code{start_date_ad}}{the start date in POSIXct} -\item{\code{end_date_ad}}{the end date in POSIXct} -\item{\code{start_date}}{the start date in ROC Taiwan calendar} -\item{\code{url}}{the retrieved json url} -\item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=20}; or use legisTaiwan::get_variable_info("get_bills_2")} -\item{\code{data}}{a tibble dataframe, whose variables include: -\describe{\item{\code{term}}{屆別} +A list containing: +\item{\code{title}}{Records of questions answered by the executives} +\item{\code{query_time}}{Query time} +\item{\code{retrieved_number}}{Number of observations} +\item{\code{retrieved_term}}{Retrieved term} +\item{\code{url}}{Retrieved JSON URL} +\item{\code{variable_names}}{Variables of the tibble dataframe} +\item{\code{manual_info}}{Official manual: \url{https://data.ly.gov.tw/getds.action?id=20} or use \code{get_variable_info("get_bills_2")}} +\item{\code{data}}{A tibble dataframe with variables such as: +\describe{ +\item{\code{term}}{屆別} \item{\code{sessionPeriod}}{會期} \item{\code{sessionTimes}}{會次} \item{\code{meetingTimes}}{臨時會會次} @@ -42,32 +38,31 @@ list list, which contains: \describe{ \item{\code{billProposer}}{主提案人} \item{\code{billCosignatory}}{連署提案} \item{\code{billStatus}}{議案狀態} -\item{\code{pdfUrl}}{關係文書pdf檔案下載位置} -\item{\code{docUrl}}{關係文書doc檔案下載位置} -\item{\code{selectTerm}}{屆別期別篩選條件} -} +\item{\code{pdfUrl}}{PDF download link for related documents} +\item{\code{docUrl}}{DOC download link for related documents} +\item{\code{selectTerm}}{Filtering criteria based on term} } } } \description{ -The Records of Legislation and the Executives Proposals 委員及政府議案提案資訊 +The Records of Legislation and the Executives Proposals: 委員及政府議案提案資訊 } \details{ -\code{get_bills_2} produces a list, which contains \code{query_time}, -\code{retrieved_number}, \code{meeting_unit}, \code{start_date_ad}, \code{end_date_ad}, \code{start_date}, -\code{end_date}, \code{url}, \code{variable_names}, \code{manual_info} and \code{data}. To retrieve the user -manual and more information about the data frame, please use \code{legisTaiwan::get_variable_info("get_bills_2")}. +The \code{get_bills_2} function produces a list, which includes \code{query_time}, +\code{retrieved_number}, \code{retrieved_term}, \code{url}, \code{variable_names}, \code{manual_info}, and \code{data}. +For the user manual and more information about the dataframe, use \code{get_variable_info("get_bills_2")}. } \note{ -To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_bills_2")} +For more details about the dataframe's variables, use \code{get_variable_info("get_bills_2")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=20}. -議事類: 提供委員及政府之議案提案資訊 (自第8屆第1會期起)。 +議事類: 提供委員及政府之議案提案資訊 (從第8屆第1會期開始)。 } \examples{ -## query the Executives' answered response by term and the session period. -## 輸入「立委屆期」與「會期」下載「質詢事項 (行政院答復部分)」 +\dontrun{ +## Query the executives' responses by term and session period. +## 輸入「立委屆期」與「會期」以下載「質詢事項 (行政院答復部分)」 get_bills_2(term = 8, session_period = 1) +} } \seealso{ diff --git a/man/get_caucus_meetings.Rd b/man/get_caucus_meetings.Rd index 0b05f280..7f80a029 100644 --- a/man/get_caucus_meetings.Rd +++ b/man/get_caucus_meetings.Rd @@ -27,7 +27,7 @@ list, which contains: \describe{ \item{\code{start_date}}{the start date in ROC Taiwan calendar} \item{\code{url}}{the retrieved json url} \item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=8}; or use legisTaiwan::get_variable_info("get_caucus_meetings")} +\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=8}; or use get_variable_info("get_caucus_meetings")} \item{\code{data}}{a tibble dataframe, whose variables include: \describe{\item{\code{comYear}}{卷} \item{\code{comVolume}}{期} @@ -58,7 +58,7 @@ The Meeting Records of Cross-caucus Session 黨團協商資訊 } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_caucus_meetings")} +frame, please use \code{get_variable_info("get_caucus_meetings")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=8}. 議事類:提供公報之黨團協商資訊 (自第8屆第1會期起) } diff --git a/man/get_committee_record.Rd b/man/get_committee_record.Rd index 118997f1..7f6d8e8b 100644 --- a/man/get_committee_record.Rd +++ b/man/get_committee_record.Rd @@ -4,60 +4,93 @@ \alias{get_committee_record} \title{The Records of Reviewed Items in the Committees 委員會會議審查之議案項目} \usage{ -get_committee_record(term = 8, session_period = NULL, verbose = TRUE) +get_committee_record(term = 10, session_period = NULL, verbose = TRUE) } \arguments{ -\item{term}{numeric or null. The data is only available from 8th term. -The default is set to 8. 參數必須為數值。資料從自第8屆起，預設值為8。} +\item{term}{numeric or null. Data is available only from the 8th term. +The default is set to 10. 參數必須為數值。提供委員會會議審查之議案項目。(自第10屆第1會期起)} -\item{session_period}{integer, numeric or NULL. Available -options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to NULL. 參數必須為數值。 -\code{review_session_info()} generates each session period available option period -in Minguo (Taiwan) calendar.} +\item{session_period}{integer, numeric or NULL. +\code{review_session_info()} provides each session period's available options based on the +Minguo (Taiwan) calendar.} -\item{verbose}{logical, indicates whether \code{get_executive_response} should -print out detailed output when retrieving the data. The default is TRUE} +\item{verbose}{logical. This indicates whether \code{get_executive_response} should +print a detailed output during data retrieval. Default is TRUE.} } \value{ -list contains: \describe{ -\item{\code{title}}{the records of the questions answered by the executives} -\item{\code{query_time}}{the queried time} -\item{\code{retrieved_number}}{the total number of observations} -\item{\code{retrieved_term}}{the queried term} -\item{\code{url}}{the retrieved json url} -\item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use legisTaiwan::get_variable_info("get_committee_record")} -\item{\code{data}}{a tibble dataframe, whose variables include: -\describe{\item{\code{term}}{屆別} -\item{\code{sessionPeriod}}{會期} -\item{\code{meetingNo}}{會議編號} -\item{\code{billNo}}{議案編號} -\item{\code{selectTerm}}{屆別期別篩選條件} +A list containing: +\item{\code{title}}{Records of questions answered by executives} +\item{\code{query_time}}{Time of query} +\item{\code{retrieved_number}}{Total number of observations} +\item{\code{retrieved_term}}{Queried term} +\item{\code{url}}{Retrieved JSON URL} +\item{\code{variable_names}}{Variables of the tibble dataframe} +\item{\code{manual_info}}{Official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use get_variable_info("get_committee_record")} +\item{\code{data}}{A tibble dataframe with variables: +\describe{ +\item{\code{term}}{Term number} +\item{\code{sessionPeriod}}{Session} +\item{\code{meetingNo}}{Meeting number} +\item{\code{billNo}}{Bill number} +\item{\code{selectTerm}}{Term selection filter} } } + +A list containing: +\item{\code{title}}{Records of questions answered by executives} +\item{\code{query_time}}{Time of query} +\item{\code{retrieved_number}}{Total number of observations} +\item{\code{retrieved_term}}{Queried term} +\item{\code{url}}{Retrieved JSON URL} +\item{\code{variable_names}}{Variables of the tibble dataframe} +\item{\code{manual_info}}{Official manual, \url{https://data.ly.gov.tw/getds.action?id=46}; or use get_variable_info("get_committee_record")} +\item{\code{data}}{A tibble dataframe with variables: +\describe{ +\item{\code{term}}{Term number} +\item{\code{sessionPeriod}}{Session} +\item{\code{meetingNo}}{Meeting number} +\item{\code{billNo}}{Bill number} +\item{\code{selectTerm}}{Term selection filter} +} } } \description{ The Records of Reviewed Items in the Committees 委員會會議審查之議案項目 } \details{ -\code{get_committee_record} produces a list, which contains \code{title}, +\code{get_committee_record} provides a list which includes \code{title}, \code{query_time}, \code{retrieved_number}, \code{retrieved_term}, \code{url}, \code{variable_names}, -\code{manual_info} and \code{data}. +\code{manual_info}, and \code{data}. + +\code{get_committee_record} provides a list which includes \code{title}, +\code{query_time}, \code{retrieved_number}, \code{retrieved_term}, \code{url}, \code{variable_names}, +\code{manual_info}, and \code{data}. } \note{ -To retrieve the user manual and more information -about variable of the data frame, please use \code{legisTaiwan::get_variable_info("get_committee_record")} -or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=46}. -議事類: 提供委員會會議審查之議案項目 (自第8屆第1會期起)。 +To access the user manual and more information about the data frame's variables, +please refer to \code{get_variable_info("get_committee_record")} or check the API manual at +\url{https://data.ly.gov.tw/getds.action?id=46}. +This provides agenda items reviewed in committee meetings (from the 10th term, 1st session onwards). + +To access the user manual and more information about the data frame's variables, +please refer to \code{get_variable_info("get_committee_record")} or check the API manual at +\url{https://data.ly.gov.tw/getds.action?id=46}. +This provides agenda items reviewed in committee meetings (from the 10th term, 1st session onwards). } \examples{ -## query the committee record by term and the session period. +## Query the committee record by term and session period. ## 輸入「立委屆期」與「會期」下載「委員會審議之議案」 -get_committee_record(term = 8, session_period = 1) +get_committee_record(term = 10, session_period = 1) + +## Query the committee record by term and session period. +## 輸入「立委屆期」與「會期」下載「委員會審議之議案」 +get_committee_record(term = 10, session_period = 1) } \seealso{ +\code{get_variable_info("get_committee_record")}, \code{review_session_info()} +The Records of Reviewed Items in the Committees 委員會會議審查之議案項目 + \code{get_variable_info("get_committee_record")}, \code{review_session_info()} } \author{ diff --git a/man/get_executive_response.Rd b/man/get_executive_response.Rd index 2869b536..2a64ea47 100644 --- a/man/get_executive_response.Rd +++ b/man/get_executive_response.Rd @@ -51,10 +51,10 @@ The Records of Response to the Questions by the Executives 公報質詢事項行 \strong{\code{get_executive_response}} produces a list, which contains \code{title}, \code{query_time}, \code{retrieved_number}, \code{retrieved_term}, \code{url}, \code{variable_names}, \code{manual_info} and \code{data}. To retrieve the user manual and more information, please -use \code{legisTaiwan::get_variable_info("get_executive_response")}. +use \code{get_variable_info("get_executive_response")}. #'@note To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_executive_response")} +frame, please use \code{get_variable_info("get_executive_response")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=2}. 質詢類: 提供公報質詢事項行政院答復資訊 (自第8屆第1會期起)。 } diff --git a/man/get_legislators.Rd b/man/get_legislators.Rd index 7aad62ef..adaa94af 100644 --- a/man/get_legislators.Rd +++ b/man/get_legislators.Rd @@ -46,7 +46,7 @@ The Legislator' Demographic Information and Background 提供委員基本資料 } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_legislators")} +frame, please use \code{get_variable_info("get_legislators")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=16}. 提供委員基本資料，最早資料可追溯至第2屆。 } diff --git a/man/get_meetings.Rd b/man/get_meetings.Rd index a176436a..77ed0979 100644 --- a/man/get_meetings.Rd +++ b/man/get_meetings.Rd @@ -33,7 +33,7 @@ list, which contains: \describe{ \item{\code{start_date}}{the start date in ROC Taiwan calendar} \item{\code{url}}{the retrieved json url} \item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the offical manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}; or use legisTaiwan::get_variable_info("get_meetings")} +\item{\code{manual_info}}{the offical manual, \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}; or use get_variable_info("get_meetings")} \item{\code{data}}{a tibble dataframe, whose variables include: \describe{\item{\code{smeeting_date}}{會議日期} \item{\code{meeting_status}}{會議狀態} @@ -56,7 +56,7 @@ The Spoken Meeting Records 委員發言 } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_meetings")} or visit +frame, please use \code{get_variable_info("get_meetings")} or visit the API manual at \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}. 資料似乎不一致，待確認。委員發言（取得最早時間不詳，待檢查。） } diff --git a/man/get_parlquestions.Rd b/man/get_parlquestions.Rd index 44a3db33..6e5ce573 100644 --- a/man/get_parlquestions.Rd +++ b/man/get_parlquestions.Rd @@ -12,23 +12,25 @@ The default is set to 8. 參數必須為數值。資料從自第8屆起，預設 \item{session_period}{integer, numeric or NULL. Available options for the session is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is set to 8 參數必須為數值。 -\code{review_session_info()} generates each session period available option period +\code{review_session_info()} generates each session period available option period in Minguo (Taiwan) calendar.} \item{verbose}{logical, indicates whether \code{get_parlquestions} should print out -detailed output when retrieving the data. The default is TRUE} +detailed output when retrieving the data. The default is TRUE.} } \value{ -list contains: \describe{ +A list containing: +\describe{ \item{\code{title}}{the records of parliamentary questions} \item{\code{query_time}}{the queried time} \item{\code{retrieved_number}}{the total number of observations} \item{\code{retrieved_term}}{the queried term} \item{\code{url}}{the retrieved json url} \item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the offical manual from \url{https://data.ly.gov.tw/getds.action?id=6}, or use legisTaiwan::get_variable_info("get_parlquestions")} +\item{\code{manual_info}}{the offical manual from \url{https://data.ly.gov.tw/getds.action?id=6}, or use get_variable_info("get_parlquestions")} \item{\code{data}}{a tibble dataframe, whose variables include: -\describe{\item{\code{term}}{屆別} +\describe{ +\item{\code{term}}{屆別} \item{\code{sessionPeriod}}{會期} \item{\code{sessionTimes}}{會次} \item{\code{item}}{項目} @@ -41,27 +43,25 @@ list contains: \describe{ The Records of Parliamentary Questions 委員質詢事項資訊 } \details{ -get_parlquestions\verb{produces a list, which contains}title\verb{, }query_time\verb{, }retrieved_number\verb{, }retrieved_term\verb{, }url\verb{, }variable_names\verb{, }manual_info\code{and}data`. +\code{get_parlquestions} produces a list, which contains \code{title}, +\code{query_time}, \code{retrieved_number}, \code{retrieved_term}, \code{url}, \code{variable_names}, +\code{manual_info}, and \code{data}. } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_parlquestions")} +frame, please use \code{get_variable_info("get_parlquestions")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=6}. 質詢類: 提供議事日程本院委員之質詢事項資訊(自第8屆第1會期起)。 } \examples{ -## query parliamentary questions by term. +## Query parliamentary questions by term. ## 輸入「立委會期」下載立委質詢資料 get_parlquestions(term = 8) -## query parliamentary questions by term. +## Query parliamentary questions by term and session period. ## 輸入「立委屆期」與「會期」下載立委質詢資料 get_parlquestions(term = 8, session_period = 2) -## query parliamentary questions by term. -## 輸入「空白」下載立委全部質詢資料 -get_parlquestions(term = 8, session_period = 2) - } \seealso{ \code{get_variable_info("get_parlquestions")} diff --git a/man/get_public_debates.Rd b/man/get_public_debates.Rd index a0663b71..227cc0cc 100644 --- a/man/get_public_debates.Rd +++ b/man/get_public_debates.Rd @@ -29,7 +29,7 @@ list, which contains: \describe{ \item{\code{start_date}}{the start date in ROC Taiwan calendar} \item{\code{url}}{the retrieved json url} \item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=7}; or use legisTaiwan::get_variable_info("get_public_debates")} +\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=7}; or use get_variable_info("get_public_debates")} \item{\code{data}}{a tibble dataframe, whose variables include: \describe{\item{\code{term}}{屆別} \item{\code{sessionPeriod}}{會期} @@ -56,7 +56,7 @@ The Records of National Public Debates 國是論壇 } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_public_debates")} +frame, please use \code{get_variable_info("get_public_debates")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=7}. 議事類: 提供公報之國是論壇資訊，並包含書面意見。自第8屆第1會期起，但實測資料從第10屆。 } diff --git a/man/get_speech_video.Rd b/man/get_speech_video.Rd index 00a4cef0..ae3f12ef 100644 --- a/man/get_speech_video.Rd +++ b/man/get_speech_video.Rd @@ -27,7 +27,7 @@ list, which contains: \describe{ \item{\code{start_date}}{the start date in ROC Taiwan calendar} \item{\code{url}}{the retrieved json url} \item{\code{variable_names}}{the variables of the tibble dataframe} -\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=148}; or use legisTaiwan::get_variable_info("get_speech_video")} +\item{\code{manual_info}}{the official manual, \url{https://data.ly.gov.tw/getds.action?id=148}; or use get_variable_info("get_speech_video")} \item{\code{data}}{a tibble dataframe, whose variables include: \describe{\item{\code{term}}{屆別} \item{\code{sessionPeriod}}{會期} @@ -55,11 +55,11 @@ The Video Information of Meetings and Committees 院會及委員會之委員發 \code{get_speech_video} produces a list, which contains \code{title}, \code{query_time}, \code{retrieved_number}, \code{meeting_unit}, \code{start_date_ad}, \code{end_date_ad}, \code{start_date}, \code{end_date}, \code{url}, \code{variable_names}, \code{manual_info} and \code{data.} To retrieve the user -manual and more information about the data frame, please use \code{legisTaiwan::get_variable_info("get_speech_video")}. +manual and more information about the data frame, please use \code{get_variable_info("get_speech_video")}. } \note{ To retrieve the user manual and more information about variable of the data -frame, please use \code{legisTaiwan::get_variable_info("get_speech_video")} +frame, please use \code{get_variable_info("get_speech_video")} or visit the API manual at \url{https://data.ly.gov.tw/getds.action?id=148}. 會議類:提供立法院院會及委員會之委員發言片段相關影片資訊 (自第9屆第1會期起)。 } diff --git a/man/get_variable_info.Rd b/man/get_variable_info.Rd index 8406b795..2eaede37 100644 --- a/man/get_variable_info.Rd +++ b/man/get_variable_info.Rd @@ -33,8 +33,13 @@ from the website of Taiwan Legislative Yuan. The avalaible options is: \code{get \details{ \code{get_variable_info} produces a list, which contains \code{page_info} and \code{reference_url}. } +\examples{ +\dontrun{ +get_variable_info("get_bills") +} +} \seealso{ -\code{review_session_info()} +\code{review_session_info()}. } \author{ David Liao (davidycliao@gmail.com) diff --git a/man/review_session_info.Rd b/man/review_session_info.Rd index 3a01f600..2d94300d 100644 --- a/man/review_session_info.Rd +++ b/man/review_session_info.Rd @@ -19,6 +19,11 @@ Check Session Periods in Each Year (Minguo Calendar) \code{review_session_info} produces a dataframe, displaying each session period in year formatted in Minguo (Taiwan) calendar. } +\examples{ +\dontrun{ +review_session_info(7) +} +} \seealso{ Regarding Minguo calendar, please see \url{https://en.wikipedia.org/wiki/Republic_of_China_calendar}. } diff --git a/man/transformed_date_bill.Rd b/man/transformed_date_bill.Rd index 69befeb8..9bc4af03 100644 --- a/man/transformed_date_bill.Rd +++ b/man/transformed_date_bill.Rd @@ -16,3 +16,9 @@ date in POSIXct \code{transformed_date_meeting()} transforms Minguo (Taiwan) Calendar to A.D. format in POSIXct for \code{get_bill()}, e.g. "1050531" to "2016-05-31". } +\examples{ +\dontrun{ +transformed_date_bill("1050531") +} +} +\keyword{internal} diff --git a/man/transformed_date_meeting.Rd b/man/transformed_date_meeting.Rd index 81e0a3fe..c4564841 100644 --- a/man/transformed_date_meeting.Rd +++ b/man/transformed_date_meeting.Rd @@ -22,6 +22,9 @@ and \code{get_speech_video()}, \code{check_date} transforms ROC date to a date in POSIXct, e.g. "105/05/31" to "2016-05-31". } \examples{ +\dontrun{ transformed_date_meeting("105/05/31") +} } +\keyword{internal} diff --git a/man/validate_dates_format.Rd b/man/validate_dates_format.Rd new file mode 100644 index 00000000..ef2e4563 --- /dev/null +++ b/man/validate_dates_format.Rd @@ -0,0 +1,26 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/utils.R +\name{validate_dates_format} +\alias{validate_dates_format} +\title{Validate Date Formats} +\usage{ +validate_dates_format(start_date, end_date) +} +\arguments{ +\item{start_date}{A string representing the start date. Expected format is numeric, e.g., "1090101".} + +\item{end_date}{A string representing the end date. Expected format is numeric, e.g., "1090101".} +} +\value{ +NULL. If the dates are not in the expected format, an error is thrown. +} +\description{ +This function checks if the provided start and end dates are in the correct numeric format. +} +\examples{ +# This should throw an error: +\dontrun{ +validate_dates_format("10901", "1100101") +} +} +\keyword{internal} diff --git a/man/website_availability.Rd b/man/website_availability.Rd index 2b249e93..6d9ab2d3 100644 --- a/man/website_availability.Rd +++ b/man/website_availability.Rd @@ -2,16 +2,18 @@ % Please edit documentation in R/utils.R \name{website_availability} \alias{website_availability} -\title{A Check for the Website Availability I} +\title{Check for the Website Availability I} \usage{ website_availability(site = "https://data.ly.gov.tw/index.action") } \arguments{ -\item{site}{https://data.ly.gov.tw/index.action} +\item{site}{A website URL to check. Default is "https://data.ly.gov.tw/index.action".} } \description{ -A Check for the Website Availability I +This function checks the availability of a specified website by trying to read +the first line of the site's content. } \seealso{ -\code{check_internet()}, +\code{check_internet()} } +\keyword{internal} diff --git a/man/website_availability2.Rd b/man/website_availability2.Rd index 18ae0b15..9fb65ee5 100644 --- a/man/website_availability2.Rd +++ b/man/website_availability2.Rd @@ -2,18 +2,20 @@ % Please edit documentation in R/utils.R \name{website_availability2} \alias{website_availability2} -\title{A Check for the Website Availability II} +\title{Check for the Website Availability II} \usage{ website_availability2( - site = "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0n" + site = "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0" ) } \arguments{ -\item{site}{https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0} +\item{site}{A website URL to check. Default is "https://npl.ly.gov.tw/do/www/appDate?status=0&expire=02&startYear=0".} } \description{ -A Check for the Website Availability II +This function checks the availability of a specified website by trying to read +the first line of the site's content. } \seealso{ -\code{check_internet()}, \code{website_availability()} +\code{check_internet()} and \code{website_availability()}. } +\keyword{internal} diff --git a/tests/testthat/test_bills.R b/tests/testthat/test_bills.R index 190ac24b..0bc356fb 100644 --- a/tests/testthat/test_bills.R +++ b/tests/testthat/test_bills.R @@ -6,10 +6,23 @@ test_that("get_bills", { test_that("get_bills_2", { expect_equal(get_bills_2(term = 8, session_period = 1)$retrieved_number, 1155) - expect_message(get_bills_2(c(8,10)), - "The API is unable to query multiple terms and the retrieved data might not be complete.") + expect_error(get_bills_2(c(8,10)), + "The API doesn't support querying multiple terms. Consider implementing batch processing. Please refer to the tutorial for guidance.") expect_error(get_bills_2(term = "10"), "use numeric format only.") expect_error(get_bills_2(term = "10", verbose = TRUE), "use numeric format only.") expect_error(get_bills_2(term = 30, verbose = FALSE), "The query is unavailable.") }) +test_that("Testing get_bills function", { + + # Test if the function returns a list + result <- get_bills(start_date = 1060120, end_date = 1070310, verbose = FALSE) + expect_type(result, "list") + # Test if get_bills throws the expected error for incorrect date format + expect_error(get_bills(start_date = 1070310, end_date = 1060120, verbose = FALSE), + "The start date, 2018-03-10, should not be later than the end date, 2017-01-20.") + + # Test if the function correctly handles invalid date format + expect_error(get_bills(start_date = "10601", end_date = 1070310, verbose = FALSE), + "Dates should be in numeric format. E.g., 1090101.") +}) diff --git a/tests/testthat/test_get_infos.R b/tests/testthat/test_get_infos.R index f70185a3..5864164f 100644 --- a/tests/testthat/test_get_infos.R +++ b/tests/testthat/test_get_infos.R @@ -1,27 +1,44 @@ -# test_that("get_variable_info", { -# expect_equal(get_variable_info("get_meetings")$reference_url, "https://www.ly.gov.tw/Pages/List.aspx?nodeid=154") -# expect_equal(get_variable_info("get_parlquestions")$reference_url, "https://data.ly.gov.tw/getds.action?id=6") -# expect_equal(get_variable_info("get_committee_record")$reference_url, "https://data.ly.gov.tw/getds.action?id=46") -# expect_equal(get_variable_info("get_executive_response")$reference_url, "https://data.ly.gov.tw/getds.action?id=2") -# expect_equal(get_variable_info("get_bills")$reference_url, "https://www.ly.gov.tw/Pages/List.aspx?nodeid=153") -# expect_equal(get_variable_info("get_legislators")$reference_url, "https://data.ly.gov.tw/getds.action?id=16") -# expect_equal(get_variable_info("get_bills_2")$reference_url, "https://data.ly.gov.tw/getds.action?id=20") -# expect_equal(get_variable_info("get_caucus_meetings")$reference_url, "https://data.ly.gov.tw/getds.action?id=8") -# expect_equal(get_variable_info("get_public_debates")$reference_url, "https://data.ly.gov.tw/getds.action?id=7") -# expect_equal(get_variable_info("get_speech_video")$reference_url, "https://data.ly.gov.tw/getds.action?id=148") -# }) - +# Test infos test_that("get_variable_info", { expect_error(get_variable_info("x"), - "Use correct funtion names below in character format: - get_bills: the records of the bills - get_bills_2: the records of legislators and the government proposals - get_meetings: the spoken meeting records - get_caucus_meetings: the meeting records of cross-caucus session - get_speech_video: the full video information of meetings and committees - get_public_debates: the records of national public debates - get_parlquestions: the records of parliamentary questions - get_executive_response: the records of the questions answered by the executives") + "Use correct function names below in character format: + get_bills: the records of the bills + get_bills_2: the records of legislators and the government proposals + get_meetings: the spoken meeting records + get_caucus_meetings: the meeting records of cross-caucus session + get_speech_video: the full video information of meetings and committees + get_public_debates: the records of national public debates + get_parlquestions: the records of parliamentary questions + get_executive_response: the records of the questions answered by the executives") +}) + + + +# For get_variable_info function +test_that("get_variable_info works correctly", { + result <- get_variable_info("get_bills") + + # Check if the function returns a list + expect_true(is.list(result)) + + # Check if the list contains specific elements + expect_true("page_info" %in% names(result)) + expect_true("reference_url" %in% names(result)) + + # Check if passing an invalid parameter value results in an error + expect_error(get_variable_info("invalid_function_name"), "Use correct function names below in character format.") }) -# test_that("review_session_info", {expect_equal(nrow(review_session_info(6)), 8)}) +# For review_session_info function +test_that("review_session_info works correctly", { + result <- review_session_info(7) + + # Check if the function returns a tibble + expect_true(is(result, "tbl_df")) + + # Check if the tibble contains specific column names (this depends on the actual column names) + expect_true("屆期會期" %in% colnames(result)) # Replace 'ColumnName1' with actual column name + + # Check if passing an invalid term value results in an error + expect_error(review_session_info(12), "use correct `term`.") +}) diff --git a/tests/testthat/test_legislators.R b/tests/testthat/test_legislators.R index 8ac6c6af..00444d54 100644 --- a/tests/testthat/test_legislators.R +++ b/tests/testthat/test_legislators.R @@ -4,8 +4,7 @@ test_that("get_legislators", { expect_equal(get_legislators(term = 2, verbose = FALSE)$queried_term, "2") expect_equal(get_legislators(term = 8)$queried_term, "8") expect_error(get_legislators(term = 30)$queried_term, "The query is unavailable.") - - expect_equal(get_legislators()$queried_term, "2 3 4 5 6 7 8 9 10") }) + }) test_that("get_legislators", { expect_message(get_legislators(c(6, 5)), diff --git a/tests/testthat/test_meeting.R b/tests/testthat/test_meeting.R index 7d7190c8..51f59d8f 100644 --- a/tests/testthat/test_meeting.R +++ b/tests/testthat/test_meeting.R @@ -30,12 +30,18 @@ test_that("get_public_debates", { }) +# test_that("get_committee_record", { +# expect_equal(get_committee_record(term = 8, session_period= 1, verbose = FALSE)$retrieved_number, 613) +# expect_equal(get_committee_record(term = 8, session_period= 2, verbose = FALSE)$retrieved_number, 633) +# expect_equal(get_committee_record(term = 8, session_period= 2, verbose = TRUE)$title, "the records of reviewed items in the committees") +# expect_error(get_committee_record(term = 2), "The query is unavailable.") +# # expect_message(get_committee_record(c(10,11)), +# # "The API is unable to query multiple terms and the retrieved data might not be complete.") +# }) + test_that("get_committee_record", { - expect_equal(get_committee_record(term = 8, session_period= 1, verbose = FALSE)$retrieved_number, 613) - expect_equal(get_committee_record(term = 8, session_period= 2, verbose = FALSE)$retrieved_number, 633) - expect_equal(get_committee_record(term = 8, session_period= 2, verbose = TRUE)$title, "the records of reviewed items in the committees") + expect_equal(get_committee_record(term = 10, session_period= 1, verbose = FALSE)$retrieved_number, 4844) + expect_equal(get_committee_record(term = 10, session_period= 2, verbose = TRUE)$title, "the records of reviewed items in the committees") expect_error(get_committee_record(term = 2), "The query is unavailable.") - # expect_message(get_committee_record(c(10,11)), - # "The API is unable to query multiple terms and the retrieved data might not be complete.") }) diff --git a/tests/testthat/test_parlquestions.R b/tests/testthat/test_parlquestions.R index 1e49b3cd..864b4060 100644 --- a/tests/testthat/test_parlquestions.R +++ b/tests/testthat/test_parlquestions.R @@ -1,22 +1,22 @@ test_that("get_parlquestions", { - expect_equal(get_parlquestions(term = 8, session_period = 1, verbose = FALSE)$title, "the records of parliarmentary questions") - expect_equal(get_parlquestions(term = 8, session_period = 1, verbose = TRUE)$retrieved_number, 957) + # expect_equal(get_parlquestions(term = 8, session_period = 1, verbose = FALSE)$title, "the records of parliarmentary questions") + # expect_equal(get_parlquestions(term = 8, session_period = 1, verbose = TRUE)$retrieved_number, 957) expect_error(get_parlquestions(term = "9", verbose = FALSE), "use numeric format only.") expect_equal(get_parlquestions(NULL)$url, "https://data.ly.gov.tw/odw/ID6Action.action?term=&sessionPeriod=&sessionTimes=&item=&fileType=json") - expect_message(get_parlquestions(c(8,9)), "The API is unable to query multiple terms and the retrieved data might not be complete.") + expect_error(get_parlquestions(c(8,9))) expect_error(get_parlquestions(30), "The query is unavailable.") }) test_that("get_executive_response", { - # checked Jan 23 2023 + # checked 23 Jan 2023 + # checked 16 Sep 2023 expect_equal(get_executive_response(term = 8, session_period = 1, verbose = FALSE)$retrieved_number, 1065) expect_equal(get_executive_response(term = 8, session_period = 1, verbose = TRUE)$retrieved_number, 1065) expect_error(get_executive_response(term = "9"), "use numeric format only.") - expect_message(get_executive_response(c(8,9)), - "The API is unable to query multiple terms and the retrieved data might not be complete.") + expect_error(get_executive_response(c(8,9)), + "The API is unable to query multiple terms.") expect_error(get_executive_response(30), "The query is unavailable.") }) - diff --git a/vignettes/.gitignore b/vignettes/.gitignore deleted file mode 100644 index 097b2416..00000000 --- a/vignettes/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -*.html -*.R diff --git a/vignettes/get_bills.Rmd b/vignettes/get_bills.Rmd index 9eebd8c1..b22f42bc 100644 --- a/vignettes/get_bills.Rmd +++ b/vignettes/get_bills.Rmd @@ -1,9 +1,9 @@ --- -title: "以「法律提案」為例" -author: "李宜展 東海大學政治系" +title: "The Records of the Bills" +author: "" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{以「法律提案」為例} + %\VignetteIndexEntry{The Records of the Bills} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -20,30 +20,20 @@ assign("has_internet_via_proxy", TRUE, environment(curl::has_internet)) ``` -## 法律提案（the Records of the Bills）為例 +## An Example of the Records of the Bills -讀取 `legisTaiwan` 與 `stringr` 套件 +First, we'll import legisTaiwan, and then we'll retrieve data from January 20th of the Republic of China year 106 to March 10th of the Republic of China year 111. ```{r} library(legisTaiwan) -library(stringr) ``` -用[`get_bills()`](https://davidycliao.github.io/legisTaiwan/reference/get_bills.html)抓取*周春米*在「民國106年1月20」至「民111年3月10日」所提之法案。 ```{r} -get_bills(start_date = 1060120, end_date = 1110310, proposer = "周春米", verbose = FALSE) +billdata <- get_bills(start_date = 1060120, + end_date = 1110310, verbose = FALSE) ``` -抓取*莊瑞雄*在「民國106年1月20」至「民111年3月10日」所提之法案。 +The get_bills function returns a list that contains query_time, retrieved_number, meeting_unit, start_date_ad (A.D) , end_date_ad (A.D), start_date, end_date, url, variable_names, manual_info, and data. ```{r} -get_bills(start_date = 1060120, end_date = 1110310, proposer = "莊瑞雄", verbose = FALSE) +billdata$data ``` - -看看「民國106年1月20日」與「民國107年3月10日」之間，有提到「原住民」的法案 -```{r} -bills_data <- get_bills(start_date = 1060120, end_date = 1070310, verbose = FALSE) -bills <- bills_data$data -bills[str_detect(bills$billName, "原住民", negate = FALSE), ] -``` - - diff --git a/vignettes/get_caucus_meetings.rmd b/vignettes/get_caucus_meetings.rmd index a07b5d76..b8b6f7a0 100644 --- a/vignettes/get_caucus_meetings.rmd +++ b/vignettes/get_caucus_meetings.rmd @@ -1,9 +1,8 @@ --- -title: "以「黨團協商」為例" -author: "陳逸儒 清華大學資訊系統與應用研究所博士班" +title: "An Example of Party Caucus Negotiation" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{以「黨團協商」為例} + %\VignetteIndexEntry{An Example of Party Caucus Negotiation} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -19,57 +18,22 @@ knitr::opts_chunk$set( assign("has_internet_via_proxy", TRUE, environment(curl::has_internet)) ``` -讀取 legisTaiwan 與 stringr,tidyverse 套件 -```{r} -library(legisTaiwan) -library(stringr) -library(tidyverse) -``` - -以get_caucus_meetings()「黨團協商」為例 - -格式：get_caucus_meetings(start_date = NULL, end_date = NULL, verbose = TRUE) +## An Example of the Records of the Bills -首先，須先知道該會期之期間(請參見：) - - -設定好指定時間區間後即可看到變數名稱 +First, we'll import legisTaiwan. Next, we'll retrieve data from September 23rd in the Republic of China year 111 to January 19th in the Republic of China year 112. Unlike the date parameter in get_bills(), it needs to be formatted as a Republic of China year in a string with "/". The reason is due to inconsistencies in the API's parameter design. In the next version, 0.2 and above, we aim to overcome this issue and unify the date format within the `legisTaiwan` framework. ```{r} -#第10屆第6會期 -get_caucus_meetings(start_date = "111/09/23", end_date = "112/01/19") -``` - -可建立指定區間的資料變數(info)（第10屆第6會期） - -```{r} -info10_6 <- get_caucus_meetings(start_date = "111/09/23", end_date = "112/01/19") -meetings10_6 <- info10_6$data +library(legisTaiwan) ``` -請注意： - -API提供參數「只有」：卷(comYear)、期(comVolume)、冊別(comBookId)、屆別(term)、會期(sessionPeriod)、會次(sessionTimes)、臨時會會次(meetingTimes)、會議起始日期(民國年)(meetingDateS)、會議結束日期(民國年)(meetingDateE)、檔案類型(fileType)，檔案類型可為json、xml、csv、txt、xls。 - -雖然API沒有提供，但是接著還是可以開始搜尋議案內容（subject） ```{r} -meetings10_6 %>% - count(subject) - +caucus_df <- get_caucus_meetings(start_date = "111/09/23", end_date = "112/01/19", verbose = FALSE) ``` -創建一個新的條目， 找出第十屆第六會期中包含「原住民」字眼之黨團協商議案 ```{r} -Q10_aborigines <- meetings10_6[str_detect(meetings10_6[["subject"]], "原住民", negate = FALSE),] - +caucus_df$data ``` -接著列出來 - -```{r} -Q10_aborigines %>% - count(subject) -``` diff --git a/vignettes/get_legislators.Rmd b/vignettes/get_legislators.Rmd index a2dafb5d..a93138a0 100644 --- a/vignettes/get_legislators.Rmd +++ b/vignettes/get_legislators.Rmd @@ -1,9 +1,9 @@ --- -title: "以「歷屆委員資料」為例" -author: "李宜展 東海大學政治系" +title: "Legislator's Democraphic Data" +author: "" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{以「歷屆委員資料」為例} + %\VignetteIndexEntry{Legislator's Democraphic Data} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -19,60 +19,18 @@ knitr::opts_chunk$set( assign("has_internet_via_proxy", TRUE, environment(curl::has_internet)) ``` - -## 以[`get_legislators()`](https://davidycliao.github.io/legisTaiwan/reference/get_legislators.html) 抓取「歷屆委員資料」為例 +## Using `get_legislators()` as an Example to Fetch Historical Legislator Data'. ```{r} library(legisTaiwan) -library(tidyverse) ``` ```{r} info <- get_legislators(verbose = FALSE) -legislators <- info$data -``` - -使用`tidyverse`協助做資料整理，計算「性別」之個數。 -```{r} -legislators %>% - count(sex) -``` - -計算「黨籍」之個數 -```{r} -legislators %>% - count(party) ``` -製作直方圖 ```{r} -library(ggplot2) -party <- legislators %>% - count(party) -ggplot(data = legislators, aes(x = party)) + - geom_bar() + - theme(text = element_text(family = "Heiti TC Light")) +info$data ``` -製作圓餅圖 -```{r} -party_1 <- table(legislators$party) -party.freq <- data.frame(party_1) -names(party.freq)[1] <- "party" - -ggplot(data = party.freq, aes(x = "", y = Freq, fill = party)) + - geom_bar(stat = "identity", width = 1) + - coord_polar(theta = "y", start = 0) + - theme_void()+ - theme(text = element_text(family = "Heiti TC Light")) - -``` - -查看不同性別於不同政黨中之比例 -```{r} -ggplot(data = legislators, aes(x = party, fill = sex)) + - geom_bar(position = "stack") + - # theme(text = element_text(family = "Heiti TC Light")) + - coord_flip() -``` diff --git a/vignettes/get_parlquestions.Rmd b/vignettes/get_parlquestions.Rmd index 7e3c438d..0a0a5fcc 100644 --- a/vignettes/get_parlquestions.Rmd +++ b/vignettes/get_parlquestions.Rmd @@ -1,9 +1,9 @@ --- -title: "以「立委質詢」為例" -author: "李宜展 東海大學政治系" +title: "Parliarmentary Questions" +author: "" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{以「立委質詢」為例} + %\VignetteIndexEntry{Parliarmentary Questions} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- @@ -15,40 +15,26 @@ knitr::opts_chunk$set( ) ``` + ```{r include=FALSE} assign("has_internet_via_proxy", TRUE, environment(curl::has_internet)) +library(legisTaiwan) ``` +## Using `get_parlquestions()` as an Example to Parliarmentary Questions'. -## 以[`get_parlquestions()`](https://davidycliao.github.io/legisTaiwan/reference/get_parlquestions.html)「立委質詢」為例 -找出立委在第八屆會期質詢當中，包含「中國」字眼之質詢。 ```{r} library(legisTaiwan) -library(stringr) -question_8 <- get_parlquestions(term = 8) -Q8_data <- question_8$data -Q8_China <- Q8_data[str_detect(Q8_data[["item"]], "中國", negate = FALSE), ] ``` -計算某位立法委員一共提出幾次有關「中國」字眼之質詢 -```{r} -cat("李應元", sum(stringr::str_count(Q8_China$item, pattern = "本院李委員應元")), "\n") -cat("丁守中", sum(stringr::str_count(Q8_China$item, pattern = "本院丁委員守中")), "\n") -cat("陳其邁", sum(stringr::str_count(Q8_China$item, pattern = "本院陳委員其邁")), "\n") -``` -李應元立員提出幾次有提到中國字眼之質詢 ```{r} -Q8_China_li <- Q8_China[str_detect(Q8_China[["item"]], "本院李委員應元", negate = FALSE),] -Q8_China_li[c("item")] +pa_term10 <- get_parlquestions(term = 10, verbose = TRUE) ``` -丁守中立員提出幾次有提到中國字眼之質詢 ```{r} -Q8_China_Ding <- Q8_China[str_detect(Q8_China[["item"]], "本院丁委員守中", negate = FALSE),] -Q8_China_Ding[c("item")] +pa_term10$data ``` - diff --git a/vignettes/manual.Rmd b/vignettes/manual.Rmd index 5a52ca4c..6ffff90e 100644 --- a/vignettes/manual.Rmd +++ b/vignettes/manual.Rmd @@ -14,6 +14,11 @@ knitr::opts_chunk$set( ) ``` +```{r include=FALSE} +assign("has_internet_via_proxy", TRUE, environment(curl::has_internet)) +``` + +
Parliamentary activities such as debates and written parliamentary questions, play a significant role in most parliamentary democracies. For example, the floor debate diff --git a/vignettes/research.Rmd b/vignettes/research.Rmd deleted file mode 100644 index 22876991..00000000 --- a/vignettes/research.Rmd +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: "research" -output: rmarkdown::html_vignette -vignette: > - %\VignetteIndexEntry{research} - %\VignetteEngine{knitr::rmarkdown} - %\VignetteEncoding{UTF-8} ---- - -```{r, include = FALSE} -knitr::opts_chunk$set( - collapse = TRUE, - comment = "#>" -) -``` - -