The admiral Glossary, Acronyms, Thesaurus.

[bms63]

What is a Derivation? Could we say something about how the function is performing the derivation. I know what this is doing I just think a new user might be confused

Originally posted by @bms63 in #1744 (comment)

[bms63]

Please see discussion in linked PR. I'm not sure how feasible this is, but having a Glossary would be so nice for users and for develoeprs!! @pharmaverse/admiral

[ramiromagno]

Hi!,

If I may chime in...

For someone who just started out looking into {admiral}, you're indeed faced with the derivation concept early on.

From the Get Started vignette:

(...) Each derivation adds one or more variables or parameters to the processed dataset. (...)

Which gives you the feeling that derivation is just dplyr::mutate() with perhaps some semantic sugar on top.

But @bundfussr's PR also adds:

A function that performs a specific derivation is expected. A derivation adds variables or observations to a dataset.

Clarifying that a derivation can also be about adding observations. So that implies that a derivation may change a dataset both horizontally and vertically. And so, from a functional point of view, it is more than a simple dplyr::mutate(). Highlighting the differences with respect to dplyr::mutate() might be really helpful for someone who's already an R programmer but is getting to know this specific domain of knowledge.

In addition, I think it would be important to consider making these distinctions about variables: https://dplyr.tidyverse.org/articles/programming.html#data--and-env-variables. Likewise, you use the word parameter in two ways: in the sense of the BMI parameter, and in the sense of a parameter of a function.

Including these concepts early on in your docs would be, at least for me, really helpful to avoid misunderstandings down the line.

[kaz462]

In addition, I think it would be important to consider making these distinctions about variables: https://dplyr.tidyverse.org/articles/programming.html#data--and-env-variables. Likewise, you use the word parameter in two ways: in the sense of the BMI parameter, and in the sense of a parameter of a function.

good point, agree Glossary/documentation would be nice to have for R programmers new to domain knowledge (or vice versa)

"add parameters" from the Get Started vignette means adding records horizontally (e.g., a dataset has column PARAM=parameter1, add/derive new records for PARAM=parameter2). it has the same meaning as from @bundfussr's PR, but could be confusing without the definition of "parameters"

(...) Each derivation adds one or more variables or parameters to the processed dataset. (...)

[thomas-neitmann]

Probably worthwile to highlight that variables = columns and parameters = rows.

[sophie-gem]

Likewise, you use the word parameter in two ways: in the sense of the BMI parameter, and in the sense of a parameter of a function.

When we're talking about 'parameter of a function', I don't know if it may be worth using the term 'argument' instead (in line with typical 'R-speak')? For example, if we take the documentation for derive_vars_duration

and replace the highlighted 'parameter' with 'argument'?

I realise that this may be a big task....but I'm just thinking it would give newcomers a clearer distinction between the two current uses of the word 'parameter'.

[sophie-gem]

In terms of a glossary, would a possible work-around be to either add a 'terminology' section to the first vignette or maybe even add them as questions to the 'FAQs' vignette (e.g. 'What do you mean by "parameter"? or 'What is a "derivation"?)

Either that or could we have a 'glossary' vignette, that builds overtime? So just start with those key words highlighted above and then add as the package develops further?

Just some semi suggestions as a starter for 10...

[bundfussr]

Many good ideas! Summarizing them I would propose the following:

• We add a "Glossary" vignette where we define terms like "derivation", "parameter", "variable", ... Each term should have an anchor such that it is possible to link to it.
• If a term is used in the documentation, it should link to the glossary where it is useful, e.g., on the "Get Started" page.
• For datasets we use CDISC terminology, i.e., variable ~ column in a dataset, record ~ row in a dataset, parameter ~ set of records in a BDS dataset.
• For R we use "argument" for function arguments/parameters and "object" for variables.
• We update documentation and programming strategy accordingly.

I have added the topic to the agenda of the next dev meeting on Wednesday.

[bms63]

Many good ideas! Summarizing them I would propose the following:

• We add a "Glossary" vignette where we define terms like "derivation", "parameter", "variable", ... Each term should have an anchor such that it is possible to link to it.
• If a term is used in the documentation, it should link to the glossary where it is useful, e.g., on the "Get Started" page.
• For datasets we use CDISC terminology, i.e., variable ~ column in a dataset, record ~ row in a dataset, parameter ~ set of records in a BDS dataset.
• For R we use "argument" for function arguments/parameters and "object" for variables.
• We update documentation and programming strategy accordingly.

I have added the topic to the agenda of the next dev meeting on Wednesday.

Perhaps the FAQ could be turned into a FAQ/Glossary Vignette. We are adding 3 vignettes in this release and that drop-down tab is getting pretty epic!! I agree on standardizing our language.

[zdz2101]

short-script if any one wants to look at all "words" (perhaps helps us generate the list of words to define) used in relevant R/Rmd code we write

library(dplyr)
library(purrr)
library(tidyr)
library(stringr)
all_words_r_scripts <- data.frame(rscripts = c(list.files("./R/"), list.files("./vignettes"))) %>%
  filter(str_detect(rscripts, ".R|.Rmd")) %>%
  mutate(
    paths = ifelse(str_detect(rscripts, ".Rmd"),
                   paste0("./vignettes/", rscripts, sep = ""),
                   paste0("./R/", rscripts, sep = "")),
    lines = map(paths, readLines)
    ) %>%
  unnest(cols = c(lines)) %>%
  mutate(words = str_split(lines, " ")) %>%
  unnest(cols = c(words)) %>%
  mutate(words = tolower(words)) %>%
  group_by(words) %>%
  count() %>%
  arrange(desc(n)) %>%
  filter(nchar(words) >= 3)

[bms63]

Hi @pharmaverse/admiral team. I updated this issue with points from this thread and core meeting discussion. This one sounds a bit epic so we might want to break into smaller issues, but this could be its parent issue.

Feel free to wordsmith it if you think more clarity is needed.

[bundfussr]

Hi @pharmaverse/admiral team. I updated this issue with points from this thread and core meeting discussion. This one sounds a bit epic so we might want to break into smaller issues, but this could be its parent issue.

Feel free to wordsmith it if you think more clarity is needed.

@bms63 , it seems that something went wrong. I can't see the update. The description is still the original one.

[bms63]

Hi @pharmaverse/admiral team. I updated this issue with points from this thread and core meeting discussion. This one sounds a bit epic so we might want to break into smaller issues, but this could be its parent issue.
Feel free to wordsmith it if you think more clarity is needed.

@bms63 , it seems that something went wrong. I can't see the update. The description is still the original one.

Ah man...that makes me sad

[StefanThoma]

Many good ideas! Summarizing them I would propose the following:

• We add a "Glossary" vignette where we define terms like "derivation", "parameter", "variable", ... Each term should have an anchor such that it is possible to link to it.
• If a term is used in the documentation, it should link to the glossary where it is useful, e.g., on the "Get Started" page.
• For datasets we use CDISC terminology, i.e., variable ~ column in a dataset, record ~ row in a dataset, parameter ~ set of records in a BDS dataset.
• For R we use "argument" for function arguments/parameters and "object" for variables.
• We update documentation and programming strategy accordingly.

I have added the topic to the agenda of the next dev meeting on Wednesday.

I am not sure what you mean with: "object" for variables.
Has this already been discussed further?
I think that "object" is too broad of a term, considering that functions are objects as well.
Or did you mean any objects at all?
Please clarify.

[zdz2101]

@bms63 Should we move this and #1529 into discussion? Feel like broad sense, these are post-stabilization "clean docs" ready front & center for users

[bms63]

Yeah - I think this might need to be put into a discussion and broken out into smaller decisions. We actually did some of this already with parameter/argument update.

[bms63]

I have linked this in our Roadmap 2.0 discussion - #2191 (comment) and will close this