Repository: marissafujimoto/catmap
Pull request #34: Add User Examples
Author: login: ajmell7
Created: 2025-03-19T22:11:15Z | Merged: 2025-03-20T19:33:35Z

Add examples to the examples folder for how each of the users in our use cases with interact with our application. This includes doctors, patients, public health officials, and maintainers. 

These are just markdown files so no testing is required other than proofreading. 


Diff:
diff --git a/examples/usage_examples.md b/examples/usage_examples.md
index 0d759b8..f312b1e 100644
--- a/examples/usage_examples.md
+++ b/examples/usage_examples.md
@@ -1,3 +1,15 @@
 # Directory of catmap Usage Examples
 
-TODO link to usage examples when we have them
\ No newline at end of file
+Select a user below to learn more about the specific roles that are relevant to them within our application. 
+
+## [Doctor](users/doctor.md) 
+As a clinician you are either using catmap to study visualizations of cancer gene data or using it to embed data collected from patients you interact with.
+
+## [Patient](users/patient.md) 
+As a patient you are using catmap either to learn more about cancer by looking at the visualization or working with your oncologist to view and interpret how your specific data fits into the catmap.
+
+## [Public Health Official](users/public_health.md) 
+As a public health official, such as a policymaker or researcher, you are using catmap to learn about cancer at a population level. This is done by using the filtering options available in the application to stratify the data by demographic information or health outcomes. You will likely not have access to additional data from individual patients that could be uploaded into the model, so you will not need to work with the embedding features of the application. 
+
+## [Maintainer](users/maintainer.md) 
+As a maintainer, you would keep the catmap application running and respond to bug reports. You would need to update the model based on new data to improve accuracy.
diff --git a/examples/users/doctor.md b/examples/users/doctor.md
new file mode 100644
index 0000000..20b163d
--- /dev/null
+++ b/examples/users/doctor.md
@@ -0,0 +1,10 @@
+# Doctor
+Click the links below to learn more about how to use the catmap application for each of the individual use cases applicable to your role. 
+
+As a doctor, we expect you already have domain knowledge about catmaps and cancer data. However, the link below provides some information specific to our application of catmaps and how to run, interact with, and interpret it.
+
+[Visualizing and Interpreting catmaps](use_cases/visualizing_and_interpreting_cancer_datasets.md) 
+
+If you have new data from a patient that you would like to embed into the catmap in order to get predicted labels for the gene expression data and determine which cells are cancerous, we recommend reading the following section.
+
+[Embedding and Interpreting New Data](use_cases/embedding_and_interpreting_new_data.md) 
diff --git a/examples/users/maintainer.md b/examples/users/maintainer.md
new file mode 100644
index 0000000..fa2af38
--- /dev/null
+++ b/examples/users/maintainer.md
@@ -0,0 +1,21 @@
+# Maintainer
+Click the links below to learn more about how to use the catmap application for each of the individual use cases we support.
+
+[Visualizing and Interpreting catmaps](use_cases/visualizing_and_interpreting_cancer_datasets.md) 
+
+[Embedding and Interpreting New Data](use_cases/embedding_and_interpreting_new_data.md) 
+
+
+As a maintainer there are many tasks you might be responsible for including but not limited to:
+## Responding to Issues / Questions:
+These should be taken in the [catmap github issues](https://github.com/marissafujimoto/catmap/issues).
+## Making Changes to the Machine Learning Models
+ 
+The models and weights were trained in colab following the notebooks available in `notebooks`. To update the models or train new ones, work from these examples using colab.
+  
+The weights and preprocessed output of the model is stored in `catmap/src/catmap/data`. For larger models / data consider storing the files with [figshare](https://figshare.com/).
+## Updating Code / Tests
+Changes to the catmap code should go through [pull requests](https://github.com/marissafujimoto/catmap/pulls) and have at least one reviewer. Automated github actions will test for regression against existing tests and formatting, but you should also expand test coverage appropriately for your test and ensure your documentation is reasonable.
+## Adding Features
+Similarly adding new features should be tested and reviewed in a pull request with tests updated / added to support the new feature.
+Additionally the usage examples in `examples` should be updated to guide users on how to use the new feature.
\ No newline at end of file
diff --git a/examples/users/patient.md b/examples/users/patient.md
new file mode 100644
index 0000000..32acf63
--- /dev/null
+++ b/examples/users/patient.md
@@ -0,0 +1,12 @@
+# Patient
+Click the links below to learn more about how to use the catmap application for each of the individual use cases applicable to your role. 
+
+As a patient, we expect that you may have some interest in learning more about catmaps and how the data they display relates to your specific type of cancer. To learn more about how to interact with and interpret our application, please click the link below.
+
+[Visualizing and Interpreting Cancer Datasets](use_cases/visualizing_and_interpreting_cancer_datasets.md) 
+
+We do not expect patients to have access to their data or be able to embed it into the model themselves, but we do anticipate that they may work with their oncologists to see how their own data would be embedded into the model. Therefore, we still provide patients with an explanation of how the embedding and interpretation of new data works.
+
+DNA sequencing is not often used in cancer diagnosis, and the scientific community relies on tissue sample donations in order to advance this technology. Patients who donate their tissue samples are helping improve this area of research and diagnosis by providing additional data and insights for applications such as catmaps. We hope that doctors and patients will work together to advance this area of research.
+
+[Embedding and Interpreting New Data](use_cases/embedding_and_interpreting_new_data.md) 
diff --git a/examples/users/public_health.md b/examples/users/public_health.md
new file mode 100644
index 0000000..ce2dfd6
--- /dev/null
+++ b/examples/users/public_health.md
@@ -0,0 +1,6 @@
+# Public Health Official
+Click the link below to learn more about how to use the catmap application for each of the individual use cases applicable to your role. 
+
+As a public health official we do not expect you to have access to individual patient data to embed into the model, so we only provide information on how to use and interpret the baseline catmap models that we have provided within our application. Please go to the link below to learn more.
+
+[Visualizing and Interpreting Cancer Datasets](use_cases/visualizing_and_interpreting_cancer_datasets.md) 
diff --git a/examples/users/use_cases/embedding_and_interpreting_new_data.md b/examples/users/use_cases/embedding_and_interpreting_new_data.md
new file mode 100644
index 0000000..14041d2
--- /dev/null
+++ b/examples/users/use_cases/embedding_and_interpreting_new_data.md
@@ -0,0 +1,37 @@
+# Embedding New Patient Data
+
+Catmap can be used to embed transcriptomic data collected from Non-Small-Cell-Lung Cancer (NSCLC) patients. Catmap has limited ability to preprocess new patient data. We recommend using [seurat](https://satijalab.org/seurat/) to preprocess your data. Ultimately it will need to be processed in the following fashion:
+
+1. Select for the 2000 genes catmap is trained on. These genes can be loaded from the variable names of the adata_test.h5ad available in the `catmap/tests/data/` subdirectory. Export a h5ad / anndata file with the X as the raw gene counts for these genes.
+
+2. Then in the catmap UI go to the NSCLC page and click Embed New Data and follow the prompts to upload your patient data. You can use the data available in `catmap/tests/data` to test this. The results should appear as below.
+
+See the section on "Interacting with Catmaps" to find how to get the to "Embed New Data" option. Here is a screenshot of its location on the NSCLC page:
+
+![image](screenshots/embed_new_data.png)
+
+After clicking the "Embed New Data" button, you will be taken to the following page: 
+
+![image](screenshots/embed_page.png)
+
+Upload your data here and wait for the logic to run.
+
+After the emebedding logic runs, catmap will show a plot of the embedded UMAP coordinates colored by the predicted cell types for the uploaded sample. Here is an example with our sample data:
+
+![image](screenshots/new_embedding_example.png)
+
+Finally, if you scroll to the bottom of the page you will see a text dropdown with more information about the embedding as well as an option to return to the home page. 
+
+![image](screenshots/bottom_of_embedding_page.png)
+
+# Interpreting the Embedding Results
+
+Three steps happen during the embedding process.
+
+1. A trained model embeds the new data using its learned embedding trained from our reference dataset.
+2. A random forest classifier predicts the cell types of the new cells.
+3. A UMAP reduction is calculated for the newly embedded points.
+
+Note that the UMAP reduction does not correspond to the reference NSCLC page’s UMAP coordinates since it focuses only on the newly uploaded data.
+
+Also note that the ratio of classified points depends on the method of collection of the tissue samples and specifically the ratio of tissue types collected.
\ No newline at end of file
diff --git a/examples/users/use_cases/screenshots/bottom_of_embedding_page.png b/examples/users/use_cases/screenshots/bottom_of_embedding_page.png
new file mode 100644
index 0000000..fb5ac4c
Binary files /dev/null and b/examples/users/use_cases/screenshots/bottom_of_embedding_page.png differ
diff --git a/examples/users/use_cases/screenshots/bottom_of_page.png b/examples/users/use_cases/screenshots/bottom_of_page.png
new file mode 100644
index 0000000..c2e9d80
Binary files /dev/null and b/examples/users/use_cases/screenshots/bottom_of_page.png differ
diff --git a/examples/users/use_cases/screenshots/embed_new_data.png b/examples/users/use_cases/screenshots/embed_new_data.png
new file mode 100644
index 0000000..22b5641
Binary files /dev/null and b/examples/users/use_cases/screenshots/embed_new_data.png differ
diff --git a/examples/users/use_cases/screenshots/embed_page.png b/examples/users/use_cases/screenshots/embed_page.png
new file mode 100644
index 0000000..4181348
Binary files /dev/null and b/examples/users/use_cases/screenshots/embed_page.png differ
diff --git a/examples/users/use_cases/screenshots/expander_buttons.png b/examples/users/use_cases/screenshots/expander_buttons.png
new file mode 100644
index 0000000..e826cfa
Binary files /dev/null and b/examples/users/use_cases/screenshots/expander_buttons.png differ
diff --git a/examples/users/use_cases/screenshots/filter_options.png b/examples/users/use_cases/screenshots/filter_options.png
new file mode 100644
index 0000000..c713d23
Binary files /dev/null and b/examples/users/use_cases/screenshots/filter_options.png differ
diff --git a/examples/users/use_cases/screenshots/home_page.png b/examples/users/use_cases/screenshots/home_page.png
new file mode 100644
index 0000000..874e4bb
Binary files /dev/null and b/examples/users/use_cases/screenshots/home_page.png differ
diff --git a/examples/users/use_cases/screenshots/info_button.png b/examples/users/use_cases/screenshots/info_button.png
new file mode 100644
index 0000000..5aa38b5
Binary files /dev/null and b/examples/users/use_cases/screenshots/info_button.png differ
diff --git a/examples/users/use_cases/screenshots/lung_cancer.png b/examples/users/use_cases/screenshots/lung_cancer.png
new file mode 100644
index 0000000..d891ef5
Binary files /dev/null and b/examples/users/use_cases/screenshots/lung_cancer.png differ
diff --git a/examples/users/use_cases/screenshots/new_embedding_example.png b/examples/users/use_cases/screenshots/new_embedding_example.png
new file mode 100644
index 0000000..9af2ad7
Binary files /dev/null and b/examples/users/use_cases/screenshots/new_embedding_example.png differ
diff --git a/examples/users/use_cases/screenshots/new_filter_selection.png b/examples/users/use_cases/screenshots/new_filter_selection.png
new file mode 100644
index 0000000..70d6dac
Binary files /dev/null and b/examples/users/use_cases/screenshots/new_filter_selection.png differ
diff --git a/examples/users/use_cases/screenshots/return_home.png b/examples/users/use_cases/screenshots/return_home.png
new file mode 100644
index 0000000..60d0017
Binary files /dev/null and b/examples/users/use_cases/screenshots/return_home.png differ
diff --git a/examples/users/use_cases/visualizing_and_interpreting_cancer_datasets.md b/examples/users/use_cases/visualizing_and_interpreting_cancer_datasets.md
new file mode 100644
index 0000000..574ea5e
--- /dev/null
+++ b/examples/users/use_cases/visualizing_and_interpreting_cancer_datasets.md
@@ -0,0 +1,54 @@
+# Interacting with catmaps
+
+To open the cancer dataset visualizations (assuming catmap is correctly installed):
+
+First launch catmap from the command line with
+
+```
+catmap
+```
+
+You will be taken the a web application with the following home screen:
+
+![image](screenshots/home_page.png)
+
+Click on the Non-Small-Cell-Lung Cancer button to navigate to a new page with the following visualization for the Lung Cancer dataset:
+
+![image](screenshots/lung_cancer.png)
+
+You can select various options in the dropdown at the top to view the data with different groupings. 
+
+![image](screenshots/filter_options.png)
+
+If we select Cell_Cluster_level1, we see that the catmap updates as follows:
+
+![image](screenshots/new_filter_selection.png)
+
+There is also an info button on the far right that provides more information about how to interact with the visualization:
+
+![image](screenshots/info_button.png)
+
+If you scroll down, you'll see that there are a few more buttons to inteact with at the bottom of the page.
+
+![image](screenshots/bottom_of_page.png)
+
+You can click on the "Visualization Overview" or "Data Overview" dropdowns to learn more about the catmap.
+
+![image](screenshots/expander_buttons.png)
+
+There is also an option to "Embed New Data", but this is only relevant to some users, so it will be explained in another section. 
+
+Finally, you can click "Back to Home" to return to the home page.
+
+![image](screenshots/return_home.png)
+
+Back at the home page you can then select the second option, "Colon Cancer" to go through the same steps above for a new dataset. 
+
+# Interpreting Visualizations
+
+For the visualizations, you will see visual embeddings of the top expressed genes in our training datasets. More details about the machine learning algorithms and preprocessing are available in the README, but some general takeaways are:
+
+1. The embeddings were trained on raw counts data using an unsupervised approach.
+2. As a rough rule of thumb, the distances of the embeddings tend to be more significant when the points are close compared to when they are further. Do not rely on larger distances (> 20% of the total embedding volume) to mean any significance. This is because while the final embedding is in two dimensions, the machine learning algorithm operates in higher dimensional space.
+3. The known labels of the cells (e.g. the patient they come from) are projected onto the points after training.
+


Reviews:
user: login: marissafujimoto
state: COMMENTED
author_association: OWNER
submitted_at: 2025-03-19T23:36:54Z
user: login: marissafujimoto
state: COMMENTED
author_association: OWNER
submitted_at: 2025-03-19T23:42:34Z
user: login: marissafujimoto
body: Please fix these minor typos, but other than that it looks really great to me!
state: APPROVED
author_association: OWNER
submitted_at: 2025-03-20T19:12:40Z
user: login: marissafujimoto
state: COMMENTED
author_association: OWNER
submitted_at: 2025-03-20T19:22:32Z

Review comments:
diff_hunk: @@ -0,0 +1,13 @@
+# Visualizing Cancer Datasets
+
+To open the visualizations (assuming catmap is correctly installed):
+
+First launch catmap from the command line with
+
+```
+catmap
+```
+
+Then navigate to either page 1 or page 2.
+
+TODO pic of home page
path: examples/users/use_cases/visualizing_cancer_datasets.md
user: login: marissafujimoto
body: After we add this pic (and pics of page 1 and page 2 can we also write a short blurb saying what it is that's in the pic and what the user can do on each page.
created_at: 2025-03-19T23:36:54Z
author_association: OWNER
diff_hunk: @@ -0,0 +1,10 @@
+# Embedding New Patient Data
+
+Catmap can be used to embed transcriptomic data collected from NSCLC patients. Catmap has limited ability to preprocess new patient data. We recommend using (seurat)[https://satijalab.org/seurat/) to preprocess your data. Ultimately it will need to be processed in the following fashion:
+
+1. Select for the 2000 genes catmap is trained on. These genes can be loaded from the variable names of the adata_test.h5ad available in the catmap/test/data/ subdirectory.
+Export an h5ad / anndata file with the X as the raw gene counts for these genes.
+
+2. Then in the catmap UI go to the NSCLC page and click Embed New Data and follow the prompts to upload your patient data. You can use the data available in catmap/test/data to test this. The results should appear as below
+
+TODO pic of embedding result.
path: examples/users/use_cases/embedding_new_data.md
user: login: marissafujimoto
body: ```suggestion
2. Then in the catmap UI go to the NSCLC page and click Embed New Data and follow the prompts to upload your patient data. You can use the data available in catmap/test/data to test this. The results should appear as below.

TODO pic of embedding result.

After the emebedding logic runs, catmap will show a plot of the embedded UMAP coordinates colored by the predicted cell types for the uploaded sample.
```

Just adding a suggested wording to explain what's on the screenshot.
created_at: 2025-03-19T23:42:34Z
author_association: OWNER
diff_hunk: @@ -0,0 +1,54 @@
+# Interacting with catmaps
+
+To open the cancer dataset visualizations (assuming catmap is correctly installed):
+
+First launch catmap from the command line with
+
+```
+catmap
+```
+
+You will be taken the a web application with the following home screen:
+
+![image](screenshots/home_page.png)
+
+Click on the Non-Small-Cell-Lung Cancer button to navigate to a new page with the following visualization for the Lung Cancer dataset:
+
+![image](screenshots/lung_cancer.png)
+
+You can select various options in the dropdown at the top to view the data with different groupings. 
+
+![image](screenshots/filter_options.png)
+
+If we select Cell_Cluster_level1, we see that the catmap updates as follows:
+
+![image](screenshots/new_filter_selection.png)
+
+There is also an info button on the far right that provides more information about how to iteract with the visualization:
path: examples/users/use_cases/visualizing_and_interpreting_cancer_datasets.md
user: login: marissafujimoto
body: ```suggestion
There is also an info button on the far right that provides more information about how to interact with the visualization:
```
created_at: 2025-03-20T19:05:34Z
author_association: OWNER
diff_hunk: @@ -0,0 +1,38 @@
+# Embedding New Patient Data
+
+Catmap can be used to embed transcriptomic data collected from Non-Small-Cell-Lung Cancer (NSCLC) patients. Catmap has limited ability to preprocess new patient data. We recommend using (seurat)[https://satijalab.org/seurat/) to preprocess your data. Ultimately it will need to be processed in the following fashion:
path: examples/users/use_cases/embedding_and_interpreting_new_data.md
user: login: marissafujimoto
body: ```suggestion
Catmap can be used to embed transcriptomic data collected from Non-Small-Cell-Lung Cancer (NSCLC) patients. Catmap has limited ability to preprocess new patient data. We recommend using (seurat)[https://satijalab.org/seurat/] to preprocess your data. Ultimately it will need to be processed in the following fashion:
```
created_at: 2025-03-20T19:08:07Z
author_association: OWNER
diff_hunk: @@ -0,0 +1,38 @@
+# Embedding New Patient Data
+
+Catmap can be used to embed transcriptomic data collected from Non-Small-Cell-Lung Cancer (NSCLC) patients. Catmap has limited ability to preprocess new patient data. We recommend using (seurat)[https://satijalab.org/seurat/) to preprocess your data. Ultimately it will need to be processed in the following fashion:
+
+1. Select for the 2000 genes catmap is trained on. These genes can be loaded from the variable names of the adata_test.h5ad available in the catmap/test/data/ subdirectory.
+Export an h5ad / anndata file with the X as the raw gene counts for these genes.
+
+2. Then in the catmap UI go to the NSCLC page and click Embed New Data and follow the prompts to upload your patient data. You can use the data available in catmap/test/data to test this. The results should appear as below.
path: examples/users/use_cases/embedding_and_interpreting_new_data.md
user: login: marissafujimoto
body: ```suggestion
1. Select for the 2000 genes catmap is trained on. These genes can be loaded from the variable names of the adata_test.h5ad available in the `catmap/tests/data/` subdirectory.
Export a h5ad / anndata file with the X as the raw gene counts for these genes.

2. Then in the catmap UI go to the NSCLC page and click Embed New Data and follow the prompts to upload your patient data. You can use the data available in `catmap/tests/data` to test this. The results should appear as below.
```
created_at: 2025-03-20T19:09:20Z
author_association: OWNER
diff_hunk: @@ -0,0 +1,2 @@
+# Maintainer
+Click the links below to learn more about how to use the catmap application for each of the individual use cases applicable to your role. 
path: examples/users/maintainer.md
user: login: marissafujimoto
body: ```suggestion
# Maintainer
Click the links below to learn more about how to use the catmap application for each of the individual use cases we support.

[Visualizing and Interpreting catmaps](use_cases/visualizing_and_interpreting_cancer_datasets.md) 

[Embedding and Interpreting New Data](use_cases/embedding_and_interpreting_new_data.md) 

As a maintainer there are many tasks you might be responsible for including but not limited to:

## Responding to Issues / Questions:

These should be taken in the [catmap github issues](https://github.com/marissafujimoto/catmap/issues).

## Making Changes to the Machine Learning Models
 
The models and weights were trained in colab following the notebooks available in `notebooks`. To update the models or train new ones, work from these examples using colab.
  
The weights and preprocessed output of the model is stored in `catmap/src/catmap/data`. For larger models / data consider storing the files with [figshare](https://figshare.com/).

## Updating Code / Tests

Changes to the catmap code should go through [pull requests](https://github.com/marissafujimoto/catmap/pulls) and have at least one reviewer. Automated github actions will test for regression against existing tests and formatting, but you should also expand test coverage appropriately for your test and ensure your documentation is reasonable.

## Adding Features

Similarly adding new features should be tested and reviewed in a pull request with tests updated / added to support the new feature.

Additionally the usage examples in `examples` should be updated to guide users on how to use the new feature.
```
created_at: 2025-03-20T19:22:32Z
author_association: OWNER

PR comments:
user: login: coveralls
created_at: 2025-03-19T22:17:17Z
body: ## Pull Request Test Coverage Report for [Build 13977765894](https://coveralls.io/builds/72842360)

### Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

- For more information on this, see <a target="_blank" href="https://docs.coveralls.io/build-types#tracking-coverage-changes-with-pull_request-builds">Tracking coverage changes with pull request builds</a>.
- To avoid this issue with future PRs, see these <a target="_blank" href="https://docs.coveralls.io/build-types#recommended-ci-configurations">Recommended CI Configurations</a>.
- For a quick fix, <a target="_blank" href="https://github.blog/changelog/2022-02-03-more-ways-to-keep-your-pull-request-branch-up-to-date/#update-your-pull-request-branch-by-rebasing">rebase this PR at GitHub</a>. Your next report should be accurate.

### Details

* **0** of **0**   changed or added relevant lines in **0** files are covered.
* No unchanged relevant lines lost coverage.
* Overall coverage remained the same at **99.407%**

---



|  Totals | [![Coverage Status](https://coveralls.io/builds/72842360/badge)](https://coveralls.io/builds/72842360) |
| :-- | --: |
| Change from base [Build 13973110554](https://coveralls.io/builds/72837232): |  0.0% |
| Covered Lines: | 503 |
| Relevant Lines: | 506 |

---
##### 💛  - [Coveralls](https://coveralls.io)

author_association: NONE
user: login: marissafujimoto
created_at: 2025-03-19T23:34:51Z
body: I really like the organization! Everything I read looked correct and good wording.

I think we should combine some of the docs though. `examples/users/use_cases/embedding_new_data.md` and `examples/users/use_cases/interpreting_embedding_results.md` should go together I think.

Similarly `examples/users/use_cases/visualizing_cancer_datasets.md` `examples/users/use_cases/interpreting_visualizations.md`. 

I understand for the patient they are not embedding new data and only interpreting, but I wonder if we should just write a short blurb to contextualize how the doctor is using catmap and then link to that section of the joined embedding page. Also in general just restating why each user is doing each use case would be good in their users markdown file I think.
author_association: OWNER