Closes #2395: Re-vamp of get-started page

[manciniedoardo]

Thank you for your Pull Request! We have developed this task checklist from the Development Process Guide to help with the final steps of the process. Completing the below tasks helps to ensure our reviewers can maximize their time on your code as well as making sure the admiral codebase remains robust and consistent.

Please check off each taskbox as an acknowledgment that you completed the task or check off that it is not relevant to your Pull Request. This checklist is part of the Github Action workflows and the Pull Request will not be merged into the main branch until you have checked off each task.

• [x] Place Closes # into the beginning of your Pull Request Title (Use Edit button in top-right if you need to update)
• [x] Code is formatted according to the tidyverse style guide. Run styler::style_file() to style R and Rmd files
• [x] Updated relevant unit tests or have written new unit tests, which should consider realistic data scenarios and edge cases, e.g. empty datasets, errors, boundary cases etc. - See Unit Test Guide
• [x] If you removed/replaced any function and/or function parameters, did you fully follow the deprecation guidance?
• [x] Review the Cheat Sheet. Make any required updates to it by editing the file inst/cheatsheet/admiral_cheatsheet.pptx and re-upload a PDF version of it to the same folder.
• [x] Update to all relevant roxygen headers and examples, including keywords and families. Refer to the categorization of functions to tag appropriate keyword/family.
• [x] Run devtools::document() so all .Rd files in the man folder and the NAMESPACE file in the project root are updated appropriately
• [x] Address any updates needed for vignettes and/or templates
• [x] Update NEWS.md under the header # admiral (development version) if the changes pertain to a user-facing function (i.e. it has an @export tag) or documentation aimed at users (rather than developers)
• [x] Build admiral site pkgdown::build_site() and check that all affected examples are displayed correctly and that all new functions occur on the "Reference" page.
• [x] Address or fix all lintr warnings and errors - lintr::lint_package()
• [x] Run R CMD check locally and address all errors and warnings - devtools::check()
• [x] Link the issue in the Development Section on the right hand side.
• [x] Address all merge conflicts and resolve appropriately
• [x] Pat yourself on the back for a job well done! Much love to your accomplishment!

[manciniedoardo]

@pharmaverse/admiral please can you take a look at the new "Programming Concepts and Conventions" vignette and add your feedback here? I'm interested in knowing if you find the content useful and/or if something is missing/superfluous.

[github-actions[bot]]

Package	Line Rate	Health
admiral	97%	✔
Summary	97% (4685 / 4813)	✔

[Fanny-Gautier]

Hi @manciniedoardo, Could you please check for the following words from concepts_conventions.Rmd file ? I would need to update the WORDLIST for "Walkthrough" word only.

Could you also run the styler for the same concepts_conventions.Rmd file as it currently fails?

Thanks.

[manciniedoardo]

Could you also run the styler for the same concepts_conventions.Rmd file as it currently fails?

Thanks.

@Fanny-Gautier thanks, I've done all of this now (I hadn't yet checked the CICD stuff as I'm waiting to get feedback from the rest of the team but I fixed them now)

[bms63]

A good opportunity for @pharmaverse/admiral_comm !! this is for the "Get Started" vignettes and trying to improve the ADaM examples and provide more information on programming concepts and conventions in admiral.

[bms63]

I am not sure if it was a good idea to split the "Get Started" page. To me it looks more confusing than before. For example why is "Derivations", "Input and Output", and "Computations" in the "walkthrough" but "Handling of Missing Values" and "Argument Conventions" in "Programming Concepts and Conventions"?

I believe the intention was to "unbury" the exprs() stuff from the Get Started page, which we are doing with the split vignette. It is a pretty critical part of programming workflow and from my understanding very unique to admiral. I don't use this in any other packages, but I don't really go beyond the verse packages.

However, I do understand that the content for each vignette might be a bit wonky!!! Let's chat on Wednesday about what to have in each vignette - I'm sure we can reach an accord!! @Fanny-Gautier and @manciniedoardo thanks for breaking up and giving us something to look at more in depth!!

[bms63]

Hi @Fanny-Gautier - did you have time to make the outline in the Issue? I think this will be helpful for us to agree on to minimize back and forth conversation on content.

[Fanny-Gautier]

Hi @Fanny-Gautier - did you have time to make the outline in the Issue? I think this will be helpful for us to agree on to minimize back and forth conversation on content.

Hi @pharmaverse/admiral here is the outline of the 2 vignettes which have been created and updated: Vignette: Simple ADSL & ADVS Walkthrough

• Main Idea
• ADSL example o Load Packages and Example Datasets o Derive Treatment Variables (TRT0xP, TRT0xA) o Derive/Impute Numeric Treatment Date/Time and Flag Variables (TRTSDTM, TRTEDTM, TRTSTMF, TRTETMF) o Derive Date Variables from Date/Time Variables (TRTSDT, TRTEDT) o Derive Treatment Duration (TRTDURD) o Derivations o Input and Output o Computations
• ADVS example o Load Packages and Example Datasets o Derive Numeric Date and Analysis Day (ADT, ADY) o Assign PARAMCD, PARAM, PARAMN, PARCAT1 o Derive Results (AVAL, AVALC) o Derive MAP Parameter
• Starting a Script
• Support
• See also

Vignette: Programming Concepts and Conventions

• Introduction
• {admiral} Functions and Options
• Handling of Missing Values
• Argument Conventions
• exprs() o What is exprs()?
• Common pitfalls o 1. Mistakenly passing something that isn’t an expression to an argument o 2. Forgetting that expressions must be evaluable in the dataset
• See also

[bms63]

Hi @Fanny-Gautier - did you have time to make the outline in the Issue? I think this will be helpful for us to agree on to minimize back and forth conversation on content.

Hi @pharmaverse/admiral here is the outline of the 2 vignettes which have been created and updated: Vignette: Simple ADSL & ADVS Walkthrough

• Main Idea

Can the main idea have some discussion on adding variables versus adding rows and in this vignette we showcase those two concepts with ADSL (adding variable), ADVS (adding records).

• ADSL example o Load Packages and Example Datasets o Derive Treatment Variables (TRT0xP, TRT0xA) o Derive/Impute Numeric Treatment Date/Time and Flag Variables (TRTSDTM, TRTEDTM, TRTSTMF, TRTETMF) o Derive Date Variables from Date/Time Variables (TRTSDT, TRTEDT) o Derive Treatment Duration (TRTDURD) o Derivations

Is this a discussion on general Derivations in admiral? Could we just move it to programming vignette or drop it.

o Input and Output

Can we move to programming vignette

o Computations

I'm a bit unsure if this is really needed to be highlighted anywhere in our Get Started documents?

• ADVS example o Load Packages and Example Datasets o Derive Numeric Date and Analysis Day (ADT, ADY) o Assign PARAMCD, PARAM, PARAMN, PARCAT1 o Derive Results (AVAL, AVALC) o Derive MAP Parameter
• Starting a Script
• Support
• See also

Vignette: Programming Concepts and Conventions

• Introduction
• {admiral} Functions and Options
• Handling of Missing Values

Can we bump to before Common pitfalls

• Argument Conventions
• exprs() o What is exprs()?
• Common pitfalls o 1. Mistakenly passing something that isn’t an expression to an argument o 2. Forgetting that expressions must be evaluable in the dataset
• See also

[nbrucken17]

I'm not sure if this is the right place for this note, and haven't been able to find the ADVS example, but the step regarding derivation of results (AVAL and AVALC) listed above caught my attention. Since the overwhelming majority of vital signs recorded have numeric results, it's unusual to need AVALC in ADVS, since AVALC should only be populated when a parameter is qualitative in nature. In addition, the only time both AVAL and AVALC should be populated on the same record is when there is a code-decode relationship between them, or for qualitative parameters when AVAL is used for controlling the sort order of the responses. This is a very common ADaM implementation issue, so I just wanted to make sure it didn't occur in the examples here. For more information, please see Section 3.3.4.2 of the ADaMIG v1.3 (also present in earlier versions of the ADaMIG).

Thanks, Nancy

[bms63]

I'm not sure if this is the right place for this note, and haven't been able to find the ADVS example, but the step regarding derivation of results (AVAL and AVALC) listed above caught my attention. Since the overwhelming majority of vital signs recorded have numeric results, it's unusual to need AVALC in ADVS, since AVALC should only be populated when a parameter is qualitative in nature. In addition, the only time both AVAL and AVALC should be populated on the same record is when there is a code-decode relationship between them, or for qualitative parameters when AVAL is used for controlling the sort order of the responses. This is a very common ADaM implementation issue, so I just wanted to make sure it didn't occur in the examples here. For more information, please see Section 3.3.4.2 of the ADaMIG v1.3 (also present in earlier versions of the ADaMIG).

Thanks, Nancy

Excellent point Nancy!! We do not follow this in our examples and we should, e.g. https://pharmaverse.github.io/admiral/articles/bds_finding.html#aval @pharmaverse/admiral could someone collect all the places that need an update and place into an issue

[bundfussr]

On the "Get Started" page I would present the main features/concepts of admiral. For each feature I would just provide a short description and a simple example such that the user gets an idea of it. For details I would link to the reference and user guides.

I would remove the ADSL and ADVS example because it requires too much space and is more focused on ADSL and ADVS concepts than admiral concepts.

What about the following outline for the "Get Started" page?

• Main Idea: modular approach
• Derivations: add variables or records, naming convention, piping
  • Adding Variables: one example, introduce common arguments like dataset_add, by_vars, new_vars
  • Adding Records: one example, introduce common arguments like set_values_to
• Argument Conventions
• Starting a Script
• Higher Order Functions
• Computations
• Filter Functions
• See Also

I would move the "Programming Concepts and Conventions" vignette to the "User Guides". Then it is clear that it must not be read for getting started. It could have the following outline.

• Introduction
• Input and Output
• {admiral} Functions and Options
• Handling of Missing Values
• Expressions in Scripts
  • Quoting and Unquoting: introduce expr(), exprs(), !!, and !!!
  • Common pitfalls

What do you think?

[Fanny-Gautier]

I found that ADSL and ADVS Walkthrough were redundant with the User Guides - even if they are simplified. I am ok with your approach.

[bms63]

I like this outline a lot!! Thanks @bundfussr.

@Fanny-Gautier when do you think you could have it ready by? We have a release on June 3rd and I think we should review thoroughly as this will be first point of contact for a lot of users!!

Thanks again for driving this forward!!

[manciniedoardo]

thanks @bundfussr, @bms63, @Fanny-Gautier for the discussion!

I am happy with the proposed new outline by @bundfussr. I will move the concepts_conventions page under user guides and make the suggested changes. Will try finish by end of next week. Happy for @Fanny-Gautier to cover the Get Started side of the update.

I am leaning towards keeping all tthe work within this PR as we have already made quite a lot of changes in this branch, which will be quite difficult to unravel. Though this will turn into a massive PR 😱 !

[manciniedoardo]

@bundfussr I have reworked the concepts and conventions vignette after your through review. please could you take a look at it again? thanks

[manciniedoardo]

@bms63 @bundfussr @Fanny-Gautier @Lina2689 as discussed last week, I have completed the revamp according to the discussing in #2395 and this PR, taking over from @Fanny-Gautier and @Lina2689's start. The PR is now ready for review.

[bms63]

@Fanny-Gautier any final comments? Be great to get this merged in before EOD. Let us know if you need some more time.

[bms63]

Done?

[manciniedoardo]

unless some sneaky hobbitses notice something else!!

I'm just joking please review to your heart's content - let's make this perfect!😆

[Fanny-Gautier]

unless some sneaky hobbitses notice something else!!

I'm just joking please review to your heart's content - let's make this perfect!😆

I promise I don't look like that in real life 🙈🤣 Trying to complete my review within the next hour 😉