search

LebeerLab / tidytacos

Functions to manipulate and visualize microbial community data
https://lebeerlab.github.io/tidytacos/
GNU General Public License v3.0
9 stars 1 forks source link

docs need instructions for users to import their own raw data #52

Closed kelly-sovacool closed 1 month ago

kelly-sovacool commented 3 months ago

The quick start guide directs users to the source code to learn about more options for importing data.

More options to import and convert your data can be found here.

I strongly discourage this. Novice users should not be expected to read the source code to learn how to use the package. This information should be distilled into a vignette for users to read.

(Originally posted by @kelly-sovacool in https://github.com/LebeerLab/tidytacos/issues/50#issuecomment-2275929329)

kelly-sovacool commented 1 month ago

@TheOafidian as far as I can tell this is unresolved. Maybe I'm not looking at the most updated version? Can you point to a commit or version where this was fixed?

kelly-sovacool commented 1 month ago

I see you added example pseudocode to the README and an improved description of the expected data format for raw data in the quick start vignette.

These changes are an improvement, but in my view are not quite sufficient to solve this issue. I would recommend showing a working, real example of importing raw data using the csv files you include in the package.

The README could have something like this:

(note: the file paths below assume you will have fixed the data organization as described here https://github.com/LebeerLab/tidytacos/issues/50#issuecomment-2433581017)

OTUtable <- readr::read_csv(system.file('extdata','urt','counts.csv'))
taxonomy <- readr::read_csv(system.file('extdata','urt','taxa.csv'))
sampledata <- readr::read_csv(system.file('extdata','urt','samples.csv'))

taco <- create_tidytacos(OTUtable, taxa_are_columns = FALSE)
taco <- taco%>%
  add_metadata(taxonomy, table_type="taxa")%>%
  add_metadata(sampledata, table_type="sample")

and the quick start vignette could have a highly similar example around here instead of the non-working file paths currently shown.

The key detail is showing working code with real example files so users can learn how to use the package by example.

Finally, I still strongly discourage linking to the source code in the quick start vignette (or in any user-facing docs) as here. You could opt instead to link to a page on the docs website, e.g. the section on file handling in the reference.