UPDATE v0.1.6

davidycliao · Sep 16, 2023 · 46ef259 · 46ef259
1 parent f819862
commit 46ef259
Show file tree

Hide file tree

Showing 14 changed files with 58 additions and 169 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(check_internet)
 export(get_bills)
 export(get_bills_2)
 export(get_caucus_meetings)

diff --git a/R/legislators.R b/R/legislators.R
@@ -45,15 +45,15 @@
 #'`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屆。
 #'
 #'@seealso
 #'`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 = "")

diff --git a/R/parlquestions.R b/R/parlquestions.R
@@ -21,7 +21,7 @@
 #'     \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{`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`}{屆別}
@@ -52,13 +52,13 @@
 #' `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")`
+#' 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")`
 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,
@@ -158,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會期起)。
 #'
@@ -171,7 +171,7 @@ 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=",

diff --git a/R/utils.R b/R/utils.R
@@ -74,11 +74,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
@@ -106,22 +105,16 @@ 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 current system time.")
-
   attempt::stop_if_all(end_date > as.Date(Sys.time()),
                        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 = ""))
@@ -143,7 +136,7 @@ api_check <- function(start_date = start_date, end_date = end_date) {
 #'
 #'@importFrom stringr str_split_1
 #'
-#' @keywords internal
+#'@keywords internal
 #'
 #'@examples
 #'transformed_date_meeting("105/05/31")

diff --git a/README.Rmd b/README.Rmd
@@ -26,7 +26,7 @@ knitr::opts_chunk$set(
 
 <div style="text-align: justify">
 
-`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.
 
 </div>
 
@@ -48,6 +48,7 @@ library(legisTaiwan)
 ## Caution:
 <div style="text-align: justify">
 
-`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.
 
 </div>
diff --git 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.
 
 </div>
 
@@ -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:
 
 <div style="text-align: justify">
 
-`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.
 
 </div>
diff --git a/man/check_internet.Rd b/man/check_internet.Rd
diff --git a/man/get_executive_response.Rd b/man/get_executive_response.Rd
diff --git a/man/get_legislators.Rd b/man/get_legislators.Rd
diff --git a/man/get_parlquestions.Rd b/man/get_parlquestions.Rd
diff --git a/vignettes/get_bills.Rmd b/vignettes/get_bills.Rmd
@@ -1,9 +1,9 @@
 ---
-title: "以「法律提案」為例"
-author: "李宜展 東海大學政治系"
+title: "An Example of the Records of the Bills"
+author: ""
 output: rmarkdown::html_vignette
 vignette: >
-  %\VignetteIndexEntry{以「法律提案」為例}
+  %\VignetteIndexEntry{An Example of 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
@@ -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
 
-首先，須先知道該會期之期間(請參見：<https://npl.ly.gov.tw/do/www/appDate?blockId=2&titleName=%E5%B1%86%E6%9C%83%E6%9C%9F%E5%B0%8D%E7%85%A7%E8%A1%A8>)
-
-
-設定好指定時間區間後即可看到變數名稱
+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) 
-```