Merge pull request #5 from davidycliao/v0.1.2

V0.1.2
davidycliao · Feb 2, 2023 · 35e747c · 35e747c
2 parents 111061e + 785d69a
commit 35e747c
Show file tree

Hide file tree

Showing 37 changed files with 1,019 additions and 370 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,9 +1,11 @@
 Package: legisTaiwan
 Type: Package
-Title: the Real-time and Archives of Taiwan Legislative Data in R
+Title: The Real-time and Archives of Taiwan Legislative Data in R
 Version: 0.1.1
 Authors@R: c(person("David Yen-Chieh", "Liao", email = "davidycliao@gmail.com", role = c("aut", "cre")),
-             person("Li", "Tang", email = "l.tang@mdx.ac.uk", role = "ctb"))
+             person("Li", "Tang", email = "l.tang@mdx.ac.uk", role = c("ctb", "aut")),
+             person("Taiwan Legislative Yuan", role = "cph"),
+             person("Taiwan National Science and Technology Council", role = "ctb"))
 Description: This is designed to make it quick and easy to download the 
             real-time and archives of Taiwan legislative data via 
             Taiwan Legislative Yuan API.

diff --git a/NAMESPACE b/NAMESPACE
@@ -13,7 +13,7 @@ export(get_meetings)
 export(get_parlquestions)
 export(get_public_debates)
 export(get_speech_video)
-export(get_variabel_infos)
+export(get_variable_info)
 export(transformed_date_bill)
 export(transformed_date_meeting)
 importFrom(attempt,stop_if_all)

diff --git a/NEWS.md b/NEWS.md
@@ -1 +1,19 @@
-## CHANGES IN `legisTaiwan` VERSION 1.0.1
+# `legisTaiwan` VERSION 0.1.2 (development version)
+
+* Fix typo in function name: `get_variabel_infos()` to `get_variable_info()`.
+
+* Add contributors and author in NAMESPACE: `國科會` and `立法院`
+
+* Re-documentation and inserting handlers
+
+# `legisTaiwan` VERSION 0.1.1
+
+* `get_executive_response()`, `get_bills_2()`, `get_debates()` and `get_speech_video()` are added.
+
+* lack of documentation 
+
+
+# `legisTaiwan` VERSION 0.1.0
+
+The package is created and had `get_meetings()`, `get_bills()`, `get_legislators()`, `get_parlquestions()`
+
diff --git a/R/bill.R b/R/bill.R
@@ -1,48 +1,69 @@
-#' Retrieving the records of the bills 法律提案(API)
-#'
-#'@param start_date Requesting meeting records starting from the date. A double
-#'represents a date in ROC Taiwan format. If a double is used, it should specify
-#' as Taiwan calendar format, e.g. 1090110.
-#'@param end_date Requesting meeting records ending from the date. A double
-#'represents a date in ROC Taiwan format.If a double is used, it should specify
-#'as Taiwan calendar format, e.g. 1090110.
-#'@param proposer The default value is NULL, which means all bill records are
-#'included between the starting date and the ending date.
-#'@param verbose The default value is TRUE, displaying the description of data
-#'retrieved in number, url and computing time.
-#'@return A tibble contains date, term, name, sessionPeriod, sessionTimes,
-#'billName, billProposer, billCosignatory, billStatus, date_ad
+#' Retrieving the records of the bills 法律提案 (API)
+#'
+#'@details `get_meetings` 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`.
+#'
+#'@param start_date numeric Must be formatted in ROC Taiwan calendar, e.g. 1090101.
+#'
+#'@param end_date numeric Must be formatted in ROC 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: s\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 offical manual}
+#'      \item{`data`}{a tibble dataframe, whose variables include:
+#'      `term`,
+#'      `sessionPeriod`,
+#'      `sessionTimes`,
+#'      `meetingTimes`,
+#'      `billName`,
+#'      `billProposer`,
+#'      `billCosignatory`,
+#'      `billStatus`, and
+#'      `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)
-#'
-#'
+#'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 = "孔文吉&鄭天財")
 #'@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) {
+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))
-  set_api_url <- paste("https://www.ly.gov.tw/WebAPI/LegislativeBill.aspx?from=", start_date, "&to=", end_date, "&proposer=", proposer, "&mode=json", sep = "")
+  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)
@@ -75,19 +96,18 @@ get_bills <- function(start_date = NULL, end_date = NULL,
   )
 }
 
-
-
-
-#' Retrieving the records of legislators and the government proposals 議案提案
+#' Retrieving the records of legislators and the government (executives) proposals
+#' 提供委員及政府之議案提案資訊。(自第8屆第1會期起)
 #'
+#'@param term numeric or NULL The default value is 8
+#'參數必須為數值，資料從自第8屆第1會期起。
+#'
+#'@param session_period numeric or NULL. Available options for the session periods
+#'is: 1, 2, 3, 4, 5, 6, 7, and 8. The default is 8 參數必須為數值。
 #'
-#'@param term Requesting answered questions by term. The parameter should be set in
-#'a numeric format. The default value is 8. The data is only available from 8th
-#'term 參數必須為數值，資料從立法院第8屆開始計算。
-#'@param session_period session in the term. The session is between 1 and 8.
-#' session_period 參數必須為數值。
 #'@param verbose The default value is TRUE, displaying the description of data
 #'retrieved in number, url and computing time.
+#'
 #'@return A list object contains a tibble carrying the variables of term, sessionPeriod,
 #' sessionTimes, meetingTimes, eyNumber, lyNumber, subject, content, docUrl
 #' selectTerm.
@@ -97,22 +117,35 @@ get_bills <- function(start_date = NULL, end_date = NULL,
 #'@importFrom jsonlite fromJSON
 #'
 #'@export
+#'
 #'@examples
 #' ## query the Executives' answered response by term and the session period.
 #' ## 輸入「立委屆期」與「會期」下載「質詢事項 (行政院答復部分)」
 #'get_bills_2(term = 8, session_period = 1)
 #'
-#'get_bills_2(term = 8, session_period = 4)
-#'
 #'@seealso
 #'\url{https://data.ly.gov.tw/getds.action?id=1}
 
-get_bills_2 <- function(term = NULL, session_period = NULL, verbose = TRUE) {
+get_bills_2 <- function(term = 8, session_period = NULL, verbose = TRUE) {
   legisTaiwan::check_internet()
-  attempt::stop_if_all(term, is.character, msg = "use numeric format only")
-  attempt::stop_if_all(term, is.character, msg = "use numeric format only")
+  if (is.null(term)) {
+
+    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")
+  } else if (length(term) == 1) {
+    attempt::stop_if_all(term, is.character, msg = "use numeric format only.")
+    term <- sprintf("%02d", as.numeric(term))
+  } else if (length(term)  > 1) {
+    attempt::stop_if_all(term, is.character, msg = "use numeric format only.")
+    message("The API is unable to query multiple terms and the request mostly falls.")
+    term <- paste(sprintf("%02d", as.numeric(term)), collapse = "&")
+  }
   set_api_url <- paste("https://data.ly.gov.tw/odw/ID20Action.action?term=",
-                       sprintf("%02d", as.numeric(term)), "&sessionPeriod=", sprintf("%02d", as.numeric(session_period)),
+                       term, "&sessionPeriod=",
+                       sprintf("%02d", as.numeric(session_period)),
                        "&sessionTimes=&meetingTimes=&billName=&billOrg=&billProposer=&billCosignatory=&fileType=json", sep = "")
   tryCatch(
     {

diff --git a/R/info.R b/R/info.R
@@ -1,8 +1,21 @@
-#' Check all function information
+#' Check each function's manuals
 #'
-#'@param param_ characters. The parameter should be `get_parlquestions`,
-#'`get_legislators`, `get_executive_response`, `get_bills`, `get_meetings`,
-#'`get_caucus_meetings` or `get_public_debates`,
+#'@param param_ characters. Must be one of options below: \describe{
+#'      \item{get_bills}{get_bills: the records of the bills, see \url{https://data.ly.gov.tw/getds.action?id=6}}
+#'      \item{get_bills_2}{the records of legislators and the government proposals, see \url{https://data.ly.gov.tw/getds.action?id=6}}
+#'      \item{get_meetings}{the spoken meeting records, see \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}}
+#'      \item{get_caucus_meetings}{the meeting records of cross-caucus session, see \url{https://data.ly.gov.tw/getds.action?id=8}}
+#'      \item{get_speech_video}{the full video information of meetings and committees, see \url{https://data.ly.gov.tw/getds.action?id=148}}
+#'      \item{get_public_debates}{the records of national public debates, see \url{https://data.ly.gov.tw/getds.action?id=7}}
+#'      \item{get_parlquestions}{the records of parliamentary questions, see \url{https://data.ly.gov.tw/getds.action?id=6}}
+#'      \item{get_executive_response}{the records of the questions answered by the executives, see \url{https://data.ly.gov.tw/getds.action?id=2}}
+#'}
+#'
+#'@return list \describe{
+#'      \item{`page_info`}{information of the end point}
+#'      \item{`reference_url`}{the url of the page}}
+#'
+#'@details `get_variable_info` produces a list, which contains `page_info` and `reference_url`.
 #'
 #'@importFrom attempt stop_if_all
 #'@importFrom jsonlite fromJSON
@@ -11,22 +24,12 @@
 #'@importFrom stringi stri_escape_unicode
 #'
 #'@export
-#'@seealso
-#'stringi::stri_escape_unicode("質詢事項(本院委員質詢部分)")  \url{https://data.ly.gov.tw/getds.action?id=6}
-#'stringi::stri_escape_unicode("歷屆委員資料") \url{https://data.ly.gov.tw/getds.action?id=16}
-#'stringi::stri_escape_unicode("行政院答復") \url{https://data.ly.gov.tw/getds.action?id=2}
-#'stringi::stri_escape_unicode("黨團協商")  \url{https://data.ly.gov.tw/getds.action?id=8}
-#'stringi::stri_escape_unicode("委員發言片段相關影片資訊")  \url{https://data.ly.gov.tw/getds.action?id=148}
-#'stringi::stri_escape_unicode("質詢事項 (行政院答復部分) ") \url{https://data.ly.gov.tw/getds.action?id=1}
-#'stringi::stri_escape_unicode("國是論壇") 國是論壇 \url{https://data.ly.gov.tw/getds.action?id=7}
-#'stringi::stri_escape_unicode("委員發言(API)") \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=154}
-#'stringi::stri_escape_unicode("法律提案(API)") \url{https://www.ly.gov.tw/Pages/List.aspx?nodeid=153}
 
-get_variabel_infos <- function(param_) {
+get_variable_info <- function(param_) {
   legisTaiwan::check_internet()
-  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 variable")
+  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"
   }
@@ -43,7 +46,7 @@ get_variabel_infos <- function(param_) {
     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=1"
+    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"
@@ -68,7 +71,7 @@ get_variabel_infos <- function(param_) {
          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_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']")

diff --git a/R/legislators.R b/R/legislators.R
@@ -1,16 +1,26 @@
-#' Retrieving legislator' demographic information and background
+#' Retrieving legislator' demographic information and background 提供委員基本資料
 #'
-#'@param term A number, which requests answered questions from the term. The parameter should be set in
-#'a numeric vector.
-#'retrieved in number, url, and computing time.
-#'@param verbose The default is TRUE, which return the information of the return.
-#'object.
-#'@return A list contains query_time, queried_term, url ,variable_names, manual_info and data
+#'@param term numeric or null. The data is available from the 2nd term. 自第2屆起
+#'
+#'@param verbose logical, indicates whether get_meetings should print out
+#'detailed output when retrieving the data. The default is TRUE.
+#'
+#'@return list contains: \describe{
+#'\item{`query_time`}{the queried time}
+#'\item{`queried_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}
+#'\item{`data`}{a tibble dataframe}
+#'}
 #'
 #'
 #'@importFrom attempt stop_if_all
 #'@importFrom jsonlite fromJSON
 #'
+#'@details `get_legislators` produces a list, which contains  `query_time`,
+#'`queried_term`, `url`, `variable_names`, `manual_info` and `data`.
+#'
 #'@export
 #'
 #'@examples
@@ -28,9 +38,9 @@
 get_legislators <- function(term = NULL, verbose = TRUE) {
   legisTaiwan::check_internet()
   if (is.null(term)) {
-    # request full data
     set_api_url <- paste("https://data.ly.gov.tw/odw/ID16Action.action?name=&sex=&party=&partyGroup=&areaName=&term=",
                          term, "=&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) {
@@ -46,7 +56,7 @@ get_legislators <- function(term = NULL, verbose = TRUE) {
     {
       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")
+      attempt::stop_if_all(nrow(df) == 0, isTRUE, msg = "The query is unavailable.")
       term <- paste(sort(as.numeric(unique(df$term))), collapse = " ", sep = ",")
       if (isTRUE(verbose)) {
         cat(" Retrieved URL: \n", set_api_url, "\n")