NEW stx_query() function implemented and Rmd updated accordingly.

.gitignore

@@ -5,4 +5,5 @@
 
 *.Rproj
 *.ini
+tests/*
 R/my_custom_fun.R

DESCRIPTION

@@ -1,12 +1,15 @@
 Package: standartox
-Version: 0.0.2
-Date: 2025-06-13
+Version: 1.0.0
+Date: 2025-06-27
 Title: Ecotoxicological Information from the Standartox Database
 Authors@R: c(
     person("Andreas", "Scharmüller",
             role = c("aut", "cre"),
             email = "andschar@protonmail.com",
-            comment = c(ORCID = "0000-0002-9290-3965"))
+            comment = c(ORCID = "0000-0002-9290-3965")),
+    person("Hannes", "Reinwald",
+            role = c("ctb"),
+            comment = c(ORCID = "0000-0003-3133-679X"))
     )
 Maintainer: Andreas Scharmüller <andschar@protonmail.com>
 Description: The Standartox database offers cleaned,

NAMESPACE

@@ -4,4 +4,5 @@ export(stx_catalog)
 export(stx_chem)
 export(stx_data)
 export(stx_meta)
+export(stx_query)
 export(stx_taxa)

README.Rmd

@@ -16,19 +16,22 @@ Standartox is a database and tool facilitating the retrieval of ecotoxicological
 
 ```{r eval=FALSE}
 # install.packages('standartox') # Currently only available on GitHub
-remotes::install_github('andschar/standartox') # development version
+if (!requireNamespace("standartox", quietly = TRUE)) {
+  remotes::install_github('andschar/standartox') # development version
+}
 ```
 
 ## Functions
 
-Standartox mainly consists of the functions `stx_catalog()` and `stx_datay()`. The former allows you to retrieve a summary catalog of the data. The latter fetches toxicity values from the database. There are also `stx_chem()`, `stx_taxa()` and `stx_meta()` funcitons which fetch chemical, taxonomic and meta data respectively.
+Standartox mainly consists of the functions `stx_catalog()` and `stx_query()`. The former allows you to retrieve a summary catalog of the data. The latter querries and aggregates the data from the database. There are also `stx_data()`, `stx_chem()`, `stx_taxa()` and `stx_meta()` funcitons which fetch the whole toxicity, chemical, taxonomic and meta data tables respectively.
 
 ### `stx_catalog()`
 
 The function returns a list of all possible arguments that can bes use in `stx_query()`.
 
 ```{r message=FALSE}
 require(standartox)
+require(data.table)
 catal = stx_catalog()
 names(catal)
 ```
@@ -37,63 +40,81 @@ names(catal)
 catal$endpoint # access the parameter top five endpoints
 ```
 
+Showing the top 10 endpoint values from `stx_catalog()`  
 ```{r echo=FALSE}
 endpoint = catal$endpoint
-knitr::kable(endpoint[1:5])
+knitr::kable(endpoint[1:10])
 ```
 
-### `stx_data()`
+### `stx_query()`
+
+The function allows you to query and filter the standartox data base.
+
+The most basic function call will return a data table filtered with default settings: 
+`endpoint_group = c("XX50", "NOEX", "LOEX")` and `duration_unit = "h"`.
 
-The function allows you to retrieve all the Standartox data.
+By setting `verbose = TRUE` the user can follow all the query steps in more detail.
 
 ```{r echo=FALSE}
-dat = stx_data()
+dat = stx_query( verbose = TRUE )
 ```
 
 ## Example: _Oncorhynchus_
 
 Let's say, we want to retrieve the 20 most tested chemicals on the genus _[Oncorhynchus](https://en.wikipedia.org/wiki/Oncorhynchus)_. We allow for test durations between 48 and 120 hours and want the tests restricted to active ingredients only. Since we are only interested in the half maximal effective concentration, we choose XX50 as our endpoint. As an aggregation method we choose the geometric mean. The code below makes use of the data.table package.
 
 ```{r warning=FALSE}
-require(data.table)
-require(standartox)
-# Retrieve the data
-dat = stx_data()
-tax = stx_taxa()
-che = stx_chem()
-# Merge
-dat2 = merge(dat, tax, by = 'tl_id', all.x = TRUE)
-dat2 = merge(dat2, che, by = 'cl_id', all.x = TRUE)
-dat3 = dat2[
-  endpoint == 'LC50' &
-  duration %between% c(48, 120) &
-  concentration_type == 'active ingredient' &
-  grepl('Oncorhynchus', taxon) # fish genus
-]
+# Run query
+oncor = stx_query(
+  tax_genus = 'Oncorhynchus',
+  endpoint_group = 'XX50',
+  concentration_unit = 'g/l',
+  effect = 'mortality',
+  duration = c(48, 120),
+  concentration_type = 'active ingredient',
+  verbose = TRUE
+)
 ```
 
 We subset the retrieved data to the 20 most tested chemicals and plot the result.
 
 ```{r warning=FALSE, message=FALSE}
-cas20 = dat3[ , .N, cas ][ order(-N) ][1:20]
-dat4 = dat3[ cas %in% cas20$cas ]
-dat4_gmn = dat4[ , .(gmn = exp(mean(log(concentration), na.rm = TRUE))), .(cas, cname, taxon)]
+cas20 = oncor[ , .N, cas ][ order(-N) ][1:20]
+oncor20 = oncor[ cas %in% cas20$cas ]
+# add new column which combines chem_name & cas
+oncor20[ , chem_name := paste0(chem_name, ' [CAS: ', cas, ']') ]
+gmn_dt = oncor20[ , .(gmn = exp(mean(log(concentration), na.rm = TRUE))), .(cas, chem_name, tax_genus)]
 ```
 
 ```{r warning=FALSE, message=FALSE, fig.width=9, fig.height=6, dpi=300}
 require(ggplot2)
-ggplot(dat4, aes(y = cname)) +
+# ggplot(oncor20, aes(y = cas)) +
+#   geom_point(aes(x = concentration, col = 'All values'),
+#              pch = 1, alpha = 0.3) +
+#   geom_point(data = gmn_dt,
+#              aes(y = reorder(cas, -gmn), x = gmn, col = 'Standartox value\n(Geometric mean)'),
+#              size = 3) +
+#   scale_x_log10(breaks = c(0.01, 0.1, 1, 10, 100, 1000, 10000),
+#                 labels = c(0.01, 0.1, 1, 10, 100, 1000, 10000)) +
+#   scale_color_viridis_d(name = '') +
+#   labs(title = 'LC50 values for Genus: Oncorhynchus',
+#        subtitle = '20 most tested chemicals',
+#        x = 'Concentration [g/L]') +
+#   theme_minimal() +
+#   theme(axis.title.y = element_blank())
+
+ggplot(oncor20, aes(y = chem_name)) +
   geom_point(aes(x = concentration, col = 'All values'),
              pch = 1, alpha = 0.3) +
-  geom_point(data = dat4_gmn,
-             aes(y = reorder(cname, -gmn), x = gmn, col = 'Standartox value\n(Geometric mean)'),
+  geom_point(data = gmn_dt,
+             aes(y = reorder(chem_name, -gmn), x = gmn, col = 'Standartox value\n(Geometric mean)'),
              size = 3) +
   scale_x_log10(breaks = c(0.01, 0.1, 1, 10, 100, 1000, 10000),
                 labels = c(0.01, 0.1, 1, 10, 100, 1000, 10000)) +
   scale_color_viridis_d(name = '') +
-  labs(title = 'Oncorhynchus EC50 values',
+  labs(title = 'LC50 values for Genus: Oncorhynchus',
        subtitle = '20 most tested chemicals',
-       x = 'Concentration (ppb)') +
+       x = 'Concentration [g/L]') +
   theme_minimal() +
   theme(axis.title.y = element_blank())
 ```