Introduction to dtreg

Fields

For doing that, you first need to know which fields you can use for the selected schema:

dtreg::show_fields(dt$group_comparison())
#> [1] "has_output" "has_input"  "targets"    "executes"   "see_also"  
#> [6] "label"

For example, this schema has the field “label”. If your instance included only a label, it would be:

labelled_inst <- dt$group_comparison(label = "my_test_results")

However, the data you want to write are usually more complex than this. The help page specifies which fields to use and what input is required by a field (e.g., another schema or a specific type of data, such as numeric).

String, numeric, and data frame

The most frequently used types of input are string, numeric, and data frame. Strings are used for labels and comments, and URLs are also presented as strings:

method_url <- dt$software_method(has_support_url = "https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/wilcox.test")

Numeric values are also frequently used:

dimensions <- dt$matrix_size(number_of_rows = 50,
                             number_of_columns = 2)

Some fields, such as “source_table”, require a data frame:

my_dataframe <- data.frame(W = 44.5, p = 2.2e-16)
output_dataframe <- dt$data_item(source_table = my_dataframe)

Please check which elements you include in your data frame and how you assign the columns. When in doubt, look at your column with:

class(my_dataframe$W)

The result should be either a basic R data type or an R factor.

By default, dtreg assigns a data frame a generic label “Table”. If you want to give your data frame a label, you can use a tuple. Please always include first the data frame and then the name as a string in the tuple:

library(sets)
my_tuple <- sets::tuple(my_dataframe, "the Wilcoxon test results")
output_tuple <- dt$data_item(source_table = my_tuple)

These are the most frequently used types of input that you write in a field.

More than one input in a field

Sometimes a few objects should be written in one field. In this case, simply concatenate them:

var_1 <- dt$component(label = "var_1")
var_2 <- dt$component(label = "var_2")
two_vars <- dt$group_comparison(targets = c(var_1, var_2))

Nested structure

In the example above you can see that a field of a schema might require another schema. This nested structure is important for making the data machine readable. The example above can be also written this way, and you can choose which is more convenient for you:

two_vars <- dt$group_comparison(targets = c(dt$component(label = "var_1"),
                                            dt$component(label = "var_2")))

None of the fields are mandatory: you will not get an error message if you leave any field, or all of them, empty. It makes sense, though, to create a useful JSON-LD file.

Example: writing down the Wilcoxon test results

In this vignette, we report the results of the Wilcoxon rank sum test from the help page. As we emphasize on the help page, even for this simple test, you might want to report more than the most basic version described here. Your actual results might include descriptive statistics, the effect size, and visualizations of the data. For this example, we use the ePIC datatype statistical_test_of_difference (see Load a DTR schema above).

Let us write down the details of the software method we used:

software <- dt$software(label = "R",
                        versioninfo = "4.3.1")

soft_library <- dt$software_library(
  label = "stats::wilcoxon",
  part_of = software,
  versioninfo = "4.3.1",
  has_support_url = "https://www.rdocumentation.org/packages/stats/versions/3.6.2/topics/wilcox.test"
)

soft_method <- dt$software_method(
  label = "Wilcoxon rank sum test",
  part_of = soft_library,
  is_implemented_by = "stats::wilcox.test(versicolor$Petal.Length, virginica$Petal.Length)"
)

Now we can add information about the input data:

dimensions <- dt$matrix_size(number_of_rows = 50,
                             number_of_columns = 2)
input <- dt$data_item(label = "Iris: virginica and versicolor",
                      has_characteristic = dimensions,
                      source_url =
                        "https://search.r-project.org/CRAN/refmans/MVTests/html/iris.html")

And now the vectors, or the variables, that were compared:

virginica <- dt$component(label = "petal length virginica")
versicolor <- dt$component(label = "petal length versicolor")

Finally, we have the results of the test:

df_result <- data.frame(W = 44.5, p = 2.2e-16)
output <- dt$data_item(source_table = df_result)

Let us now write everything together in the final instance:

wilcoxon_inst <- dt$group_comparison(
  label = "Wilcoxon petal length, virginica vs versicolor",
  executes = soft_method,
  has_input = input,
  targets = c(virginica, versicolor),
  has_output = output
)

Please be attentive when writing the results. In case you misspell a variable, omit a comma separating two fields, forget a closing bracket, or make another seemingly tiny mistake, you will get an error message (something like “object ‘inputt’ not found”). You can experiment with such typos and see which error messages you get.