Merge pull request #169 from cjbarrie/barrie-branch

Documentation updates

R/bind_tweets.R

@@ -1,6 +1,10 @@
 #' Bind information stored as JSON files
 #'
-#' This function binds information stored as JSON files. By default, it binds into a data frame containing tweets (from data_*id*.json files). If users is TRUE, it binds into a data frame containing user information (from users_*id*.json). 
+#' This function binds information stored as JSON files. 
+#' 
+#' By default, it binds into a data frame containing tweets (from data_*id*.json files). 
+#' 
+#' If users is TRUE, it binds into a data frame containing user information (from users_*id*.json). 
 #'
 #' @param data_path string, file path to directory of stored tweets data saved as data_*id*.json and users_*id*.json
 #' @param user If `FALSE`, this function binds JSON files into a data frame containing tweets; data frame containing user information otherwise. Ignore if `output_format` is not NA
@@ -18,8 +22,10 @@
 #' \dontrun{
 #' # bind json files in the directory "data" into a data frame containing tweets
 #' bind_tweets(data_path = "data/")
+#' 
 #' # bind json files in the directory "data" into a data frame containing user information
 #' bind_tweets(data_path = "data/", user = TRUE)
+#' 
 #' # bind json files in the directory "data" into a "tidy" data frame / tibble
 #' bind_tweets(data_path = "data/", user = TRUE, output_format = "tidy")
 #' }

R/build_queryv2.R

@@ -1,6 +1,8 @@
 #' Build tweet query
 #'
-#' Build tweet query according to targeted parameters. This function is already called within the main
+#' Build tweet query according to targeted parameters. 
+#' 
+#' This function is already called within the main
 #' \code{\link{get_all_tweets}} function. 
 #' 
 #' It may also be called separately and the output saved as
@@ -9,7 +11,7 @@
 #' @param query string or character vector, search query or queries
 #' @param users string or character vector, user handles to collect tweets from the specified users
 #' @param reply_to string or character vector, user handles to collect replies to the specified users
-#' @param retweets_of string or character vector, user handles to collects retweets of tweets the specified users
+#' @param retweets_of string or character vector, user handles to collects retweets of tweets by the specified users
 #' @param exclude string or character vector, tweets containing the keyword(s) will be excluded
 #' 
 #' @param is_retweet If `TRUE`, only retweets will be returned; if `FALSE`, retweets will be excluded; if `NULL`, both retweets and other tweet types will be returned.
@@ -41,9 +43,18 @@
 #'
 #' @examples
 #' \dontrun{
-#' query <- build_query("happy", is_retweet = FALSE,
-#'                      place = "new york",
-#'                      country = "US")
+#' query <- build_query(query = "happy", is_retweet = FALSE,
+#'                      country = "US",
+#'                      place = "seattle",
+#'                      point_radius = c(-122.33795253639994, 47.60900846404393, 25),
+#'                      lang = "en")
+#'                      
+#' query <- build_query(query = "twitter",
+#'                      point_radius = c(-122.33795253639994, 47.60900846404393, 25),
+#'                      lang = "en")
+#'                      
+#' query <- build_query("الحراك", is_retweet = FALSE,
+#'                      country = "DZ")
 #' }
 #'
 #' @importFrom utils menu

R/count_all_tweets.R

@@ -1,18 +1,18 @@
 #' Count tweets from full archive search
 #'
-#' This function count tweets by query string or strings
-#' between specified date ranges.
+#' This function returns aggregate counts of tweets by query string or strings
+#' between specified date ranges. 
 #'
 #' @param query string or character vector, search query or queries
 #' @param start_tweets string, starting date
 #' @param end_tweets  string, ending date
 #' @param bearer_token string, bearer token
-#' @param n integer, upper limit of tweets to be fetched
+#' @param n integer, upper limit of tweet counts to be fetched (i.e., for 365 days n must be at least 365). Default is 100. 
 #' @param file string, name of the resulting RDS file
 #' @param data_path string, if supplied, fetched data can be saved to the designated path as jsons
 #' @param export_query If `TRUE`, queries are exported to data_path
 #' @param bind_tweets If `TRUE`, tweets captured are bound into a data.frame for assignment
-#' @param granularity string, the granularity for the search counts results.
+#' @param granularity string, the granularity for the search counts results. Options are "day"; "hour"; "minute". Default is day. 
 #' @param verbose If `FALSE`, query progress messages are suppressed
 #' @param ... arguments will be passed to `build_query()` function. See `?build_query()` for further information.
 #' 
@@ -21,12 +21,18 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 #' 
-#' get_count(query = "BLM", 
-#'           start_tweets = "2020-01-01T00:00:00Z", 
+#' count_all_tweets(query = "Hogmanay", 
+#'           start_tweets = "2019-12-2700:00:00Z", 
 #'           end_tweets = "2020-01-05T00:00:00Z", 
 #'           bearer_token = get_bearer())
+#'           
+#' count_all_tweets(query = "Hogmanay", 
+#'           start_tweets = "2019-12-27T00:00:00Z", 
+#'           end_tweets = "2020-01-05T00:00:00Z", 
+#'           bearer_token = get_bearer(),
+#'           granularity = "hour",
+#'           n = 500)
 #' }
 count_all_tweets <-
   function(query = NULL,

R/get_bearer.R

@@ -1,9 +1,13 @@
-#' Manage your bearer token
+#' Manage bearer token
 #'
 #' This function attempts to retrieve your bearer token from the environmental variable "TWITTER_BEARER". 
 #' The easiest way to setup this environmental variable is to use \code{set_bearer()} 
 #' and insert your bearer token to \code{.Renviron} file following the format: TWITTER_BEARER=YOURTOKENHERE. 
 #' Replace YOURTOKENHERE with your own token.
+#' 
+#' Note: for \code{get_bearer()} to retrieve your bearer token you will need to restart the 
+#' R session after storing in \code{.Renviron}.
+#' 
 #' @return string represents your bearer token, if it the environmental variable "TWITTER_BEARER" has been preset.
 #' @export
 get_bearer <- function() {

R/get_liked_tweets.R

@@ -1,6 +1,6 @@
 #' Get liked tweets
 #' 
-#' This function fetches a list of tweets liked by a user or users.
+#' This function fetches returns tweets liked by a user or users.
 #'
 #' @param x string containing one user id or a vector of user ids
 #' @param bearer_token string, bearer token
@@ -11,9 +11,8 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-#' users <- "2244994945"
-#' get_liked_tweets(users, bearer_token)
+#' users <- c("2244994945", "95226101")
+#' get_liked_tweets(users, bearer_token = get_bearer())
 #' }
 get_liked_tweets <- function(x, bearer_token = get_bearer(), ...){
   get_user_edges(x, bearer_token, wt = "liked_tweets", ...)

R/get_liking_users.R

@@ -1,6 +1,6 @@
 #' Get liking users
 #' 
-#' This function fetches a list of users who liked a tweet or tweets.
+#' This function fetches users who liked a tweet or tweets.
 #'
 #' @param x string containing one tweet id or a vector of tweet ids
 #' @param bearer_token string, bearer token
@@ -11,9 +11,8 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 #' tweet <- "1387744422729748486"
-#' get_liking_users(tweet, bearer_token)
+#' get_liking_users(tweet, bearer_token = get_bearer())
 #' }
 get_liking_users <- function(x, bearer_token = get_bearer(), verbose = TRUE){
   bearer_token <- check_bearer(bearer_token)

R/get_user_edges.R

@@ -1,6 +1,6 @@
 #' Get user followers
 #' 
-#' This function fetches a list of users who are followers of the specified user ID.
+#' This function fetches users who are followers of the specified user ID.
 #'
 #' @param x string containing one user id or a vector of user ids
 #' @param bearer_token string, bearer token
@@ -13,7 +13,7 @@
 #' \dontrun{
 #' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 #' users <- "2244994945"
-#' get_user_followers(users, bearer_token)
+#' get_user_followers(users, bearer_token = get_bearer())
 #' }
 get_user_followers <- function(x, bearer_token = get_bearer(), ...){
   get_user_edges(x = x, bearer_token = bearer_token, wt = "followers", ...)

R/get_user_timeline.R

@@ -1,6 +1,8 @@
-#' Get tweets composed by a single user
+#' Get tweets by a single user
 #'
-#' This function collects tweets by an user ID. The most recent 3,200 Tweets can be retrieved.
+#' This function collects tweets by an user ID from the users endpoint. 
+#' 
+#' Only the most recent 3,200 Tweets can be retrieved.
 #' 
 #' If a filename is supplied, the function will 
 #' save the result as a RDS file.
@@ -29,12 +31,11 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
 #' 
 #' get_user_timeline("2244994945",
 #'                   start_tweets = "2020-01-01T00:00:00Z", 
 #'                   end_tweets = "2021-05-14T00:00:00Z",
-#'                   bearer_token = bearer_token,
+#'                   bearer_token = get_bearer(),
 #'                   n = 200)
 #' }
 get_user_timeline <-

R/resume_collection.R

@@ -1,6 +1,7 @@
 #' Resume previous collection
 #'
 #' This function resumes a previous interrupted collection session.
+#' 
 #' For this function to work, export_query must be set to "TRUE" during the original collection.
 #' 
 #' @inheritParams update_collection
@@ -10,8 +11,7 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-#' resume_collection(data_path = "data", bearer_token)
+#' resume_collection(data_path = "data", bearer_token = get_bearer())
 #' }
 
 resume_collection <- function(data_path, bearer_token = get_bearer(), verbose = TRUE, ...){

R/set_bearer.R

@@ -1,11 +1,16 @@
 #' Set bearer token
 #' 
 #' This function lets the user add their bearer token to the \code{.Renviron} file. 
+#' 
 #' It is in general not safe to 1) hard code your bearer token in your R script or 
-#' 2) have your bearer token in your command history. \code{set_bearer} opens the .Renviron file
+#' 2) have your bearer token in your command history. 
+#' 
+#' \code{set_bearer} opens the .Renviron file
 #' for the user and provides instructions on how to add the bearer token, which requires the
 #' addition of just one line in the \code{.Renviron} file, following the format TWITTER_BEARER=YOURTOKENHERE. 
+#' 
 #' Replace YOURTOKENHERE with your own token.
+#' 
 #' @importFrom usethis edit_r_environ ui_info ui_line ui_silence
 #' @export
 set_bearer <- function() {

R/update_collection.R

@@ -1,6 +1,6 @@
 #' Update previous collection session
 #'
-#' This function continues previous collection session with a new end date. 
+#' This function continues a previous collection session with a new end date. 
 #' For this function to work, export_query must be set to "TRUE" during the original collection.
 #'
 #' @param data_path string, name of an existing data_path
@@ -11,8 +11,7 @@
 #'
 #' @examples
 #' \dontrun{
-#' bearer_token <- "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
-#' update_collection(data_path = "data", "2020-01-03T00:00:00Z", bearer_token)
+#' update_collection(data_path = "data", "2020-01-03T00:00:00Z", bearer_token = get_bearer())
 #' }
 
 update_collection <- function(data_path, end_tweets, bearer_token = get_bearer(), verbose = TRUE, ...){