Merge pull request #24 from pepijn-devries/work-in-progress

Work in progress

Author: pepijn-devries

.gitignore

@@ -0,0 +1,4 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: ECOTOXr
 Type: Package
 Title: Download and Extract Data from US EPA's ECOTOX Database
-Version: 1.0.2
-Date: 2023-06-18
+Version: 1.0.3
+Date: 2023-08-21
 Authors@R: c(person("Pepijn", "de Vries", role = c("aut", "cre", "dtc"),
     email = "[email protected]",
     comment = c(ORCID = "0000-0002-7961-6646")))
@@ -41,11 +41,11 @@ Suggests:
     standartox,
     testthat (>= 3.0.0),
     webchem
-URL: <https://github.com/pepijn-devries/ECOTOXr>
+URL: https://github.com/pepijn-devries/ECOTOXr
 BugReports: https://github.com/pepijn-devries/ECOTOXr/issues
 License: GPL (>= 3)
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.1.2
+RoxygenNote: 7.2.3
 Config/testthat/edition: 3
 Roxygen: list(markdown = TRUE)

ECOTOXr.Rproj

@@ -0,0 +1,18 @@
+Version: 1.0
+
+RestoreWorkspace: Default
+SaveWorkspace: Default
+AlwaysSaveHistory: Default
+
+EnableCodeIndexing: Yes
+UseSpacesForTab: Yes
+NumSpacesForTab: 2
+Encoding: UTF-8
+
+RnwWeave: Sweave
+LaTeX: pdfLaTeX
+
+BuildType: Package
+PackageUseDevtools: Yes
+PackageInstallArgs: --no-multiarch --with-keep.source
+PackageRoxygenize: rd,collate,namespace

R/ECOTOXr.r R/ECOTOXr-package.rR/ECOTOXr.r renamed to R/ECOTOXr-package.r

@@ -1,74 +1,73 @@
-#' Package description
-#'
-#' Everything you need to know when you start using the ECOTOXr package. \if{html}{\figure{logo.png}}
-#'
-#' The ECOTOXr provides the means to efficiently search, extract and analyse [US EPA](https://www.epa.gov/)
-#' [ECOTOX](https://cfpub.epa.gov/ecotox/) data, with a focus on reproducible results. Although the package
-#' creator/maintainer is confident in the quality of this software, it is the end users sole responsibility to
-#' assure the quality of his or her work while using this software. As per the provided license terms the package
-#' maintainer is not liable for any damage resulting from its usage. That being said, below we present some tips
-#' for generating reproducible results with this package.
-#'
-#' @section How do I get started?:
-#' Installing this package is only the first step to get things started. You need to perform the following steps
-#' in order to use the package to its full capacity.
-#'
-#' * First download a copy of the complete EPA database. This can be done by calling [download_ecotox_data()].
-#'   This may not always work on all machines as R does not always accept the website SSL certificate from the EPA.
-#'   In those cases the zipped archive with the database files can be downloaded manually with a different (more
-#'   forgiving) browser. The files from the zip archive can be extracted to a location of choice. Alternatively,
-#'   the user could try to use `[download_ecotox_data](ssl_verifypeer = 0L)` when the download URL is trusted.
-#' * Next, an SQLite database needs to be build from the downloaded files. This will be done automatically when
-#'   you used [download_ecotox_data()] in the previous step. When you have manually downloaded the files
-#'   you can call [build_ecotox_sqlite()] to build the database locally.
-#' * When the previous steps have been performed successfully, you can now search the database by calling
-#'   [search_ecotox()]. You can also use [dbConnectEcotox()] to open a connection to the
-#'   database. You can query the database using this connection and any of the methods provided from the
-#'   [DBI][DBI::DBI] or [RSQLite][RSQLite::RSQLite] packages.
-#'
-#' @section How do I obtain reproducible results?:
-#' Each individual user is responsible for evaluating the reproducibility of his or her work. Although
-#' this package offers instruments to achieve reproducibility, it is not guaranteed. In order to increase the
-#' chances of generating reproducible results, one should adhere at least to the following rules:
-#' * Always use an official release from CRAN, and cite the version used in your analyses (`citation("ECOTOXr")`).
-#'   Different versions, may produce different end results (although we will strive for backward compatibility).
-#' * Make sure you are working with a clean (unaltered) version of the database. When in doubt, download and build
-#'   a fresh copy of the database ([download_ecotox_data()]). Also cite the (release) version of the downloaded
-#'   database ([cite_ecotox()]), and the system operating system in which the local database was build
-#'   [get_ecotox_info()]). Or, just make sure that you never modify the database (e.g., write data to it, delete
-#'   data from it, etc.)
-#' * In order to avoid platform dependencies it is advised to only include non-accented alpha-numerical characters in
-#'   search terms. See also [search_ecotox] and [build_ecotox_sqlite].
-#' * When trying to reproduce database extractions from earlier database releases, filter out additions after
-#'   that specific release. This can be done by adding output fields 'tests.modified_date', 'tests.created_date' and
-#'   'tests.published_date' to your search and compare those with the release date of the database you are trying to
-#'   reproduce results from.
-#'
-#' @section Why isn't the database included in the package?:
-#' This package doesn't come bundled with a copy of the database which needs to be downloaded the first time the
-#' package is used. Why is this? There are several reasons:
-#' * The database is maintained and updated by the [US EPA](https://www.epa.gov/). This process is and should be
-#'   outside the sphere of influence of the package maintainer.
-#' * Packages on CRAN are not allowed to contain large amounts of data. Publication on CRAN is key to control
-#'   the quality of this package and therefore outweighs the convenience of having the data bundled with the package.
-#' * The user has full control over the release version of the database that is being used.
-#'
-#' @section Why does this package promotes using a local copy of the ECOTOX database?:
-#' Although this package offers experimental features for searching on-line, there are several reasons why we
-#' opted for creating a local copy:
-#' * The user would be restricted to the search options provided on the website ([ECOTOX](https://cfpub.epa.gov/ecotox/)).
-#' * The on-line database doesn't come with an API that would allow for convenient interface. This is why
-#'   features implemented in this package are experimental.
-#' * The user is not limited by an internet connection and its bandwidth.
-#' * Not all database fields, and only a limited number of records, can be retrieved from the on-line interface.
-#' @docType package
-#' @name ECOTOXr
-#' @author Pepijn de Vries
-#' @references
-#' Official US EPA ECOTOX website:
-#' <https://cfpub.epa.gov/ecotox/>
-#' 
-#' Olker, J.H., Elonen, C.M., Pilli, A., Anderson, A., Kinziger, B., Erickson, S., Skopinski, M., Pomplun, A., LaLone, C.A.,
-#' Russom, C.L. and Hoff, D. (2022), The ECOTOXicology Knowledgebase: A Curated Database of Ecologically Relevant Toxicity
-#' Tests to Support Environmental Research and Risk Assessment. _Environ Toxicol Chem_, 41: 1520-1539.
-NULL
+#' Package description
+#'
+#' Everything you need to know when you start using the ECOTOXr package. \if{html}{\figure{logo.png}}
+#'
+#' The ECOTOXr provides the means to efficiently search, extract and analyse [US EPA](https://www.epa.gov/)
+#' [ECOTOX](https://cfpub.epa.gov/ecotox/) data, with a focus on reproducible results. Although the package
+#' creator/maintainer is confident in the quality of this software, it is the end users sole responsibility to
+#' assure the quality of his or her work while using this software. As per the provided license terms the package
+#' maintainer is not liable for any damage resulting from its usage. That being said, below we present some tips
+#' for generating reproducible results with this package.
+#'
+#' @section How do I get started?:
+#' Installing this package is only the first step to get things started. You need to perform the following steps
+#' in order to use the package to its full capacity.
+#'
+#' * First download a copy of the complete EPA database. This can be done by calling [download_ecotox_data()].
+#'   This may not always work on all machines as R does not always accept the website SSL certificate from the EPA.
+#'   In those cases the zipped archive with the database files can be downloaded manually with a different (more
+#'   forgiving) browser. The files from the zip archive can be extracted to a location of choice. Alternatively,
+#'   the user could try to use `[download_ecotox_data](ssl_verifypeer = 0L)` when the download URL is trusted.
+#' * Next, an SQLite database needs to be build from the downloaded files. This will be done automatically when
+#'   you used [download_ecotox_data()] in the previous step. When you have manually downloaded the files
+#'   you can call [build_ecotox_sqlite()] to build the database locally.
+#' * When the previous steps have been performed successfully, you can now search the database by calling
+#'   [search_ecotox()]. You can also use [dbConnectEcotox()] to open a connection to the
+#'   database. You can query the database using this connection and any of the methods provided from the
+#'   [DBI][DBI::DBI] or [RSQLite][RSQLite::RSQLite] packages.
+#'
+#' @section How do I obtain reproducible results?:
+#' Each individual user is responsible for evaluating the reproducibility of his or her work. Although
+#' this package offers instruments to achieve reproducibility, it is not guaranteed. In order to increase the
+#' chances of generating reproducible results, one should adhere at least to the following rules:
+#' * Always use an official release from CRAN, and cite the version used in your analyses (`citation("ECOTOXr")`).
+#'   Different versions, may produce different end results (although we will strive for backward compatibility).
+#' * Make sure you are working with a clean (unaltered) version of the database. When in doubt, download and build
+#'   a fresh copy of the database ([download_ecotox_data()]). Also cite the (release) version of the downloaded
+#'   database ([cite_ecotox()]), and the system operating system in which the local database was build
+#'   [get_ecotox_info()]). Or, just make sure that you never modify the database (e.g., write data to it, delete
+#'   data from it, etc.)
+#' * In order to avoid platform dependencies it is advised to only include non-accented alpha-numerical characters in
+#'   search terms. See also [search_ecotox] and [build_ecotox_sqlite].
+#' * When trying to reproduce database extractions from earlier database releases, filter out additions after
+#'   that specific release. This can be done by adding output fields 'tests.modified_date', 'tests.created_date' and
+#'   'tests.published_date' to your search and compare those with the release date of the database you are trying to
+#'   reproduce results from.
+#'
+#' @section Why isn't the database included in the package?:
+#' This package doesn't come bundled with a copy of the database which needs to be downloaded the first time the
+#' package is used. Why is this? There are several reasons:
+#' * The database is maintained and updated by the [US EPA](https://www.epa.gov/). This process is and should be
+#'   outside the sphere of influence of the package maintainer.
+#' * Packages on CRAN are not allowed to contain large amounts of data. Publication on CRAN is key to control
+#'   the quality of this package and therefore outweighs the convenience of having the data bundled with the package.
+#' * The user has full control over the release version of the database that is being used.
+#'
+#' @section Why does this package promotes using a local copy of the ECOTOX database?:
+#' Although this package offers experimental features for searching on-line, there are several reasons why we
+#' opted for creating a local copy:
+#' * The user would be restricted to the search options provided on the website ([ECOTOX](https://cfpub.epa.gov/ecotox/)).
+#' * The on-line database doesn't come with an API that would allow for convenient interface. This is why
+#'   features implemented in this package are experimental.
+#' * The user is not limited by an internet connection and its bandwidth.
+#' * Not all database fields, and only a limited number of records, can be retrieved from the on-line interface.
+#' @references
+#' Official US EPA ECOTOX website:
+#' <https://cfpub.epa.gov/ecotox/>
+#' 
+#' Olker, J.H., Elonen, C.M., Pilli, A., Anderson, A., Kinziger, B., Erickson, S., Skopinski, M., Pomplun, A., LaLone, C.A.,
+#' Russom, C.L. and Hoff, D. (2022), The ECOTOXicology Knowledgebase: A Curated Database of Ecologically Relevant Toxicity
+#' Tests to Support Environmental Research and Risk Assessment. _Environ Toxicol Chem_, 41: 1520-1539.
+#' @keywords internal
+"_PACKAGE"
+NULL

R/cas_handlers.r

@@ -19,7 +19,7 @@
 #' @param hyphenate A `logical` value indicating whether the formatted CAS number needs to be hyphenated.
 #' Default is `TRUE`.
 #' @param ... Arguments passed to other functions
-#' @return Functions `cas`, `c` and `as.cas` return S3 class 'cas' objects. Coercion functions
+#' @returns Functions `cas`, `c` and `as.cas` return S3 class 'cas' objects. Coercion functions
 #' (starting with 'as') return the object as specified by their respective function names (i.e., `integer`,
 #' `double`, `character`, `list` and `data.frame`). The `show.cas` and `print` functions
 #' also return formatted `charater`s. The function `is.cas` will return a single `logical` value,

R/database_access.r

@@ -35,7 +35,7 @@ get_ecotox_sqlite_file <- function(path = get_ecotox_path(), version) {
 #' @param conn An open connection to the ECOTOX database that needs to be closed.
 #' @param ... Arguments that are passed to [`dbConnect()`][RSQLite::SQLite] method
 #' or [`dbDisconnect()`][RSQLite::SQLite] method.
-#' @return A database connection in the form of a [DBI::DBIConnection-class()] object.
+#' @returns A database connection in the form of a [DBI::DBIConnection-class()] object.
 #' The object is tagged with: a time stamp; the package version used; and the
 #' file path of the SQLite database used in the connection. These tags are added as attributes
 #' to the object.
@@ -80,7 +80,7 @@ dbDisconnectEcotox <- function(conn, ...) {
 #' @param version A `character` string referring to the release version of the database you wish to locate.
 #' It should have the same format as the date in the EPA download link, which is month, day, year, separated by
 #' underscores ("%m_%d_%Y"). When missing, the most recent available copy is selected automatically.
-#' @return Returns a `vector` of [bibentry()]'s, containing a reference to the downloaded database
+#' @returns Returns a `vector` of [bibentry()]'s, containing a reference to the downloaded database
 #' and this package.
 #' @rdname cite_ecotox
 #' @name cite_ecotox
@@ -111,7 +111,7 @@ cite_ecotox <- function(path = get_ecotox_path(), version) {
 #' @param version A `character` string referring to the release version of the database you wish to locate.
 #' It should have the same format as the date in the EPA download link, which is month, day, year, separated by
 #' underscores ("%m_%d_%Y"). When missing, the most recent available copy is selected automatically.
-#' @return Returns a `vector` of `character`s, containing a information on the selected local ECOTOX database.
+#' @returns Returns a `vector` of `character`s, containing a information on the selected local ECOTOX database.
 #' @rdname get_ecotox_info
 #' @name get_ecotox_info
 #' @examples
@@ -154,7 +154,7 @@ get_ecotox_info <- function(path = get_ecotox_path(), version) {
 #' 'dose_response_details', 'dose_response_links' and 'dose_stat_method_codes'.
 #' @param include_table A `logical` value indicating whether the table name should be included
 #' as prefix. Default is `TRUE`.
-#' @return Returns a `vector` of type `character` containing the field names from the ECOTOX database.
+#' @returns Returns a `vector` of type `character` containing the field names from the ECOTOX database.
 #' @rdname list_ecotox_fields
 #' @name list_ecotox_fields
 #' @examples

R/init.r

@@ -8,7 +8,7 @@
 #' by using this URL in a different browser (or on a different machine). Alternatively, the user could try to use
 #' `[download_ecotox_data](ssl_verifypeer = 0L)` when the download URL is trusted.
 #' @param ... arguments passed on to [httr::GET()]
-#' @return Returns a `character` string containing the download URL of the latest version of the EPA ECOTOX
+#' @returns Returns a `character` string containing the download URL of the latest version of the EPA ECOTOX
 #' database.
 #' @rdname get_ecotox_url
 #' @name get_ecotox_url
@@ -36,7 +36,7 @@ get_ecotox_url <- function(...) {
 #' When arguments are omitted, this function will look in the default directory ([get_ecotox_path()]).
 #' However, it is possible to build a database file elsewhere if necessary.
 #' @param target A `character` string specifying the path where to look for the database file.
-#' @return Returns a `logical` value indicating whether a copy of the database exists. It also returns
+#' @returns Returns a `logical` value indicating whether a copy of the database exists. It also returns
 #' a `files` attribute that lists which copies of the database are found.
 #' @rdname check_ecotox_availability
 #' @name check_ecotox_availability
@@ -79,7 +79,7 @@ check_ecotox_availability <- function(target = get_ecotox_path()) {
 #' @param version A `character` string referring to the release version of the database you wish to locate.
 #' It should have the same format as the date in the EPA download link, which is month, day, year, separated by
 #' underscores ("%m_%d_%Y"). When missing, the most recent available copy is selected automatically.
-#' @return Returns a `character` string of the path.
+#' @returns Returns a `character` string of the path.
 #' `get_ecotox_path` will return the default directory of the database.
 #' `get_ecotox_sqlite_file` will return the path to the sqlite file when it exists.
 #' @rdname get_path
@@ -128,7 +128,7 @@ get_ecotox_path <- function() {
 #' @param ... Arguments passed on to [httr::GET()]. When this function fails with the error: "Peer
 #' certificate cannot be authenticated with given CA certificates", you could try to rerun the function with
 #' the option `ssl_verifypeer = 0L`. Only do so when you trust the indicated URL.
-#' @return Returns `NULL` invisibly.
+#' @returns Returns `NULL` invisibly.
 #' @rdname download_ecotox_data
 #' @name download_ecotox_data
 #' @examples
@@ -251,7 +251,7 @@ download_ecotox_data <- function(target = get_ecotox_path(), write_log = TRUE, a
 #  after building the SQLite database. See \code{\link{build_ecotox_sqlite}()} for more details. Default is
 #' `TRUE`. The log contains information on the source and destination path, the version of this package,
 #' the creation date, and the operating system on which the database was created.
-#' @return Returns `NULL` invisibly.
+#' @returns Returns `NULL` invisibly.
 #' @rdname build_ecotox_sqlite
 #' @name build_ecotox_sqlite
 #' @examples
@@ -438,7 +438,7 @@ build_ecotox_sqlite <- function(source, destination = get_ecotox_path(), write_l
       paste(unexpected_fields, collapse = ", "),
       paste(incomplete_check, collapse = ", ")
     ),
-    con = logfile, )
+    con = logfile)
   }
   return(invisible(NULL))
 }