[Question]: what is the strategy for visibility of datasets

[pawelru]

What is your question?

I saw in one of the workshops that we instruct people to use datasets from teal.data. These are exported but their documentation is kept internal. I see this a little bit not consistent. Let me ask then: what's our strategy on this?

Code of Conduct

• I agree to follow this project's Code of Conduct.

Contribution Guidelines

• I agree to follow this project's Contribution Guidelines.

Security Policy

• I agree to follow this project's Security Policy.

[donyunardi]

I think the data in tmg was previously meant for testing as we decoupled scda and then we have a copy of the dataset in tm packages.

However, it was removed as we tried to decrease the size of the package:
insightsengineering/nestdevs-tasks#87
insightsengineering/teal.modules.general#818

And we decided to use teal.data for our tmg examples.
I don't see why we couldn't expose the documentation now that we're using this more globally.

[pawelru]

Thanks @donyunardi. That makes sense to me. Hence I think it's reasonable to make the docs public

[donyunardi]

Acceptance Criteria

• Expose the documentation of datasets in teal.data

[donyunardi]

Actually, I just realized that we have a function called example_cdisc_data that is exported.
https://insightsengineering.github.io/teal.data/latest-tag/reference/example_cdisc_data.html

This way, we don't necessarily need to export the object and use this function to provide any additional documentation.
I can also start using this function when I need to pull example data from teal.data.

WDYT? @pawelru

[pawelru]

This would be good as well!

My ask would be just to stick with a single and consistent approach throughout our codebase (not only in this repo).

Having said that - IIRC we usually do pkg::rADSL or pkg::cADSL and not pkg::example_data("XYZ"). Don't get me wrong - it's a completely valid and fully functional approach - it's just some conventions that devs and users could already get used to.

[averissimo]

Given our extensive use of pkg::rADXX throughout our examples, documentation and workshops, I think we should embrace them and remove the internal tag.

Even if we don't export the documentation to the site, the data is in need of a cleanup. I've updated it on #376 and depending on the results of the discussion it can be adapted quickly.

[donyunardi]

@pawelru
I can't recall why we created example_data but I agree with both you and @averissimo that we should remove internal flag.

tmc also has example datasets and the documentation are grouped together:
https://insightsengineering.github.io/teal.modules.clinical/latest-tag/reference/ex_data.html

We agreed that we need to maintain consistency on how we surface these example datasets.
Grouping seems like a good approach but the Format section provide the dataset dimensions without identifying where it's coming from.

However, I don't think this information is useful for the user since these are all fake data.

For now, the decision is to follow the tmc format: remove the internal tag and group the documentation together.
We will also try to find out if we can remove the Format information from the documentation.