diff --git a/.python-version b/.python-version new file mode 100644 index 000000000..56d91d353 --- /dev/null +++ b/.python-version @@ -0,0 +1 @@ +3.10.12 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 000000000..0d161072e --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team representative, info@monarchinitiative.org. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..a04dfab48 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Welcome to the Monarch Initiative + +The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. While we have a core development team, we welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. + +# Table of Contents + +- [Useful Links](#important-links) +- [Community Guidelines](#community-guidelines) +- [Monarch App](#monarch-app) + - [Requirements](#requirements) + - [Backend Requirements](#backend-requirements) + - [Frontend Requirements](#frontend-requirements) + - [Other Requirements](#other-requirements) + - [Getting Started](#getting-started) + - [Makefile](#makefile) + - [Quick Start](#quick-start) +- [Testing and Development](#testing-and-development) + - [Backend](#backend) + - [Frontend](#frontend) +- [Deploying Monarch](#deploying-monarch) + +# Useful Links + +- [Monarch Documentation](https://monarch-initiative.github.io/monarch-documentation/) - In addition to the documentation here, we have a separate documentation site that is automatically generated from the codebase, which encompasses the entire Monarch Initiative ecosystem, as well as the release process and other important information. +- [Monarch Py Documentation](https://monarch-initiative.github.io/monarch-app/) - The Monarch Py documentation contains information on the Python library for interacting with the Monarch Initiative knowledge graph, as well as the FastAPI module that serves as the website's backend. +- [Monarch App Website](https://next.monarchinitiative.org/) - The Monarch Initiative website, a Vue web app using `monarch-py` as the backend. + +# Community Guidelines + +We welcome you to our community! We seek to provide a welcoming and safe development experience for everyone. Please read our [code of conduct](CODE_OF_CONDUCT.md) and reach out to us if you have any questions. We welcome your input! + +# Monarch App + +[![documentation](https://img.shields.io/badge/-Documentation-purple?logo=read-the-docs&logoColor=white&style=for-the-badge)](https://monarch-initiative.github.io/monarch-documentation/) + +[**⭐️⭐️ View the website ⭐️⭐️**](https://next.monarchinitiative.org/) + +The monarch-app repository is a monorepo that contains the projects necessary to build and run the web app at monarchinitiative.org and the appropriate tooling and developer resources to continue development. The frontend for the Monarch Initiative website is a javascript/typescript webapp developed using the Vue toolkit. The backend, also referred to as `monarch-py`, is a Python library for interacting with the Monarch Initiative knowledge graph. The `monarch-py` backend also includes an optional FastAPI module that serves as the website's backend and related services for enabling the frontend. + +## Requirements + +The Monarch Initiative website tool chain has a few requirements that you may need to install before we are ready to work on testing or development. Here is the list of requirements and what they are used for. If you are only working on a portion of the code-base you may not need all of the tools below. + +### Backend Requirements + +- Python - Most of us use Python version 3.10.12 for development and try to be compatible with versions 3.9-3.12. +- [Poetry](https://python-poetry.org/docs/#installation) - We use Poetry to manage dependencies in `monarch-py` +- [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) (suggested) - I recommend using pyenv to manage your Python version within different projects + +### Frontend Requirements + +- [Bun](https://bun.sh/docs/installation) - Bun is used as a drop-in replacement for Node (non-browser JavaScript runtime environment) and Yarn (package manager). If you already have Node.js installed you Bun will not conflict with your Node.js environment and can be installed as a module. The frontend/CONTRIBUTING.md has simple instructions on how to install Bun. + +### Other Requirements + +- Docker - Image files used for development and testing for both frontend and backend (required for Solr) +- Rust (cargo) - Required for running the semsimian server locally + +## Getting Started + +To get started with development in monarch-app clone the repo and navigate to the directory. + +```shell +git clone git@github.com:monarch-initiative/monarch-app.git +cd monarch-app +``` + +In order to maintain a clean system environment you may want to create a local python environment. I also recommend setting a local python version of 3.10 with pyenv. You can do both with the following commands. + +```shell +pyenv install 3.10.12 +pyenv local 3.10.12 +python -m venv .venv +``` + +When the new virtual environment is created, you may want to do some peronal modifications to the envoronment. I edit the `activate` script to name the virtual environment more meaningfully and also install `poetry` locally (my preference, `activate` then run `pip install poetry`). After the virtual environment is set up you will want to start it before each development session by running `activate` (or in your IDE). To exit the environment run `deactivate`. + +### Makefile + +The monarch-app repo uses a Makefile system to facilitate and simplify some of the development setup and deployment tasks. For detailed information on the build targets and details of implementation please refer to the [Makefile](Makefile) in the monarch-app directory. + +### Quick Start +For a quick-start, once the requirements above are met you can install and launch a working local version of the Monarch App with the following commands. + +```shell +cd monarch-app +make install +monarch solr download +monarch solr start +cd frontend +bun run dev +``` + +Once these commands are run you should have a working version of the Monarch App running from your local system. +_Note_: You may have to resolve some permissions issues with solr in order to download and start monarch solr. + +# Testing and Development + +## Backend + +For detailed information the backend please refer to the [README.md](./backend/README.md) and [CONTRIBUTING.md](./backend/CONTRIBUTING.md) file in the backend directory. Additional information can be find in the [documentation](https://monarch-app.monarchinitiative.org) + +## Frontend + +More detailed information on frontend development and run options can be found at the [frontend README.md](./frontend/README.md) and [CONTRIBUTING.md](./frontend/CONTRIBUTING.md) files in the frontend directory. Additional information can be found in the [documentation](https://monarch-app.monarchinitiative.org) + +# Deploying to Monarch + +For documentation on deploying to monarch please see the [Monarch documentation](https://monarch-initiative.github.io/monarch-documentation/release-process/) regarding the release process. diff --git a/README.md b/README.md index ce0877c17..305efdffb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,11 @@ -# Monarch App +# Welcome to the Monarch Initiative + +The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. + +We welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. To help get started on contributing to the Monarch Initiative, please see our CONTRIBUTING.md file. -[![documentation](https://img.shields.io/badge/-Documentation-purple?logo=read-the-docs&logoColor=white&style=for-the-badge)](https://monarch-initiative.github.io/monarch-app/docs) +# Monarch App +[![documentation](https://img.shields.io/badge/-Documentation-purple?logo=read-the-docs&logoColor=white&style=for-the-badge)](https://monarch-initiative.github.io/monarch-documentation/) ![](https://github.com/monarch-initiative/monarch-app/actions/workflows/test-backend.yaml/badge.svg) ![](https://github.com/monarch-initiative/monarch-app/actions/workflows/test-frontend.yaml/badge.svg) ![](https://github.com/monarch-initiative/monarch-app/actions/workflows/deploy-documentation.yaml/badge.svg) @@ -8,18 +13,14 @@ [**⭐️⭐️ View the website ⭐️⭐️**](https://next.monarchinitiative.org/) -This repository contains the source code for the Monarch Initiative website (a Vue webapp), -as well as `monarch-py`, a Python library for interacting with the Monarch Initiative knowledge graph, -which includes an optional FastAPI module that serves as the website's backend. +The monarch-app repo contains the source code for the Monarch Initiative website (a Vue webapp), +as well as `monarch-py`, a Python library for interacting with the Monarch Initiative knowledge graph. The `monarch-py` library also includes a FastAPI module that serves as the website's backend. Together, the frontend and backend make up the stack used to deply and run the Monarch Initiative website. +If you wish to run Monarch-App as a local web application, please install the requirements below and then follow on to the usage section to start the application. Refer to [Using Local Data](#using-local-data) to see how you can run the full Monarch website locally and use your own data store. -### For developers -To get started with this repo: +### For developers -``` -git clone https://github.com/monarch-initiative/monarch-app -cd monarch-app -``` +The monarch-app repository contains the code to run the Monarch Initiative website in the `frontend` and `backend` directories as well as documentation, helper scripts, Docker files and services to help set up a local environment for development and for deployment. -Then see `Makefile` or the individual `/frontend` and `/backend` folders for how you can install, develop, build, test, lint, or format the frontend or backend. +To start development, please refer to the CONTRIBUTING.md document with this README. If you are planning to only develop the frontend or backend of the application you can refer directly to the README and CONTRIBUTING files in each of those sections. diff --git a/backend/CONTRIBUTING.md b/backend/CONTRIBUTING.md new file mode 100644 index 000000000..c431ff2c5 --- /dev/null +++ b/backend/CONTRIBUTING.md @@ -0,0 +1,37 @@ +# Welcome to the Monarch Initiative + +The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. While we have a core development team, we welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. + +This CONTRIBUTING.md is for the monarch-app backend, also refered to as monarch-py, usable as either a python module or a local CLI. + +# Useful Links + +- [Monarch Documentation](https://monarch-initiative.github.io/monarch-documentation/) - In addition to the documentation here, we have a separate documentation site that is automatically generated from the codebase, which encompasses the entire Monarch Initiative ecosystem, as well as the release process and other important information. +- [Monarch Py Documentation](https://monarch-initiative.github.io/monarch-app/) - The Monarch Py documentation contains information on the Python library for interacting with the Monarch Initiative knowledge graph, as well as the FastAPI module that serves as the website's backend. +- [Monarch App Website](https://next.monarchinitiative.org/) - The Monarch Initiative website, a Vue web app using `monarch-py` as the backend. + +### Running the API: + +#### Local development: + +- Connect to and expose the SOLR database: + `gcloud compute ssh monarch-solr-dev -- -L 8983:localhost:8983` + +- Start the uvicorn server: + `cd /monarch-api && uvicorn main:app --reload` + +#### GCP deployment: + +- First, connect to the GCP SOLR machine: + `gcloud compute ssh monarch-api-dev -- -L 8000:localhost:8000` + +- Then, start the uvicorn server: + `nohup uvicorn main:app --reload --host 0.0.0.0 &` + +#### Building and using the Docker image: + +- Build the docker image: + `docker build --rm --tag us-central1-docker.pkg.dev/monarch-initiative/monarch-api/monarch-api:{VERSION} . ` + +- Push the docker image: + `docker push us-central1-docker.pkg.dev/monarch-initiative/monarch-api/monarch-api:{VERSION}` diff --git a/backend/README.md b/backend/README.md index 35177cd63..95f62f136 100644 --- a/backend/README.md +++ b/backend/README.md @@ -2,10 +2,78 @@ [![documentation](https://img.shields.io/badge/-Documentation-purple?logo=read-the-docs&logoColor=white&style=for-the-badge)](https://monarch-initiative.github.io/monarch-app) -Monarch-Py is a Python library for interfacing with the Monarch Initiative Knowledge graph. -It can be used from CLI, as a module, or as a FastAPI app +Monarch-Py is a Python library for interfacing with the Monarch Initiative Knowledge graph. The monarch-py package can be used from CLI, as a module, or as a FastAPI app. +# Requirements +If you are running the whole monarch-app suite locally you will want to review the [README.md](../README.md) or [CONTRIBUTING.md](../CONTRIBUTING.md) files in the repository root for information on the requirements for monarch-app at large. If you intend to run just the backend for end-user usage or testing you will only need the following prerequisites. + +- Python version 3.9+, version 3.10.12 recommended for development. +- [Poetry](https://python-poetry.org/docs/#installation) - For managing dependencies in monarch-py. +- [Docker](https://docs.docker.com/get-docker/) - For running the Solr instance locally. +- [Rust](https://www.rust-lang.org/tools/install) - For running the semsimian server locally. + +For development of monarch-py, please refer to the [backend/CONTRUBUTING.md](CONTRIBUTING.md) for additional details. + +# Usage + +Basic installation can be performed using pip/pipx or your favorite package manager. + +``` +pip install monarch-py +``` + +The monarch-py module and CLI use the Monarch-KG using a Solr instance running locally. +This requires Docker to be installed and running on your computer. + +``` +monarch solr download +monarch solr start +``` + +This will download and then run the monarch Solr image locally on port 8983. +*Note* You may need to change permissions on the file in order to install and run the Solr container. + +``` +sudo chgrp -R 8983 ~/.data/monarch +sudo chmod -R g+w ~/.data/monarch +``` + +To check if Solr is running correctly on your computer you can check you can check using Docker or the monarch CLI. + +Using Docker: + +``` +docker ps +``` + +For docker you should see output resembling this: + +``` +66da4aeed48e solr:8 "docker-entrypoint.s…" 3 weeks ago Up 5 days 0.0.0.0:8983->8983/tcp, :::8983->8983/tcp monarch_solr +``` + +Using the monarch CLI: + +``` +monarch solr status +``` + +For the monarch CLI you should see output similar to this: + +``` +Checking for Solr container... + +Found monarch_solr container: 66da4aeed48e7f71241f85f31f1e3366f9255cb53b78f16b13fb79bcfb2b36f2 +Container status: running +``` + +monarch-ingest creates it's own Solr docker instance which mounts its own data output from closurizer and makes it's own Solr artifact. + +# Developers + +For instructions on how to test monarch-py locally or how to start with developing please see the [CONTRIBUTING.md](../CONTRIBUTING.md) file in the root of the Monarch-App repository. +For instructions specific to monarch-py (the Monarch-App backend), see the [backend/CONTRIBUTING.md](./CONTRIBUTING.md) file. ## For Developers diff --git a/backend/src/monarch_py/datamodels/model.py b/backend/src/monarch_py/datamodels/model.py index a83be9820..af1733324 100644 --- a/backend/src/monarch_py/datamodels/model.py +++ b/backend/src/monarch_py/datamodels/model.py @@ -183,6 +183,16 @@ class Association(ConfiguredBaseModel): ) +class AssociationCountList(ConfiguredBaseModel): + """ + Container class for a list of association counts + """ + + items: List[AssociationCount] = Field( + default_factory=list, description="""A collection of items, with the type to be overriden by slot_usage""" + ) + + class CompactAssociation(ConfiguredBaseModel): category: Optional[str] = Field(None) @@ -194,16 +204,6 @@ class CompactAssociation(ConfiguredBaseModel): negated: Optional[bool] = Field(None) -class AssociationCountList(ConfiguredBaseModel): - """ - Container class for a list of association counts - """ - - items: List[AssociationCount] = Field( - default_factory=list, description="""A collection of items, with the type to be overriden by slot_usage""" - ) - - class AssociationTypeMapping(ConfiguredBaseModel): """ A data class to hold the necessary information to produce association type counts for given entities with appropriate directional labels @@ -780,8 +780,8 @@ class SemsimSearchResult(ConfiguredBaseModel): # Model rebuild # see https://pydantic-docs.helpmanual.io/usage/models/#rebuilding-a-model Association.model_rebuild() -CompactAssociation.model_rebuild() AssociationCountList.model_rebuild() +CompactAssociation.model_rebuild() AssociationTypeMapping.model_rebuild() DirectionalAssociation.model_rebuild() ExpandedCurie.model_rebuild() diff --git a/docs/FastAPI/index.md b/docs/FastAPI/index.md index 0af3f7df5..ccea8d3b3 100644 --- a/docs/FastAPI/index.md +++ b/docs/FastAPI/index.md @@ -1,20 +1,19 @@ # Monarch-Py FastAPI -An optional FastAPI is also available for browsing the knowledge graph produced by the Monarch Initiative, which wraps the `monarch-py` library. +A FastAPI is also available for browsing the knowledge graph produced by the Monarch Initiative, which wraps the `monarch-py` library. -It can be installed as an extra of `monarch-py` via pip or pipx: -```bash -pip|pipx install monarch-py[api] -``` +It is included automatically as part of `monarch-py` when installed via pip or pipx. ## Running the API Server -A local development server can be started with the command: +A local development server can be started with the command: + ```bash monarch-api ``` or using `uvicorn`: + ```bash # Using uvicorn directly: poetry run uvicorn src.monarch_py.api.main:app --reload @@ -29,9 +28,8 @@ The API is then available at `http://127.0.0.1:8000/v3/api`. Swagger documentation is available at `http://127.0.0.1:8000/v3/docs`, and a ReDoc interface at `http://127.0.0.1:8000/v3/redoc`. -## Documentation +## Documentation [API Reference](./Endpoints/index.md) [Data Response Model](../Data-Model/index.md) - diff --git a/docs/Usage/CLI.md b/docs/Usage/CLI.md index aebcdc956..e42a3d41a 100644 --- a/docs/Usage/CLI.md +++ b/docs/Usage/CLI.md @@ -21,9 +21,10 @@ $ monarch [OPTIONS] COMMAND [ARGS]... * `association-table` * `associations`: Paginate through associations * `autocomplete`: Return entity autcomplete matches for a... -* `compare`: Compare two entities using semantic... +* `compare`: Compare two sets of phenotypes using... * `entity`: Retrieve an entity by ID * `histopheno`: Retrieve the histopheno data for an entity... +* `mappings` * `multi-entity-associations`: Paginate through associations for multiple... * `schema`: Print the linkml schema for the data model * `search`: Search for entities @@ -56,7 +57,7 @@ $ monarch association-counts [OPTIONS] [ENTITY] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch association-table` @@ -64,21 +65,23 @@ $ monarch association-counts [OPTIONS] [ENTITY] **Usage**: ```console -$ monarch association-table [OPTIONS] ENTITY CATEGORY +$ monarch association-table [OPTIONS] ENTITY CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation} ``` **Arguments**: * `ENTITY`: The entity to get associations for [required] -* `CATEGORY`: The association category to get associations for, ex. biolink:GeneToPhenotypicFeatureAssociation [required] +* `CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation}`: The association category to get associations for, ex. biolink:GeneToPhenotypicFeatureAssociation [required] **Options**: * `-q, --query TEXT` +* `-t, --traverse-orthologs`: Whether to traverse orthologs when getting associations +* `-s, --sort TEXT` * `-l, --limit INTEGER`: [default: 5] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch associations` @@ -105,12 +108,13 @@ $ monarch associations [OPTIONS] **Options**: -* `-c, --category TEXT`: Comma-separated list of categories -* `-s, --subject TEXT`: Comma-separated list of subjects -* `-p, --predicate TEXT`: Comma-separated list of predicates -* `-o, --object TEXT`: Comma-separated list of objects -* `-e, --entity TEXT`: Comma-separated list of entities +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation]`: Category to get associations for +* `-s, --subject TEXT`: Subject ID to get associations for +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:related_to|biolink:active_in|biolink:part_of|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:gene_associated_with_condition|biolink:contributes_to|biolink:causes|biolink:colocalizes_with|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_negative_effect|biolink:acts_upstream_of_negative_effect]`: Predicate ID to get associations for +* `-o, --object TEXT`: Object ID to get associations for +* `-e, --entity TEXT`: Entity (subject or object) ID to get associations for * `-d, --direct`: Whether to exclude associations with subject/object as ancestors +* `-C, --compact`: Whether to return a compact representation of the associations * `-l, --limit INTEGER`: The number of associations to return [default: 20] * `--offset INTEGER`: The offset of the first association to be retrieved [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] @@ -139,12 +143,12 @@ $ monarch autocomplete [OPTIONS] [Q] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch compare` -Compare two entities using semantic similarity via OAK +Compare two sets of phenotypes using semantic similarity via SemSimian **Usage**: @@ -160,7 +164,7 @@ $ monarch compare [OPTIONS] SUBJECTS OBJECTS **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch entity` @@ -186,7 +190,7 @@ $ monarch entity [OPTIONS] [ID] * `-e, --extra`: Include extra fields in the output (association_counts and node_hierarchy) * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch histopheno` @@ -213,7 +217,28 @@ $ monarch histopheno [OPTIONS] [SUBJECT] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file +* `--help`: Show this message and exit. + +## `monarch mappings` + +**Usage**: + +```console +$ monarch mappings [OPTIONS] +``` + +**Options**: + +* `-e, --entity-id TEXT`: entity ID to get mappings for +* `-s, --subject-id TEXT`: subject ID to get mappings for +* `-p, --predicate-id [skos:exactMatch|skos:closeMatch|skos:broadMatch|skos:narrowMatch]`: predicate ID to get mappings for +* `-o, --object-id TEXT`: object ID to get mappings for +* `-m, --mapping-justification TEXT`: mapping justification to get mappings for +* `--offset INTEGER`: The offset of the first mapping to be retrieved [default: 0] +* `-l, --limit INTEGER`: The number of mappings to return [default: 20] +* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch multi-entity-associations` @@ -241,7 +266,7 @@ $ monarch multi-entity-associations [OPTIONS] * `-l, --limit INTEGER`: [default: 20] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch schema` @@ -280,14 +305,14 @@ $ monarch search [OPTIONS] **Options**: * `-q, --query TEXT` -* `-c, --category TEXT` +* `-c, --category [biolink:Gene|biolink:PhenotypicFeature|biolink:BiologicalProcessOrActivity|biolink:GrossAnatomicalStructure|biolink:Disease|biolink:Pathway|biolink:Cell|biolink:NamedThing|biolink:AnatomicalEntity|biolink:CellularComponent|biolink:MolecularEntity|biolink:BiologicalProcess|biolink:MacromolecularComplex|biolink:MolecularActivity|biolink:Protein|biolink:CellularOrganism|biolink:PhenotypicQuality|biolink:Vertebrate|biolink:Virus|biolink:BehavioralFeature|biolink:LifeStage|biolink:PathologicalProcess|biolink:ChemicalEntity|biolink:Drug|biolink:OrganismTaxon|biolink:SequenceVariant|biolink:SmallMolecule|biolink:InformationContentEntity|biolink:NucleicAcidEntity|biolink:EvidenceType|biolink:GeographicExposure|biolink:RNAProduct|biolink:Transcript|biolink:Fungus|biolink:Plant|biolink:Dataset|biolink:Invertebrate|biolink:PopulationOfIndividualOrganisms|biolink:ProteinFamily|biolink:Activity|biolink:Agent|biolink:ChemicalExposure|biolink:ConfidenceLevel|biolink:EnvironmentalFeature|biolink:Exon|biolink:GeneticInheritance|biolink:Genome|biolink:Genotype|biolink:Haplotype|biolink:Human|biolink:IndividualOrganism|biolink:Mammal|biolink:MaterialSample|biolink:MicroRNA|biolink:Patent|biolink:ProteinDomain|biolink:Publication|biolink:RegulatoryRegion|biolink:Study|biolink:Treatment|biolink:WebPage|biolink:AccessibleDnaRegion|biolink:Article|biolink:Attribute|biolink:Bacterium|biolink:BiologicalEntity|biolink:BiologicalSex|biolink:CellLine|biolink:ChemicalMixture|biolink:CodingSequence|biolink:DatasetDistribution|biolink:DiagnosticAid|biolink:DrugExposure|biolink:EnvironmentalProcess|biolink:Event|biolink:GenotypicSex|biolink:NoncodingRNAProduct|biolink:OrganismalEntity|biolink:PhenotypicSex|biolink:Polypeptide|biolink:Procedure|biolink:ProcessedMaterial|biolink:ReagentTargetedGene|biolink:SiRNA|biolink:Snv|biolink:StudyVariable|biolink:TranscriptionFactorBindingSite|biolink:Zygosity]` * `-t, --in-taxon-label TEXT` * `-ff, --facet-fields TEXT` * `--facet-queries TEXT` * `-l, --limit INTEGER`: [default: 20] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ## `monarch solr` @@ -313,6 +338,7 @@ $ monarch solr [OPTIONS] COMMAND [ARGS]... * `download`: Download the Monarch Solr KG. * `entity`: Retrieve an entity by ID * `histopheno`: Retrieve the histopheno associations for a... +* `mappings` * `multi-entity-associations`: Paginate through associations for multiple... * `search`: Search for entities * `start`: Starts a local Solr container. @@ -343,7 +369,7 @@ $ monarch solr association-counts [OPTIONS] [ENTITY] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr association-table` @@ -351,21 +377,23 @@ $ monarch solr association-counts [OPTIONS] [ENTITY] **Usage**: ```console -$ monarch solr association-table [OPTIONS] ENTITY CATEGORY +$ monarch solr association-table [OPTIONS] ENTITY [CATEGORY]:[biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation] ``` **Arguments**: * `ENTITY`: The entity to get associations for [required] -* `CATEGORY`: The association category to get associations for, ex. biolink:GeneToPhenotypicFeatureAssociation [required] +* `[CATEGORY]:[biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation]`: The association category to get associations for, ex. biolink:GeneToPhenotypicFeatureAssociation **Options**: +* `-t, --traverse-orthologs`: Whether to traverse orthologs when getting associations * `-q, --query TEXT` +* `-s, --sort TEXT` * `-l, --limit INTEGER`: [default: 5] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr associations` @@ -373,16 +401,16 @@ $ monarch solr association-table [OPTIONS] ENTITY CATEGORY Paginate through associations Args: - category: A comma-separated list of categories - subject: A comma-separated list of subjects - predicate: A comma-separated list of predicates - object: A comma-separated list of objects - entity: A comma-separated list of entities - limit: The number of associations to return - direct: Whether to exclude associations with subject/object as ancestors + category: The category of the association (multi-valued) + subject: The subject of the association (multi-valued) + predicate: The predicate of the association (multi-valued) + object: The object of the association (multi-valued) + entity: The entity (subject or object) of the association (multi-valued) + limit: The number of associations to return (default 20) + direct: Whether to exclude associations with subject/object as ancestors (default False) offset: The offset of the first association to be retrieved - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) + fmt: The format of the output (json, yaml, tsv, table) (default json) + output: The path to the output file (stdout if not specified) (default None) **Usage**: @@ -392,16 +420,17 @@ $ monarch solr associations [OPTIONS] **Options**: -* `-c, --category TEXT`: Comma-separated list of categories -* `-s, --subject TEXT`: Comma-separated list of subjects -* `-p, --predicate TEXT`: Comma-separated list of predicates -* `-o, --object TEXT`: Comma-separated list of objects -* `-e, --entity TEXT`: Comma-separated list of entities +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation]`: Category to get associations for +* `-s, --subject TEXT`: Subject ID to get associations for +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:related_to|biolink:active_in|biolink:part_of|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:gene_associated_with_condition|biolink:contributes_to|biolink:causes|biolink:colocalizes_with|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_negative_effect|biolink:acts_upstream_of_negative_effect]`: Predicate ID to get associations for +* `-o, --object TEXT`: Object ID to get associations for +* `-e, --entity TEXT`: Entity (subject or object) ID to get associations for * `-d, --direct`: Whether to exclude associations with subject/object as ancestors +* `-C, --compact`: Whether to return a compact representation of the associations * `-l, --limit INTEGER`: The number of associations to return [default: 20] * `--offset INTEGER`: The offset of the first association to be retrieved [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr autocomplete` @@ -426,7 +455,7 @@ $ monarch solr autocomplete [OPTIONS] [Q] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr download` @@ -470,7 +499,7 @@ $ monarch solr entity [OPTIONS] [ID] * `-e, --extra`: Include extra fields in the output (association_counts and node_hierarchy) * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr histopheno` @@ -497,7 +526,28 @@ $ monarch solr histopheno [OPTIONS] [SUBJECT] **Options**: * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: JSON] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file +* `--help`: Show this message and exit. + +### `monarch solr mappings` + +**Usage**: + +```console +$ monarch solr mappings [OPTIONS] +``` + +**Options**: + +* `-e, --entity-id TEXT`: entity ID to get mappings for +* `-s, --subject-id TEXT`: subject ID to get mappings for +* `-p, --predicate-id [skos:exactMatch|skos:closeMatch|skos:broadMatch|skos:narrowMatch]`: predicate ID to get mappings for +* `-o, --object-id TEXT`: object ID to get mappings for +* `-m, --mapping-justification TEXT`: mapping justification to get mappings for +* `--offset INTEGER`: The offset of the first mapping to be retrieved [default: 0] +* `-l, --limit INTEGER`: The number of mappings to return [default: 20] +* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr multi-entity-associations` @@ -525,7 +575,7 @@ $ monarch solr multi-entity-associations [OPTIONS] * `-l, --limit INTEGER`: [default: 20] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr search` @@ -551,15 +601,15 @@ $ monarch solr search [OPTIONS] **Options**: -* `-q, --query TEXT` -* `-c, --category TEXT` +* `-q, --query TEXT`: [default: *:*] +* `-c, --category [biolink:Gene|biolink:PhenotypicFeature|biolink:BiologicalProcessOrActivity|biolink:GrossAnatomicalStructure|biolink:Disease|biolink:Pathway|biolink:Cell|biolink:NamedThing|biolink:AnatomicalEntity|biolink:CellularComponent|biolink:MolecularEntity|biolink:BiologicalProcess|biolink:MacromolecularComplex|biolink:MolecularActivity|biolink:Protein|biolink:CellularOrganism|biolink:PhenotypicQuality|biolink:Vertebrate|biolink:Virus|biolink:BehavioralFeature|biolink:LifeStage|biolink:PathologicalProcess|biolink:ChemicalEntity|biolink:Drug|biolink:OrganismTaxon|biolink:SequenceVariant|biolink:SmallMolecule|biolink:InformationContentEntity|biolink:NucleicAcidEntity|biolink:EvidenceType|biolink:GeographicExposure|biolink:RNAProduct|biolink:Transcript|biolink:Fungus|biolink:Plant|biolink:Dataset|biolink:Invertebrate|biolink:PopulationOfIndividualOrganisms|biolink:ProteinFamily|biolink:Activity|biolink:Agent|biolink:ChemicalExposure|biolink:ConfidenceLevel|biolink:EnvironmentalFeature|biolink:Exon|biolink:GeneticInheritance|biolink:Genome|biolink:Genotype|biolink:Haplotype|biolink:Human|biolink:IndividualOrganism|biolink:Mammal|biolink:MaterialSample|biolink:MicroRNA|biolink:Patent|biolink:ProteinDomain|biolink:Publication|biolink:RegulatoryRegion|biolink:Study|biolink:Treatment|biolink:WebPage|biolink:AccessibleDnaRegion|biolink:Article|biolink:Attribute|biolink:Bacterium|biolink:BiologicalEntity|biolink:BiologicalSex|biolink:CellLine|biolink:ChemicalMixture|biolink:CodingSequence|biolink:DatasetDistribution|biolink:DiagnosticAid|biolink:DrugExposure|biolink:EnvironmentalProcess|biolink:Event|biolink:GenotypicSex|biolink:NoncodingRNAProduct|biolink:OrganismalEntity|biolink:PhenotypicSex|biolink:Polypeptide|biolink:Procedure|biolink:ProcessedMaterial|biolink:ReagentTargetedGene|biolink:SiRNA|biolink:Snv|biolink:StudyVariable|biolink:TranscriptionFactorBindingSite|biolink:Zygosity]` * `-t, --in-taxon-label TEXT` * `-ff, --facet-fields TEXT` * `--facet-queries TEXT` * `-l, --limit INTEGER`: [default: 20] * `--offset INTEGER`: [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-O, --output TEXT`: The path to the output file * `--help`: Show this message and exit. ### `monarch solr start` @@ -634,6 +684,8 @@ Args: predicate: A comma-separated list of predicates object: A comma-separated list of objects entity: A comma-separated list of entities + direct: Whether to exclude associations with subject/object as ancestors + compact: Whether to return a compact representation of the associations limit: The number of associations to return offset: The offset of the first association to be retrieved fmt: The format of the output (json, yaml, tsv, table) @@ -647,12 +699,13 @@ $ monarch sql associations [OPTIONS] **Options**: -* `-c, --category TEXT`: Comma-separated list of categories -* `-s, --subject TEXT`: Comma-separated list of subjects -* `-p, --predicate TEXT`: Comma-separated list of predicates -* `-o, --object TEXT`: Comma-separated list of objects -* `-e, --entity TEXT`: Comma-separated list of entities +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:ChemicalToPathwayAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:CausalGeneToDiseaseAssociation]`: Category to get associations for +* `-s, --subject TEXT`: Subject ID to get associations for +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:related_to|biolink:active_in|biolink:part_of|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:gene_associated_with_condition|biolink:contributes_to|biolink:causes|biolink:colocalizes_with|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_negative_effect|biolink:acts_upstream_of_negative_effect]`: Predicate ID to get associations for +* `-o, --object TEXT`: Object ID to get associations for +* `-e, --entity TEXT`: Entity (subject or object) ID to get associations for * `-d, --direct`: Whether to exclude associations with subject/object as ancestors +* `-C, --compact`: Whether to return a compact representation of the associations * `-l, --limit INTEGER`: The number of associations to return [default: 20] * `--offset INTEGER`: The offset of the first association to be retrieved [default: 0] * `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] diff --git a/docs/index.md b/docs/index.md index c35ace0ca..5262d8cd3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,34 +1,28 @@ # monarch-py -## Introduction +## Introduction **monarch-py** is a Python library for interacting with and querying the -Monarch knowledge graph, with implementations for Solr and SQLite backends. +Monarch knowledge graph, with implementations for Solr and SQLite backends. -This means the same API methods can be used regardless of the implementation. +This means the same API methods can be used regardless of the implementation. -This library provides a collection of interfaces for graph operations such as retrieving entities and browsing associations. +This library provides a collection of interfaces for graph operations such as retrieving entities and browsing associations. ## Installation Requires Python 3.8 or higher This library is available via pip or pipx: -```bash -pip|pipx install monarch-py -``` -A [FastAPI server](./FastAPI/index.md) is also available as an extra: ```bash -pip|pipx install monarch-py[api] - -# The API server gets its own terminal command: -monarch-api +pip install monarch-py ``` ## Usage Full usage instructions [here](./Usage/index.md) + ### Basic Example - CLI ```bash @@ -62,7 +56,7 @@ $ monarch associations --subject MONDO:0012933 --limit 5 ### Basic Example - As a Module ```python ->>> from monarch_py.implementations.solr.solr_implentation import SolrImplementation +>>> from monarch_py.implementations.solr.solr_implementation import SolrImplementation >>> si = SolrImplementation() >>> entity = si.get_entity("MONDO:0007947") >>> print(entity.name) diff --git a/frontend/CONTRIBUTING.md b/frontend/CONTRIBUTING.md new file mode 100644 index 000000000..817e414d7 --- /dev/null +++ b/frontend/CONTRIBUTING.md @@ -0,0 +1,271 @@ +# Welcome to the Monarch Initiative + +The Monarch Initiative is an extensive knowledge graph and ecosystem of tools made for the benefit of clinicians, researchers, and scientists. The knowledge graph consists of millions of entities – genes, diseases, phenotypes, and many more – imported from dozens of sources. While we have a core development team, we welcome the contributions of the community to help us maintain and improve the knowledge graph and the tools that use it. + +This CONTRIBUTING.md is a javascript/typescript web app using Bun as a replacement for Node.js (a non-browser JavaScript runtime environment) with the Vite/Vue framework. You can use the monarch-app frontend to query the Monarch KG using the web app locally. + +Without additional setup this will use the same FastAPI backend and data source as the website. This is primarily for front-end development of the website UI. If you want to use a local data store review the monarch-app README.md and CONTRIBUTING.md in the top level directory of this repository to understand how to manage the whole stack locally. + +# Useful Links + +- [Monarch App Website](https://next.monarchinitiative.org/) - The Monarch Initiative website, a Vue webapp accessing `monarch-py`, a Python library for interacting with the Monarch Initiative knowledge graph, which includes an optional FastAPI module that serves as the website's backend. +- [Documentation](https://monarch-initiative.github.io/monarch-documentation/) - In addition, to the documentation here, we have a separate documentation site that is automatically generated from the codebase. + +# Table of Contents + +- [Welcome to the Monarch Initiative](#welcome-to-the-monarch-initiative) +- [Useful Links](#useful-links) +- [Quick Start](#quick-start) + - [Dependancies](#dependancies) +- [Monarch Frontend Details](#monarch-frontend-details) + - [Commands](#commands) + - [Flags](#flags) + - [Phenogrid](#phenogrid) + - [Parameters](#parameters) + - [Events](#events) + - [Style guidelines](#style-guidelines) + +# Quick Start + +To get started running or testing the frontend environment, install the dependancies then + +## Dependancies + +- [Bun](bun.sh) + +Bun is used as a drop-in replacement for Node (non-browser JavaScript runtime environment) and Yarn (package manager). +It is _not_ yet used as a replacement for Vite (dev previewing, bundling, building) or Vitest (test runner). + +This makes one less thing for developers to install. +It also should make installs (which impact GitHub Actions quota) much faster, and anything that runs locally (like Vite and Vitest) a bit faster as well. + +Anything that works in Node should also work in Bun, per Bun's stated goals. +Do not use Bun-specific APIs. +If there is ever a problem with Bun, switching back to Node should be as simple as replacing "bun" with "node"/"yarn" and "bunx" with "npx" in commands. + +To install Bun with an existing Node.js environment (currently recommended for version/package isolation): + +``` +npm install -g bun +``` + +If you don't have an existing Node.js implementation and want to install Bun globally on your system (requires curl): + +``` +curl -fsSL https://bun.sh/install | bash +``` + +## Run using Monarch Cloud hosted API + +To run the frontend using the Monarch Cloud hosted API, you can use the following commands: + +``` +bun install +bun run dev +``` + +You should now be able to run the Monarch Web App from your local system using the Monarch Cloud-Hosted FastAPI and the current realease of the Monarch-KG. If you are trying to use self-hosted data please refer to the README.md in the top-level of the monarch-app repository. + +## Run using local API from backend + +To host the API locally using the backend development in this repo first see frontend/README.md and frontend/CONTRIBUTING.md to ensure dependencies and requirements are met. Once requirements are met you can run the following commands to run the Monarch Web App frontend using the current development backend. + +``` +cd ../backend +poetry install +poetry run monarch solr download +``` + +_Note_ You may need to change permissions on the file in order to install and run the Solr container. + +``` +sudo chgrp -R 8983 ~/.data/monarch +sudo chmod -R g+w ~/.data/monarch +``` + +If the permissions are correct you can then run the Solr instance with: + +``` +poetry run monarch solr start +``` + +In a seperate terminal run the API (this will need to stay running will you are using the UI). Go to monarch-app root and run: + +``` +make dev-api +``` + +Once the API is properly set up with the above commands you can run the frontend with: + +``` +cd ../frontend +VITE_API-local bun run dev +``` + +If you run into problems please see the more detailed information in frontend/README.md and forntend/CONTRIBUTING.md + +# Monarch Frontend Details + +The monarch-app Frontend is a javascript/typescript app built on the Node.js using Bun for package management. It is developed using the Vue 3 framework and built to be deployed using + +This project was scaffolded using Vite (`bun create vite` → `Vue` → `create-vue`). + +- Bun (for runtime and package manager, see note below) +- TypeScript (for type checking) +- Vue Router (for SPA navigation) +- Vitest (unit testing) +- Playwright (e2e testing) +- ESLint (code quality) +- Prettier (code formatting) +- Vue 3 +- Composition API +- `