From 6232a93dcdbb1bc9a0e77f6707755fbe027cfe8d Mon Sep 17 00:00:00 2001 From: changbenjamin Date: Fri, 30 May 2025 13:23:52 -0700 Subject: [PATCH 1/3] updated README.md with information about examples --- README.md | 52 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6d2cf3b..b13d91a 100644 --- a/README.md +++ b/README.md @@ -37,13 +37,13 @@ See our [blog](https://www.futurehouse.org/research-announcements/demonstrating- The project uses `pyproject.toml` for dependency management. Install the base package and development dependencies (which include Jupyter): ```bash - uv pip install -e .[dev] + uv pip install -e '.[dev]' ``` OR ```bash - pip install -e .[dev] + pip install -e '.[dev]' ``` 4. **Set API Keys:** @@ -76,14 +76,7 @@ See our [blog](https://www.futurehouse.org/research-announcements/demonstrating- config = RobinConfiguration( disease_name="DISEASE_NAME", # <-- Customize the disease name here # You can also explicitly set API keys here if not using environment variables: - # futurehouse_api_key="your_futurehouse_api_key_here", - # llm_config={ # Example if you want to specify a different LLM - # "model_list": [{ - # "model_name": "gpt-4-turbo", - # "litellm_params": {"model": "gpt-4-turbo", "api_key": os.getenv("OPENAI_API_KEY")} - # }] - # }, - # llm_name="gpt-4-turbo" # if overriding default + # futurehouse_api_key="your_futurehouse_api_key_here" ) ``` @@ -100,11 +93,44 @@ See our [blog](https://www.futurehouse.org/research-announcements/demonstrating- ## Expected Output -- **Logs:** Detailed logs will be printed in the notebook output and/or your console, showing the progress of each step. -- **Files:** Results, including generated queries, literature reviews, candidate proposals, and rankings, will be saved in a new subdirectory within `robin_output/`. The subdirectory name is typically based on the `disease_name` and a timestamp (e.g., `robin_output/PCOS_2023-10-27_10-30/`). +- **Logs:** Detailed logs will be printed in the notebook output and/or your console, showing the progress of each step (e.g., query generation, literature search, candidate proposal, ranking). + +- **Files:** Results are saved in a new subdirectory within `robin_output/`, named after the `disease_name` and a timestamp (e.g., `robin_output/DISEASE_NAME_YYYY-MM-DD_HH-MM/`). This directory contains a structured set of outputs, including: + - Folders for detailed hypotheses and literature reviews for both experimental assays and therapeutic candidates (e.g., `experimental_assay_detailed_hypotheses/`, `therapeutic_candidate_literature_reviews/`). + - CSV files for ranking results and final ranked lists (e.g., `experimental_assay_ranking_results.csv`, `ranked_therapeutic_candidates.csv`). + - Text summaries for proposed assays and candidates (e.g., `experimental_assay_summary.txt`, `therapeutic_candidates_summary.txt`). + - If the optional data analysis step is run (using the `data_analysis` function), there will be an additional `data_analysis/` subfolder containing outputs from the Finch agent (e.g., `consensus_results.csv`). Correspondingly, some therapeutic candidate-related files generated after this step may have an `_experimental` suffix (e.g., `ranked_therapeutic_candidates_experimental.csv`, `therapeutic_candidate_detailed_hypotheses_experimental/`). + + +### Overview of `examples` Folder: + +The `examples` folder provides practical usage demonstrations of pre-generated output directories from complete Robin runs for 10 diseases: +* Age-Related Hearing Loss +* Celiac Disease +* Charcot-Marie-Tooth Disease +* Chronic Kidney Disease +* Friedreich's Ataxia +* Glaucoma +* Idiopathic Pulmonary Fibrosis +* Non-alcoholic Steatohepatitis +* Polycystic Ovary Syndrome +* Sarcopenia + +Each disease-specific subfolder mirrors the exact file and directory structure a user would obtain in their own `robin_output/` directory after a run: +* `experimental_assay_detailed_hypotheses/`: Text files containing detailed reports for each proposed experimental assay. +* `experimental_assay_literature_reviews/`: Text files of literature reviews generated from queries related to assay development. +* `experimental_assay_ranking_results.csv`: CSV file showing pairwise comparison results for assay ranking. +* `experimental_assay_summary.txt`: A textual summary of the proposed experimental assays. +* `ranked_therapeutic_candidates.csv`: CSV file listing the final ranked therapeutic candidates and their strength scores. +* `therapeutic_candidate_detailed_hypotheses/`: Text files with detailed reports for each proposed therapeutic candidate. +* `therapeutic_candidate_literature_reviews/`: Text files of literature reviews for therapeutic candidate queries. +* `therapeutic_candidate_ranking_results.csv`: CSV file of pairwise comparison results for candidate ranking. +* `therapeutic_candidates_summary.txt`: A textual summary of the proposed therapeutic candidates. + +These example outputs are provided to help users to understand the depth, format, and typical errors seen in Robin runs across various diseases. ## Advanced Usage -A full example trajectory can be found in the `robin_full.ipynb` notebook. This notebook includes the parameters and agents used in the paper. Note that the parameters used in this notebook exceeds the current free rate limits. +A full example trajectory of both the initial therapeutic candidate generation and experimental data analysis can be found in the `robin_full.ipynb` notebook. This notebook includes the parameters and agents used in the paper. Note that the parameters used in this notebook exceeds the current free rate limits and data analysis functionality is currently in beta testing. While this guide focuses on the `robin_demo.ipynb` notebook, the `robin` Python module (in the `robin/` directory) can be imported and its functions (`experimental_assay`, `therapeutic_candidates`, `data_analysis`) can be used programmatically in your own Python scripts for more customized workflows. From 64147715b897005d176e9017712530e6e4fd3b14 Mon Sep 17 00:00:00 2001 From: changbenjamin Date: Fri, 30 May 2025 13:25:18 -0700 Subject: [PATCH 2/3] updated README.md with information about examples --- README.md | 49 +++++++++++++++++++++++++------------------------ 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index b13d91a..f57e879 100644 --- a/README.md +++ b/README.md @@ -96,36 +96,37 @@ See our [blog](https://www.futurehouse.org/research-announcements/demonstrating- - **Logs:** Detailed logs will be printed in the notebook output and/or your console, showing the progress of each step (e.g., query generation, literature search, candidate proposal, ranking). - **Files:** Results are saved in a new subdirectory within `robin_output/`, named after the `disease_name` and a timestamp (e.g., `robin_output/DISEASE_NAME_YYYY-MM-DD_HH-MM/`). This directory contains a structured set of outputs, including: - - Folders for detailed hypotheses and literature reviews for both experimental assays and therapeutic candidates (e.g., `experimental_assay_detailed_hypotheses/`, `therapeutic_candidate_literature_reviews/`). - - CSV files for ranking results and final ranked lists (e.g., `experimental_assay_ranking_results.csv`, `ranked_therapeutic_candidates.csv`). - - Text summaries for proposed assays and candidates (e.g., `experimental_assay_summary.txt`, `therapeutic_candidates_summary.txt`). - - If the optional data analysis step is run (using the `data_analysis` function), there will be an additional `data_analysis/` subfolder containing outputs from the Finch agent (e.g., `consensus_results.csv`). Correspondingly, some therapeutic candidate-related files generated after this step may have an `_experimental` suffix (e.g., `ranked_therapeutic_candidates_experimental.csv`, `therapeutic_candidate_detailed_hypotheses_experimental/`). - + - Folders for detailed hypotheses and literature reviews for both experimental assays and therapeutic candidates (e.g., `experimental_assay_detailed_hypotheses/`, `therapeutic_candidate_literature_reviews/`). + - CSV files for ranking results and final ranked lists (e.g., `experimental_assay_ranking_results.csv`, `ranked_therapeutic_candidates.csv`). + - Text summaries for proposed assays and candidates (e.g., `experimental_assay_summary.txt`, `therapeutic_candidates_summary.txt`). + - If the optional data analysis step is run (using the `data_analysis` function), there will be an additional `data_analysis/` subfolder containing outputs from the Finch agent (e.g., `consensus_results.csv`). Correspondingly, some therapeutic candidate-related files generated after this step may have an `_experimental` suffix (e.g., `ranked_therapeutic_candidates_experimental.csv`, `therapeutic_candidate_detailed_hypotheses_experimental/`). ### Overview of `examples` Folder: The `examples` folder provides practical usage demonstrations of pre-generated output directories from complete Robin runs for 10 diseases: -* Age-Related Hearing Loss -* Celiac Disease -* Charcot-Marie-Tooth Disease -* Chronic Kidney Disease -* Friedreich's Ataxia -* Glaucoma -* Idiopathic Pulmonary Fibrosis -* Non-alcoholic Steatohepatitis -* Polycystic Ovary Syndrome -* Sarcopenia + +- Age-Related Hearing Loss +- Celiac Disease +- Charcot-Marie-Tooth Disease +- Chronic Kidney Disease +- Friedreich's Ataxia +- Glaucoma +- Idiopathic Pulmonary Fibrosis +- Non-alcoholic Steatohepatitis +- Polycystic Ovary Syndrome +- Sarcopenia Each disease-specific subfolder mirrors the exact file and directory structure a user would obtain in their own `robin_output/` directory after a run: -* `experimental_assay_detailed_hypotheses/`: Text files containing detailed reports for each proposed experimental assay. -* `experimental_assay_literature_reviews/`: Text files of literature reviews generated from queries related to assay development. -* `experimental_assay_ranking_results.csv`: CSV file showing pairwise comparison results for assay ranking. -* `experimental_assay_summary.txt`: A textual summary of the proposed experimental assays. -* `ranked_therapeutic_candidates.csv`: CSV file listing the final ranked therapeutic candidates and their strength scores. -* `therapeutic_candidate_detailed_hypotheses/`: Text files with detailed reports for each proposed therapeutic candidate. -* `therapeutic_candidate_literature_reviews/`: Text files of literature reviews for therapeutic candidate queries. -* `therapeutic_candidate_ranking_results.csv`: CSV file of pairwise comparison results for candidate ranking. -* `therapeutic_candidates_summary.txt`: A textual summary of the proposed therapeutic candidates. + +- `experimental_assay_detailed_hypotheses/`: Text files containing detailed reports for each proposed experimental assay. +- `experimental_assay_literature_reviews/`: Text files of literature reviews generated from queries related to assay development. +- `experimental_assay_ranking_results.csv`: CSV file showing pairwise comparison results for assay ranking. +- `experimental_assay_summary.txt`: A textual summary of the proposed experimental assays. +- `ranked_therapeutic_candidates.csv`: CSV file listing the final ranked therapeutic candidates and their strength scores. +- `therapeutic_candidate_detailed_hypotheses/`: Text files with detailed reports for each proposed therapeutic candidate. +- `therapeutic_candidate_literature_reviews/`: Text files of literature reviews for therapeutic candidate queries. +- `therapeutic_candidate_ranking_results.csv`: CSV file of pairwise comparison results for candidate ranking. +- `therapeutic_candidates_summary.txt`: A textual summary of the proposed therapeutic candidates. These example outputs are provided to help users to understand the depth, format, and typical errors seen in Robin runs across various diseases. From c2357f93f69ecfd595f49f59854c14e5ac538c41 Mon Sep 17 00:00:00 2001 From: changbenjamin Date: Fri, 30 May 2025 13:26:48 -0700 Subject: [PATCH 3/3] updated the hierarchy of README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f57e879..74dbbec 100644 --- a/README.md +++ b/README.md @@ -101,7 +101,7 @@ See our [blog](https://www.futurehouse.org/research-announcements/demonstrating- - Text summaries for proposed assays and candidates (e.g., `experimental_assay_summary.txt`, `therapeutic_candidates_summary.txt`). - If the optional data analysis step is run (using the `data_analysis` function), there will be an additional `data_analysis/` subfolder containing outputs from the Finch agent (e.g., `consensus_results.csv`). Correspondingly, some therapeutic candidate-related files generated after this step may have an `_experimental` suffix (e.g., `ranked_therapeutic_candidates_experimental.csv`, `therapeutic_candidate_detailed_hypotheses_experimental/`). -### Overview of `examples` Folder: +## Overview of `examples` Folder: The `examples` folder provides practical usage demonstrations of pre-generated output directories from complete Robin runs for 10 diseases: