Update readme and vignette with example

Author: multimeric

README.Rmd

@@ -275,6 +275,30 @@ metadata |>
 knitr::include_graphics("man/figures/HLA_A_tissue_plot.png")
 ```
 
+## Obtain Unharmonised Metadata
+
+Various metadata fields are *not* common between datasets, so it does not
+make sense for these to live in the main metadata table. However, we can
+obtain it using the `get_unharmonised_metadata()` function.
+
+Note how this table has additional columns that are not in the normal metadata:
+
+```{r}
+dataset = "838ea006-2369-4e2c-b426-b2a744a2b02b"
+unharmonised_meta = get_unharmonised_metadata(dataset)
+unharmonised_tbl = dplyr::collect(unharmonised_meta[[dataset]])
+unharmonised_tbl
+```
+
+If we have metadata from the normal metadata table that is from a single dataset,
+we can even join this additional metadata into one big data frame:
+```{r}
+harmonised_meta = get_metadata() |> dplyr::filter(file_id == dataset) |> dplyr::collect()
+dplyr::left_join(harmonised_meta, unharmonised_tbl, by=c("file_id", "cell_"))
+```
+
+
+
 # Cell metadata
 
 Dataset-specific columns (definitions available at cellxgene.cziscience.com)

vignettes/Introduction.Rmd

@@ -293,6 +293,28 @@ metadata |>
 knitr::include_graphics("../man/figures/HLA_A_tissue_plot.png")
 ```
 
+## Obtain Unharmonised Metadata
+
+Various metadata fields are *not* common between datasets, so it does not
+make sense for these to live in the main metadata table. However, we can
+obtain it using the `get_unharmonised_metadata()` function.
+
+Note how this table has additional columns that are not in the normal metadata:
+
+```{r}
+dataset = "838ea006-2369-4e2c-b426-b2a744a2b02b"
+unharmonised_meta = get_unharmonised_metadata(dataset)
+unharmonised_tbl = dplyr::collect(unharmonised_meta[[dataset]])
+unharmonised_tbl
+```
+
+If we have metadata from the normal metadata table that is from a single dataset,
+we can even join this additional metadata into one big data frame:
+```{r}
+harmonised_meta = get_metadata() |> dplyr::filter(file_id == dataset) |> dplyr::collect()
+dplyr::left_join(harmonised_meta, unharmonised_tbl, by=c("file_id", "cell_"))
+```
+
 # Cell metadata
 
 Dataset-specific columns (definitions available at cellxgene.cziscience.com)