@@ -70,32 +70,54 @@ fetch_iquizoo_mem <- function(cache = NULL) {
7070
7171# ' Fetch data from iQuizoo database
7272# '
73- # ' @param query A parameterized SQL query. Note the query should also contain
74- # ' a `glue` expression to inject the table name, i.e., `"{ table_name }"`.
73+ # ' This function is a wrapper of [fetch_iquizoo()], which is used as a helper
74+ # ' function to fetch data from the iQuizoo database.
75+ # '
76+ # ' The data essentially means one of the two types of data: raw data or scores.
77+ # ' The raw data is the original data collected from the game, while the scores
78+ # ' are the scores calculated by the iQuizoo system. While scores can also be
79+ # ' calculated from the raw data, the pre-calculated scores are used to for some
80+ # ' quick analysis.
81+ # '
82+ # ' The data is separated by project date, so the table name is suffixed by the
83+ # ' project date, which is automatically fetched from the database by this
84+ # ' function. You could set the format of the date suffix by `suffix_format`,
85+ # ' although currently you should not need to change it because it probably will
86+ # ' not change in the future. Finally, this suffix should be substituted into the
87+ # ' query, which should contain an expression to inject the table name, i.e.,
88+ # ' `"{table_name}"`.
89+ # '
7590# ' @param project_id The project id to be bound to the query.
7691# ' @param game_id The game id to be bound to the query.
7792# ' @param ... Further arguments passed to [fetch_iquizoo()].
7893# ' @param what What to fetch. Can be either "raw_data" or "scores".
94+ # ' @param query A parameterized SQL query. A default query file is stored in the
95+ # ' package, which is often enough for most cases. You can also specify your
96+ # ' own query file by this argument. See details for more information.
97+ # ' @param suffix_format The format of the date suffix. See details for more
98+ # ' information.
7999# ' @return A [data.frame] contains the fetched data.
80100# ' @export
81- fetch_data <- function (query , project_id , game_id , ... ,
82- what = c(" raw_data" " scores"
101+ fetch_data <- function (project_id , game_id , ... ,
102+ what = c(" raw_data" " scores"
103+ query = NULL ,
104+ suffix_format = " %Y0101"
83105 check_dots_used()
84106 what <- match.arg(what )
85- # the database stores data from each year into a separate table with the
86- # suffix of course date with the format "<year>0101"
107+ # data separated by project date, so we need to get the project date first
87108 suffix <- package_file(" sql" " project_date.sql" | >
88109 read_file() | >
89110 fetch_iquizoo(params = project_id ) | >
90111 .subset2(" project_date" | >
91- format(" %Y0101 "
112+ format(suffix_format )
92113 table_name <- paste0(
93114 switch (what ,
94115 raw_data = " content_orginal_data_"
95116 scores = " content_ability_score_"
96117 ),
97118 suffix
98119 )
120+ query <- query %|| % read_file(package_file(" sql" what , " .sql"
99121 fetch_iquizoo(
100122 stringr :: str_glue(
101123 query ,
@@ -105,96 +127,3 @@ fetch_data <- function(query, project_id, game_id, ...,
105127 params = list (project_id , game_id )
106128 )
107129}
108-
109- # ' Set data source
110- # '
111- # ' @param driver The driver used. Set as an option of `"tarflow.driver"`.
112- # ' Options are [odbc::odbc()] and [RMariaDB::MariaDB()], both of which need
113- # ' pre-configurations. Default to first available one.
114- # ' @param dsn The data source name of an **ODBC** database connector. See
115- # ' [odbc::dbConnect()] for more information. Used when `driver` is set as
116- # ' [odbc::odbc()].
117- # ' @param groups Section identifier in the `default.file`. See
118- # ' [RMariaDB::MariaDB()] for more information. Used when `driver` is set as
119- # ' [RMariaDB::MariaDB()].
120- # ' @return An S3 class of `tarflow.source` with the options.
121- # ' @export
122- setup_source <- function (driver = getOption(" tarflow.driver"
123- dsn = getOption(" tarflow.dsn"
124- groups = getOption(" tarflow.groups"
125- structure(
126- list (
127- driver = driver ,
128- dsn = dsn ,
129- groups = groups
130- ),
131- class = " tarflow.source"
132- )
133- }
134-
135- # ' Check if the database based on the given data source is ready
136- # '
137- # ' @param source The data source from which data is fetched. See
138- # ' [setup_source()] for details.
139- # ' @return TRUE if the database is ready, FALSE otherwise.
140- # ' @export
141- check_source <- function (source = setup_source()) {
142- if (! inherits(source , " tarflow.source"
143- cli :: cli_abort(
144- " {.arg source} must be created by {.fun setup_source}."
145- class = " tarflow_bad_source"
146- )
147- }
148- # nocov start
149- if (inherits(source $ driver , " OdbcDriver"
150- return (DBI :: dbCanConnect(source $ driver , dsn = source $ dsn ))
151- }
152- # nocov end
153- if (inherits(source $ driver , " MariaDBDriver"
154- return (DBI :: dbCanConnect(source $ driver , groups = source $ groups ))
155- }
156- return (FALSE )
157- }
158-
159- # nocov start
160-
161- # ' Setup MySQL database connection option file
162- # '
163- # ' This function will create a MySQL option file at the given path. To ensure it
164- # ' works, set these environment variables before calling this function:
165- # ' - `MYSQL_HOST`: The host name of the MySQL server.
166- # ' - `MYSQL_USER`: The user name of the MySQL server.
167- # ' - `MYSQL_PASSWORD`: The password of the MySQL server.
168- # '
169- # ' @param path The path to the option file. Default location is operating system
170- # ' dependent. On Windows, it is `C:/my.cnf`. On other systems, it is
171- # ' `~/.my.cnf`.
172- # ' @param overwrite Whether to overwrite the existing option file.
173- # ' @param quietly A logical indicates whether message should be suppressed.
174- # ' @return NULL (invisible).
175- # ' @export
176- setup_option_file <- function (path = NULL , overwrite = FALSE , quietly = FALSE ) {
177- my_cnf_tmpl <- read_file(package_file(" database" " my.cnf.tmpl"
178- path <- path %|| % default_file()
179- if (file.exists(path ) && ! overwrite ) {
180- if (! quietly ) {
181- cli :: cli_alert_warning(
182- " Option file already exists. Use {.arg overwrite = TRUE} to overwrite."
183- class = " tarflow_option_file_exists"
184- )
185- }
186- return (invisible ())
187- }
188- writeLines(stringr :: str_glue(my_cnf_tmpl ), path )
189- }
190-
191- # helper functions
192- default_file <- function () {
193- if (Sys.info()[" sysname" == " Windows"
194- return (" C:/my.cnf"
195- } else {
196- return (" ~/.my.cnf"
197- }
198- }
199-
200- # nocov end
0 commit comments