From e9a6dd03b998115fee29344cecfa67b9c3d576f4 Mon Sep 17 00:00:00 2001
From: Danielle Callan <dcallan@upenn.edu>
Date: Thu, 8 Feb 2024 14:40:27 -0500
Subject: [PATCH] add anticipated usage directions to readme

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 298576a..4abde19 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,36 @@ remotes::install_github('d-callan/microbiomeData')
 ```
 
 ## Usage
-This package is may be used as a dependency in other R packages. In order to establish that depedency the developer of the 
+This package could be used directly to explore data you've downloaded from MicrobiomeDB.org, or it could be used for data management as a dependency in another package.
+
+### Direct Usage
+You can download data for a particular microbiome study from MicrobiomeDB.org. Data files from the website are organized by 'entity', with some entities representing sample metadata and others assay data. The assay data are organized into 'collections' where a particular collection might for example represent all abundances for a particular taxonomic rank for a particular assay.
+
+You can pass lists of files to a method called `mbioDataset`. You should pass one list of files for any entities representing sample metadata and a second list of files for any entities representing assay data/ collections. If you got the files from our website, we'll parse them into the appropriate collections for you. That might look something like this:
+
+```R
+myData <- mbioDataset(collections = list(fileA, fileB), metadata = list(fileD, fileE))
+```
+
+If you already read those files into R, you can do a similar thing except passing data.frame or data.table objects and things will work the same.
+
+Once you have `myData`, you can ask for specific collections from that dataset. That might look something like:
+
+```R
+myCollection <- getCollection(myData, '16S-species')
+```
+
+Once you have `myCollection`, you can start using our `microbiomeComputations` package (which was installed for you when you installed this one) to do fun things like:
+
+```R
+correlationResults <- correlation(myCollection)
+differentialAbundanceResults <- differentialAbundance(myCollection)
+```
+
+This will give you a `ComputeResult` object, with slots for `data` and `statistics` that you can explore. These objects can be difficult to parse, so we're planning a second package to help format these results in more usable and exciting ways!
+
+### Usage as a Package Dependency
+This package may be used as a dependency in other R packages. In order to establish that depedency the developer of the 
 dependent package must follow these steps:
 1. add ```microbiomeData``` to the ```Imports``` section of the dependent package's ```DESCRIPTION``` file.
 2. add a ```Remotes``` section to the dependent package's ```DESCRIPTION``` file.
@@ -31,5 +60,32 @@ Pull requests are welcome. For major changes, please open an issue first to disc
 
 Please make sure to update tests as appropriate.
 
+
+If you are trying to add data a dataset to the package, then in your local R you should:
+ 1. Make sure you have `devtools` installed locally.
+ 2. Make a branch of this repository to work in.
+ 3. Create an `mbioDataset` object in your local R using the 'Direct Usage' instructions above. 
+ 4. Make sure your new dataset and its collections, etc are named well enough for others to use them too.
+ 5. Use `usethis::use_data` to add the data to the package. Be sure you're working in the branch you made.
+ 6. Add documentation for your dataset in R/data.R following this example:
+   ```R
+   #' World Health Organization TB data
+   #'
+   #' A subset of data from the World Health Organization Global Tuberculosis
+   #' Report ...
+   #'
+   #' @format ## `who`
+   #' A data frame with 7,240 rows and 60 columns:
+   #' \describe{
+   #'   \item{country}{Country name}
+   #'   \item{iso2, iso3}{2 & 3 letter ISO country codes}
+   #'   \item{year}{Year}
+   #'   ...
+   #' }
+   #' @source <https://www.who.int/teams/global-tuberculosis-programme/data>
+   "who"
+   ```
+ 7. Make a Pull Request against this repo!
+
 ## License
 [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt)
\ No newline at end of file