{"id":27977344,"url":"https://github.com/baranzinilab/spoke_genelab","last_synced_at":"2025-05-08T01:48:27.132Z","repository":{"id":289030672,"uuid":"732162579","full_name":"BaranziniLab/spoke_genelab","owner":"BaranziniLab","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-28T21:28:21.000Z","size":77409,"stargazers_count":4,"open_issues_count":0,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-08T01:48:21.160Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BaranziniLab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-15T20:00:57.000Z","updated_at":"2025-05-02T07:37:50.000Z","dependencies_parsed_at":"2025-04-28T22:35:08.837Z","dependency_job_id":null,"html_url":"https://github.com/BaranziniLab/spoke_genelab","commit_stats":null,"previous_names":["baranzinilab/spoke_genelab"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranziniLab%2Fspoke_genelab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranziniLab%2Fspoke_genelab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranziniLab%2Fspoke_genelab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BaranziniLab%2Fspoke_genelab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BaranziniLab","download_url":"https://codeload.github.com/BaranziniLab/spoke_genelab/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252983735,"owners_count":21835762,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-08T01:48:26.568Z","updated_at":"2025-05-08T01:48:27.092Z","avatar_url":"https://github.com/BaranziniLab.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NASA SPOKE-GeneLab Knowledge Graph\n\nThis repository contains the code and metadata needed to build a **Knowledge Graph (KG)** for [NASA GeneLab](https://www.nasa.gov/osdr-genelab-about/) omics datasets hosted on the [Open Science Data Repository (OSDR)](https://osdr.nasa.gov/bio/repo/search?q=\u0026data_source=cgene,alsda\u0026data_type=study).\n\n---\n\n## 🚀 Features\n\n- **Automated graph construction** from datasets in the OSDR\n- **Incremental update** for new datasets\n- **Statistical filtering** of results for significance\n- **Species selection** via a configurable whitelist\n- **Versioned metadata** for reproducibility (v0.0.3)\n- **Federated query** using Neo4j Fabric with the [Scalable Precision Medicine Open Knowledge Engine (SPOKE) KG](https://spoke.ucsf.edu/)\n\n---\n\n## 🧪 Supported Data Types\n\n| Measurement                  | Technology                                              | Property         | Selection Criteria |\n| ---------------------------- | ------------------------------------------------------- | -----------------|-----------------|\n| Transcription profiling      | RNA Sequencing (RNA‑Seq)                                | Log2 fold change | Adjusted p-value \u003c= 0.05 |\n| Transcription profiling      | DNA microarray                                          | Log2 fold change | Adjusted p-value \u003c= 0.05 |\n| DNA methylation profiling    | Whole Genome Bisulfite Sequencing                       | Methylation difference % | q-value \u003c= 0.05 |\n| DNA methylation profiling    | Reduced‑Representation Bisulfite Sequencing (RRBS)      | Methylation difference % | q-value \u003c= 0.05 |\n\n---\n\n## ⚙️ How It Works\n\n1. **Fetch** omics study records using the OSDR API  \n2. **Filter** datasets by statistical thresholds and target species  \n3. **Map** model organism genes to human genes\n4. **Map** cell and tissue types to the [Cell (CL)](https://bioportal.bioontology.org/ontologies/CL) and [Uber Anatomy Ontology (UBERON)](https://bioportal.bioontology.org/ontologies/UBERON) ontology, respectively \n5. **Export** CSV files for graph database upload\n6. **Import** CSV files into a Neo4j Graph database\n\n---\n\n## 🕸️ Graph Schema\n\n![Simplified Graph Schema](docs/spoke-genelab-v0.0.3-simplified.png)\n\n**Figure**: Schematic overview of the GeneLab knowledge graph structure, highlighting key node types (circles) and relationships (arrows).\n\nThe `Assay–MEASURED–MGene` relationship encodes Log₂ fold changes derived from transcription profiling assays, while the `Assay–MEASURED–MethylationRegion` relationship captures methylation differences identified through DNA methylation assays. The `MGene–METHYLATED_IN–MethylationRegion` relationship links model organism genes (`MGene`) to 1,000 base pair genomic regions (`MethylationRegion`) exhibiting differential methylation.\n\nProxy nodes (shown in gray) represent standardized identifiers for human genes (ENTREZ ID), anatomical structures (UBERON ID), and cell types (CL ID), enabling integration with external Neo4j databases and supporting composite graph database construction.\n\nDiagram generated using [arrows.app](https://arrows.app).\n\n---\n\n## 📁 Metadata Directory Structure\n\nThe following node and relationship metadata files define the graph schema.\n\n- **Nodes**  \n  [kg/v0.0.3/metadata/nodes/](kg/v0.0.3/metadata/nodes/)\n\n- **Relationships**   \n  [kg/v0.0.3/metadata/relationships/](kg/v0.0.3/metadata/relationships/)\n\nThe organization and conventions for defining the metadata and data are described in the [kg-import](https://github.com/sbl-sdsc/kg-import) Git repository.\n\n---\n\n## 🔗 SPOKE - GeneLab Composite Database\n\n![](docs/spoke-genlab-v0.0.3-composite.png)\n\n**Figure**: Integration of the SPOKE and GeneLab knowledge graphs using proxy nodes.  \nThe **GeneLab** graph (right), a knowledge graph representing spaceflight omics datasets, depicts key experimental entities: `Assay`, `Study`, `Mission`, `MGene`, and `MethylationRegion`, along with their relationships. \n**Proxy nodes** (gray) represent external identifiers (ENTREZ, UBERON, CL) and enable linkage to the **[SPOKE](https://spoke.ucsf.edu/)** graph (left), a rich biomedical knowledge graph comprising biological processes, molecular functions, diseases, compounds, and more. The dashed lines indicate mappings to enable the construction of a [composite Neo4j graph database](https://neo4j.com/docs/operations-manual/current/tutorial/tutorial-composite-database/). The composite graph enables federated queries across multiple KGs.\n\n---\n\n## ⚙️ Data Import Into Neo4j Knowledge Graph\n\n### Setup Neo4j Desktop\n\n1. Download the Neo4j Desktop application from the [Neo4j Download Center](https://neo4j.com/download-center/#desktop) and follow the installation instructions.\n\n2. When the installation is complete, Neo4j Desktop will launch. Click the `New` button to create a new project.\n\n![](docs/new_project.png)\n\n3. Hover the cursor over the created project, click the edit button, and change the project name from `Project` to `spoke-genelab`.\n\n![](docs/rename_project.png)\n\n4. Click the `ADD` button and select `Local DBMS`. **Select Neo4j version 5.23.0.**\n\n![](docs/add_graph_dbms.png)\n\n5. Enter the password `neo4jdemo` and click `Create`.\n    \n![](docs/create_dbms.png)\n    \n6. Select `Terminal` to open a terminal window.\n    \n![](docs/open_terminal.png)\n\n7. Type `pwd` in the terminal window to show the path to the `NEO4J_INSTALL_PATH` directory. This path is required in the `.env` file, see the next section.\n \n![](docs/get_path.png)\n\n\n------\n\n### Setup the Environment\n\nPrerequisites: Miniconda3 (light-weight, preferred) or Anaconda3 and Mamba (faster than Conda)\n\n* Install [Miniconda3](https://docs.conda.io/en/latest/miniconda.html)\n* Update an existing miniconda3 installation: ```conda update conda```\n* Install Mamba: ```conda install mamba -n base -c conda-forge```\n* Install Git (if not installed): ```conda install git -n base -c anaconda```\n------\n\n1. Clone this Repository\n\n```\ngit clone https://github.com/BaranziniLab/spoke_genelab.git\ncd spoke_genelab\n```\n\n2. Create a Conda environment\n\nThe file `environment.yml` specifies the Python version and all required dependencies.\n\n```\nmamba env create -f environment.yml\n```\n\n3. Create an account in [BioPortal](https://bioportal.bioontology.org/) and copy the API key. BioPortal is used to map terms to ontologies.\n\n   \n4. Copy the file `env_template` to `.env`\n\n5. Edit the file `.env` and set the following variables\n\nKG version number\n\n`KG_VERSION=v0.0.3`\n\nPath to the cloned git repository\n\n`KG_GIT=/Users/.../spoke_genelab/`\n\nPath to the Neo4J instance in Neo4j Desktop (in quotes). Make sure to enclose the path in quotes.\n\n`NEO4J_INSTALL_PATH=\"/Users/.../Library/Application Support/Neo4j Desktop/Application/relate-data/dbmss/dbms-3d4b95d1-0219-480b-a3c4-ee5a409cc383\"`\n\nBioPortal API Key\n\n`BIOPORTAL_API_KEY=\u003cbioportal api key\u003e`\n\n------\n\n### Download and Process Datasets and upload to Neo4J Graph Database\n\n1. Start the spoke-genelab Graph DBMS\n\n![](docs/start_dbms.png)\n\n2. Activate the conda environment\n\n```\nconda activate spoke-genelab\n```\n\n3. Launch Jupyter Lab\n\n```\njupyter lab\n```\n\n4. Navigate to the `notebooks` directory and run the following notebooks\n\n| Notebook                   |   Description           |\n|----------------------------|-------------------------|\n| 1_download_datasets.ipynb  | Downloads datasets     |\n| 2_create_study_mission_nodes.ipynb | Creates Study and Mission nodes and their relationships |\n| 3_create_gene_nodes.ipynb  | Creates MGene (model organism) and mapped Gene (human) gene nodes |\n| 4_create_assay_nodes.ipynb | Creates Assay nodes and their relationships |\n| 5_import_to_neo4j.ipynb    | Imports the formatted data into a Neo4j KG |\n| 6_query_examples.ipynb     | Runs example queries (optional) |\n\n5. When the import is completed, click the `Refresh` button in Neo4j Desktop. The newly created database `spoke-genelab-v0.0.3` will be listed.\n\n![](docs/db_imported.png)\n\n6. Click the `Open` button to launch the database.\n\n![](docs/open_dbms.png)\n\n7. Click on the database icon on the left.\n\n![](docs/select_db_icon.png)\n\n8. Use the pull-down menu to select a version of `spoke-genelab-v0.0.3` database. Wait for about 30+ seconds until the database is loaded and the nodes are listed as shown below.\n   \n![](docs/db_ready.png)\n\n9. Set the Graph Stylesheet\n\nDrag the file kg/v0.0.3/style.grass onto the Neo4j Browser window to set the node colors, sizes, and labels.\n\n10. Now you are ready to run Cypher queries on the selected database.\n\n11. When you are finished, stop the database in the Neo4j Desktop.\n\nTo stop the conda environment, type\n\n```conda deactivate```\n\n------\n\n### Dump Neo4J Graph Database\n1. Stop the database\n\n2. Hover the cursor over the `spoke-genelab-v0.0.3` database and select `Dump` from the menu.\n\n![](docs/dump_db.png)\n\n3. When the dump is complete, click the `Reveal files in Finder` button to open the directory that contains the `spoke-genelab-v0.0.3.dump` file.\n\n![](docs/dump_location.png)\n\nThis database dump will be used to create the SPOKE-GeneLab composite database.\n\n------\n\n## 📚 Citation\n\nPW Rose, CA Nelson, SG Gebre, K Soman, KA Grigorev, LM Sanders, SV Costes, SE Baranzini, NASA SPOKE-GeneLab Knowledge Graph. Available online: https://github.com/BaranziniLab/spoke_genelab (2025)\n\nCA Nelson, PW Rose, K Soman, LM Sanders, SG Gebre, SV Costes, SE Baranzini, Nasa Genelab-Knowledge Graph Fabric Enables Deep Biomedical Analysis of Multi-Omics Datasets, https://ntrs.nasa.gov/citations/20250000723 (2025)\n\n------\n\n## 💰 Funding\nNSF Award number [2333819](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2333819), Proto-OKN Theme 1: Connecting Biomedical information on Earth and in Space via the SPOKE knowledge graph.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaranzinilab%2Fspoke_genelab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbaranzinilab%2Fspoke_genelab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbaranzinilab%2Fspoke_genelab/lists"}