diff --git a/backend/src/monarch_py/solr_cli.py b/backend/src/monarch_py/solr_cli.py index 6b0d22adf..73f6d6aec 100644 --- a/backend/src/monarch_py/solr_cli.py +++ b/backend/src/monarch_py/solr_cli.py @@ -213,6 +213,7 @@ def multi_entity_associations( typer.Option( "--counterpart-category", "-c", + help="A comma-separated list of counterpart categories" ), ] = None, limit: fields.LimitOption = 20, @@ -305,24 +306,23 @@ def histopheno( @solr_app.command("association-counts") def association_counts( - entity: Annotated[str, typer.Argument(help="The entity to get association counts for")], + entity_id: Annotated[ + str, typer.Argument(help="The entity to get association counts for") + ], fmt: fields.FormatOption = fields.OutputFormat.json, output: fields.OutputOption = None, ): """ Retrieve the association counts for a given entity """ - if not entity: - console.print("\n[bold red]Entity ID required.[/]\n") - raise typer.Exit(1) solr = get_solr(update=False) - response = solr.get_association_counts(entity) + response = solr.get_association_counts(entity_id) format_output(fmt, response, output) @solr_app.command("association-table") def association_table( - entity: Annotated[ + entity_id: Annotated[ str, typer.Argument( help="The entity to get associations for", @@ -357,7 +357,7 @@ def association_table( ): solr = get_solr(update=False) response = solr.get_association_table( - entity=entity, + entity=entity_id, category=category, traverse_orthologs=traverse_orthologs, sort=sort, diff --git a/backend/src/monarch_py/utils/cli_fields.py b/backend/src/monarch_py/utils/cli_fields.py index a683ed464..f124e444f 100644 --- a/backend/src/monarch_py/utils/cli_fields.py +++ b/backend/src/monarch_py/utils/cli_fields.py @@ -51,7 +51,7 @@ class OutputFormat(str, Enum): Optional[str], typer.Option( "--output", - "-o", - help="The path to write command output (stdout if not specified)", + "-O", + help="Path to file to write command output (stdout if not specified)", ), ] diff --git a/docs/API-Reference/index.md b/docs/API-Reference/index.md deleted file mode 100644 index a07e72be9..000000000 --- a/docs/API-Reference/index.md +++ /dev/null @@ -1,17 +0,0 @@ -# API Reference - -This section outlines the monarch-py API. - -Here you can find detailed documentation and source code for its interfaces and implementations. - -## Interfaces - -::: src.monarch_py.interfaces.entity_interface -::: src.monarch_py.interfaces.association_interface -::: src.monarch_py.interfaces.search_interface - - -## Implementations -::: src.monarch_py.implementations.solr.solr_implementation -::: src.monarch_py.implementations.sql.sql_implementation - diff --git a/docs/Usage/CLI.md b/docs/Usage/CLI.md index 27980e720..d12fbc9f4 100644 --- a/docs/Usage/CLI.md +++ b/docs/Usage/CLI.md @@ -8,22 +8,22 @@ $ monarch [OPTIONS] COMMAND [ARGS]... **Options**: -* `--version / --no-version` -* `--quiet / --no-quiet`: [default: no-quiet] -* `--debug / --no-debug`: [default: no-debug] +* `-v, --version`: Show the currently installed version +* `-q, --quiet`: Set log level to warning +* `-d, --debug`: Set log level to debug * `--install-completion`: Install completion for the current shell. * `--show-completion`: Show completion for the current shell, to copy it or customize the installation. * `--help`: Show this message and exit. **Commands**: -* `association-counts`: Retrieve association counts for an entity... +* `association-counts`: Retrieve the association counts for a... * `association-table` * `associations`: Paginate through associations * `autocomplete`: Return entity autcomplete matches for a... * `compare`: Compare two sets of phenotypes using... * `entity`: Retrieve an entity by ID -* `histopheno`: Retrieve the histopheno data for an entity... +* `histopheno`: Retrieve the histopheno associations for a... * `mappings` * `multi-entity-associations`: Paginate through associations for multiple... * `release`: Retrieve metadata for a specific release @@ -36,30 +36,22 @@ $ monarch [OPTIONS] COMMAND [ARGS]... ## `monarch association-counts` -Retrieve association counts for an entity by ID - -Args: - entity: The entity to get association counts for - fmt: The format of the output (json, yaml, tsv, table). Default JSON - output: The path to the output file. Default stdout - -Returns: - A list of association counts for the given entity containing association type, label and count +Retrieve the association counts for a given entity **Usage**: ```console -$ monarch association-counts [OPTIONS] [ENTITY] +$ monarch association-counts [OPTIONS] ENTITY_ID ``` **Arguments**: -* `[ENTITY]`: The entity to get association counts for +* `ENTITY_ID`: The entity to get association counts for [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch association-table` @@ -67,41 +59,29 @@ $ monarch association-counts [OPTIONS] [ENTITY] **Usage**: ```console -$ 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} +$ monarch association-table [OPTIONS] ENTITY_ID CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation} ``` **Arguments**: -* `ENTITY`: The entity to get associations for [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] +* `ENTITY_ID`: The entity to get associations for [required] +* `CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation}`: 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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch associations` 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 - 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) - **Usage**: ```console @@ -110,42 +90,37 @@ $ monarch associations [OPTIONS] **Options**: -* `-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 +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation]`: 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 +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:is_sequence_variant_of|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:related_to|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:active_in|biolink:part_of|biolink:model_of|biolink:causes|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:contributes_to|biolink:gene_associated_with_condition|biolink:treats_or_applied_or_studied_to_treat|biolink:colocalizes_with|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_negative_effect|biolink:acts_upstream_of_or_within_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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch autocomplete` Return entity autcomplete matches for a query string -Args: - q: The query string to autocomplete against - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) - **Usage**: ```console -$ monarch autocomplete [OPTIONS] [Q] +$ monarch autocomplete [OPTIONS] Q ``` **Arguments**: -* `[Q]`: Query string to autocomplete against +* `Q`: Query string to autocomplete against [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch compare` @@ -166,61 +141,49 @@ $ monarch compare [OPTIONS] SUBJECTS OBJECTS **Options**: * `-m, --metric [ancestor_information_content|jaccard_similarity|phenodigm_score]`: The metric to use for comparison [default: ancestor_information_content] -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch entity` Retrieve an entity by ID -Args: - id: The identifier of the entity to be retrieved - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) - **Usage**: ```console -$ monarch entity [OPTIONS] [ID] +$ monarch entity [OPTIONS] ENTITY_ID ``` **Arguments**: -* `[ID]`: The identifier of the entity to be retrieved +* `ENTITY_ID`: The identifier of the entity to be retrieved [required] **Options**: * `-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 +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch histopheno` -Retrieve the histopheno data for an entity by ID - -Args: - subject: The subject of the association - -Optional Args: - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout +Retrieve the histopheno associations for a given subject **Usage**: ```console -$ monarch histopheno [OPTIONS] [SUBJECT] +$ monarch histopheno [OPTIONS] SUBJECT ``` **Arguments**: -* `[SUBJECT]`: The subject of the association +* `SUBJECT`: The subject of the association [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch mappings` @@ -235,27 +198,19 @@ $ monarch mappings [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 +* `-p, --predicate-id [skos:exactMatch|skos:broadMatch]`: 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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch multi-entity-associations` Paginate through associations for multiple entities -Args: - entity: A comma-separated list of entities - counterpart_category: A comma-separated list of counterpart categories - 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) - output: The path to the output file (stdout if not specified) - **Usage**: ```console @@ -265,36 +220,31 @@ $ monarch multi-entity-associations [OPTIONS] **Options**: * `-e, --entity TEXT`: Comma-separated list of entities -* `-c, --counterpart-category 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 +* `-c, --counterpart-category TEXT`: A comma-separated list of counterpart categories +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch release` Retrieve metadata for a specific release -Args: - release_ver: The release version to get metadata for - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) - **Usage**: ```console -$ monarch release [OPTIONS] [RELEASE_VER] +$ monarch release [OPTIONS] RELEASE_VER ``` **Arguments**: -* `[RELEASE_VER]`: The release version to get metadata for +* `RELEASE_VER`: The release version to get metadata for [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch releases` @@ -310,7 +260,7 @@ $ monarch releases [OPTIONS] **Options**: * `--dev`: Get dev releases of the KG (default is False) -* `-l, --limit INTEGER`: The number of releases to return [default: 0] +* `-l, --limit INTEGER`: The number of results to return [default: 0] * `--help`: Show this message and exit. ## `monarch schema` @@ -331,15 +281,6 @@ $ monarch schema [OPTIONS] Search for entities -Args: - q: The query string to search for - category: The category of the entity - in_taxon_label: The taxon label to filter by - limit: The number of entities to return - offset: The offset of the first entity to be retrieved - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) - **Usage**: ```console @@ -348,15 +289,15 @@ $ monarch search [OPTIONS] **Options**: -* `-q, --query 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]` +* `-q, --query TEXT`: [default: :*] +* `-c, --category [biolink:SequenceVariant|biolink:Gene|biolink:Genotype|biolink:PhenotypicFeature|biolink:BiologicalProcessOrActivity|biolink:Disease|biolink:GrossAnatomicalStructure|biolink:Cell|biolink:Pathway|biolink:NamedThing|biolink:AnatomicalEntity|biolink:CellularComponent|biolink:MolecularEntity|biolink:BiologicalProcess|biolink:MacromolecularComplex|biolink:MolecularActivity|biolink:Protein|biolink:CellularOrganism|biolink:Vertebrate|biolink:Virus|biolink:BehavioralFeature|biolink:ChemicalEntity|biolink:LifeStage|biolink:PathologicalProcess|biolink:Drug|biolink:SmallMolecule|biolink:OrganismTaxon|biolink:InformationContentEntity|biolink:NucleicAcidEntity|biolink:EvidenceType|biolink:RNAProduct|biolink:Transcript|biolink:Fungus|biolink:Plant|biolink:ProcessedMaterial|biolink:Activity|biolink:Agent|biolink:ConfidenceLevel|biolink:Dataset|biolink:EnvironmentalFeature|biolink:GeneticInheritance|biolink:Haplotype|biolink:Invertebrate|biolink:Mammal|biolink:PopulationOfIndividualOrganisms|biolink:ProteinFamily|biolink:Publication|biolink:AccessibleDnaRegion|biolink:Bacterium|biolink:BiologicalSex|biolink:CellLine|biolink:ChemicalExposure|biolink:ChemicalMixture|biolink:DatasetDistribution|biolink:DiagnosticAid|biolink:DrugExposure|biolink:EnvironmentalProcess|biolink:Event|biolink:Exon|biolink:Genome|biolink:GenotypicSex|biolink:Human|biolink:IndividualOrganism|biolink:MaterialSample|biolink:MicroRNA|biolink:OrganismalEntity|biolink:Patent|biolink:PhenotypicSex|biolink:Polypeptide|biolink:ProteinDomain|biolink:ReagentTargetedGene|biolink:RegulatoryRegion|biolink:SiRNA|biolink:Snv|biolink:Study|biolink:StudyVariable|biolink:TranscriptionFactorBindingSite|biolink:Treatment|biolink:WebPage|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 +* `-fq, --facet-queries TEXT` +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch solr` @@ -369,8 +310,8 @@ $ monarch solr [OPTIONS] COMMAND [ARGS]... **Options**: -* `--quiet / --no-quiet`: [default: no-quiet] -* `--debug / --no-debug`: [default: no-debug] +* `-q, --quiet`: Set log level to warning +* `-d, --debug`: Set log level to debug * `--help`: Show this message and exit. **Commands**: @@ -393,27 +334,20 @@ $ monarch solr [OPTIONS] COMMAND [ARGS]... Retrieve the association counts for a given entity -Args: - entity (str): The entity to get association counts for - -Optional Args: - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout - **Usage**: ```console -$ monarch solr association-counts [OPTIONS] [ENTITY] +$ monarch solr association-counts [OPTIONS] ENTITY_ID ``` **Arguments**: -* `[ENTITY]`: The entity to get association counts for +* `ENTITY_ID`: The entity to get association counts for [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr association-table` @@ -421,41 +355,29 @@ $ monarch solr association-counts [OPTIONS] [ENTITY] **Usage**: ```console -$ 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] +$ monarch solr association-table [OPTIONS] ENTITY_ID CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation} ``` **Arguments**: -* `ENTITY`: The entity to get associations for [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 +* `ENTITY_ID`: The entity to get associations for [required] +* `CATEGORY:{biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation}`: The association category to get associations for, ex. biolink:GeneToPhenotypicFeatureAssociation [required] **Options**: -* `-t, --traverse-orthologs`: Whether to traverse orthologs when getting associations * `-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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr associations` Paginate through associations -Args: - 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) (default json) - output: The path to the output file (stdout if not specified) (default None) - **Usage**: ```console @@ -464,42 +386,37 @@ $ monarch solr associations [OPTIONS] **Options**: -* `-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 +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation]`: 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 +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:is_sequence_variant_of|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:related_to|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:active_in|biolink:part_of|biolink:model_of|biolink:causes|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:contributes_to|biolink:gene_associated_with_condition|biolink:treats_or_applied_or_studied_to_treat|biolink:colocalizes_with|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_negative_effect|biolink:acts_upstream_of_or_within_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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr autocomplete` Return entity autcomplete matches for a query string -Args: - q: The query string to autocomplete against - fmt: The format of the output (json, yaml, tsv, table) - output: The path to the output file (stdout if not specified) - **Usage**: ```console -$ monarch solr autocomplete [OPTIONS] [Q] +$ monarch solr autocomplete [OPTIONS] Q ``` **Arguments**: -* `[Q]`: Query string to autocomplete against +* `Q`: Query string to autocomplete against [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr download` @@ -509,68 +426,57 @@ Download the Monarch Solr KG. **Usage**: ```console -$ monarch solr download [OPTIONS] +$ monarch solr download [OPTIONS] [VERSION] ``` +**Arguments**: + +* `[VERSION]`: The version of the Solr KG to download (latest, dev, or a specific version) [default: latest] + **Options**: -* `--version TEXT`: [default: latest] -* `--overwrite / --no-overwrite`: [default: no-overwrite] +* `--overwrite`: Overwrite the existing Solr KG if it exists * `--help`: Show this message and exit. ### `monarch solr entity` Retrieve an entity by ID -Args: - id (str): The identifier of the entity to be retrieved - -Optional Args: - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout - **Usage**: ```console -$ monarch solr entity [OPTIONS] [ID] +$ monarch solr entity [OPTIONS] ENTITY_ID ``` **Arguments**: -* `[ID]`: The identifier of the entity to be retrieved +* `ENTITY_ID`: The identifier of the entity to be retrieved [required] **Options**: * `-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 +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr histopheno` Retrieve the histopheno associations for a given subject -Args: - subject (str): The subject of the association - -Optional Args: - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout - **Usage**: ```console -$ monarch solr histopheno [OPTIONS] [SUBJECT] +$ monarch solr histopheno [OPTIONS] SUBJECT ``` **Arguments**: -* `[SUBJECT]`: The subject of the association +* `SUBJECT`: The subject of the association [required] **Options**: -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: JSON] -* `-O, --output TEXT`: The path to the output file +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr mappings` @@ -585,27 +491,19 @@ $ monarch solr mappings [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 +* `-p, --predicate-id [skos:exactMatch|skos:broadMatch]`: 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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr multi-entity-associations` Paginate through associations for multiple entities -Args: - entity: A comma-separated list of entities - counterpart_category: A comma-separated list of counterpart categories - 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) - output: The path to the output file (stdout if not specified) - **Usage**: ```console @@ -614,29 +512,18 @@ $ monarch solr multi-entity-associations [OPTIONS] **Options**: -* `-e, --entity TEXT`: Entity ID to get associations for -* `-c, --counterpart-category TEXT`: Counterpart category to get associations for -* `-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 +* `-e, --entity TEXT`: Comma-separated list of entities +* `-c, --counterpart-category TEXT`: A comma-separated list of counterpart categories +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr search` Search for entities -Optional Args: - q: The query string to search for - category: The category of the entity - in_taxon_label: The taxon label to filter on - facet_fields: The fields to facet on - facet_queries: The queries to facet on - limit: The number of entities to return - offset: The offset of the first entity to be retrieved - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout - **Usage**: ```console @@ -645,15 +532,15 @@ $ monarch solr search [OPTIONS] **Options**: -* `-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]` +* `-q, --query TEXT`: [default: :*] +* `-c, --category [biolink:SequenceVariant|biolink:Gene|biolink:Genotype|biolink:PhenotypicFeature|biolink:BiologicalProcessOrActivity|biolink:Disease|biolink:GrossAnatomicalStructure|biolink:Cell|biolink:Pathway|biolink:NamedThing|biolink:AnatomicalEntity|biolink:CellularComponent|biolink:MolecularEntity|biolink:BiologicalProcess|biolink:MacromolecularComplex|biolink:MolecularActivity|biolink:Protein|biolink:CellularOrganism|biolink:Vertebrate|biolink:Virus|biolink:BehavioralFeature|biolink:ChemicalEntity|biolink:LifeStage|biolink:PathologicalProcess|biolink:Drug|biolink:SmallMolecule|biolink:OrganismTaxon|biolink:InformationContentEntity|biolink:NucleicAcidEntity|biolink:EvidenceType|biolink:RNAProduct|biolink:Transcript|biolink:Fungus|biolink:Plant|biolink:ProcessedMaterial|biolink:Activity|biolink:Agent|biolink:ConfidenceLevel|biolink:Dataset|biolink:EnvironmentalFeature|biolink:GeneticInheritance|biolink:Haplotype|biolink:Invertebrate|biolink:Mammal|biolink:PopulationOfIndividualOrganisms|biolink:ProteinFamily|biolink:Publication|biolink:AccessibleDnaRegion|biolink:Bacterium|biolink:BiologicalSex|biolink:CellLine|biolink:ChemicalExposure|biolink:ChemicalMixture|biolink:DatasetDistribution|biolink:DiagnosticAid|biolink:DrugExposure|biolink:EnvironmentalProcess|biolink:Event|biolink:Exon|biolink:Genome|biolink:GenotypicSex|biolink:Human|biolink:IndividualOrganism|biolink:MaterialSample|biolink:MicroRNA|biolink:OrganismalEntity|biolink:Patent|biolink:PhenotypicSex|biolink:Polypeptide|biolink:ProteinDomain|biolink:ReagentTargetedGene|biolink:RegulatoryRegion|biolink:SiRNA|biolink:Snv|biolink:Study|biolink:StudyVariable|biolink:TranscriptionFactorBindingSite|biolink:Treatment|biolink:WebPage|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 +* `-fq, --facet-queries TEXT` +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch solr start` @@ -709,8 +596,8 @@ $ monarch sql [OPTIONS] COMMAND [ARGS]... **Options**: -* `--quiet / --no-quiet`: [default: no-quiet] -* `--debug / --no-debug`: [default: no-debug] +* `-q, --quiet`: Set log level to warning +* `-d, --debug`: Set log level to debug * `--help`: Show this message and exit. **Commands**: @@ -722,19 +609,6 @@ $ monarch sql [OPTIONS] COMMAND [ARGS]... 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 - 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) - output: The path to the output file (stdout if not specified) - **Usage**: ```console @@ -743,45 +617,39 @@ $ monarch sql associations [OPTIONS] **Options**: -* `-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 +* `-c, --category [biolink:PairwiseGeneToGeneInteraction|biolink:GeneToExpressionSiteAssociation|biolink:VariantToGeneAssociation|biolink:MacromolecularMachineToBiologicalProcessAssociation|biolink:GeneToPhenotypicFeatureAssociation|biolink:MacromolecularMachineToMolecularActivityAssociation|biolink:MacromolecularMachineToCellularComponentAssociation|biolink:Association|biolink:GeneToGeneHomologyAssociation|biolink:GenotypeToPhenotypicFeatureAssociation|biolink:DiseaseToPhenotypicFeatureAssociation|biolink:GeneToPathwayAssociation|biolink:DiseaseOrPhenotypicFeatureToLocationAssociation|biolink:ChemicalToPathwayAssociation|biolink:GenotypeToDiseaseAssociation|biolink:CorrelatedGeneToDiseaseAssociation|biolink:DiseaseOrPhenotypicFeatureToGeneticInheritanceAssociation|biolink:VariantToDiseaseAssociation|biolink:CausalGeneToDiseaseAssociation|biolink:ChemicalToDiseaseOrPhenotypicFeatureAssociation]`: 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 +* `-p, --predicate [biolink:interacts_with|biolink:expressed_in|biolink:has_phenotype|biolink:is_sequence_variant_of|biolink:enables|biolink:actively_involved_in|biolink:orthologous_to|biolink:located_in|biolink:subclass_of|biolink:related_to|biolink:participates_in|biolink:acts_upstream_of_or_within|biolink:active_in|biolink:part_of|biolink:model_of|biolink:causes|biolink:acts_upstream_of|biolink:has_mode_of_inheritance|biolink:contributes_to|biolink:gene_associated_with_condition|biolink:treats_or_applied_or_studied_to_treat|biolink:colocalizes_with|biolink:acts_upstream_of_positive_effect|biolink:acts_upstream_of_or_within_positive_effect|biolink:acts_upstream_of_negative_effect|biolink:acts_upstream_of_or_within_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 +* `-l, --limit INTEGER`: The number of results to return [default: 20] +* `--offset INTEGER`: The offset of the first result to be retrieved [default: 0] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ### `monarch sql entity` Retrieve an entity by ID -Args: - id (str): The identifier of the entity to be retrieved - update (bool): = Whether to re-download the Monarch KG. Default False - fmt (str): The format of the output (json, yaml, tsv, table). Default JSON - output (str): The path to the output file. Default stdout - **Usage**: ```console -$ monarch sql entity [OPTIONS] [ID] +$ monarch sql entity [OPTIONS] ENTITY_ID ``` **Arguments**: -* `[ID]`: The identifier of the entity to be retrieved +* `ENTITY_ID`: The identifier of the entity to be retrieved [required] **Options**: -* `-e, --extra`: Include extra fields in the output (association_counts and node_hierarchy) -* `-u, --update`: Whether to re-download the Monarch KG -* `-f, --format TEXT`: The format of the output (json, yaml, tsv, table) [default: json] -* `-o, --output TEXT`: The path to the output file +* `-e, --extra`: Include extra fields in the output (association_counts and node_hierarchy) [required] +* `-u, --update`: Whether to re-download the Monarch KG [required] +* `-f, --format [json|yaml|tsv|table]`: The format of the output (json, yaml, tsv, table) [default: json] +* `-O, --output TEXT`: Path to file to write command output (stdout if not specified) * `--help`: Show this message and exit. ## `monarch test` diff --git a/docs/release-process.md b/docs/release-process.md new file mode 100644 index 000000000..c7236db9d --- /dev/null +++ b/docs/release-process.md @@ -0,0 +1,191 @@ +# Monarch Release Process + +## Overview + +This document describes the steps required to create a new Monarch release. + +These releases consist primarily of the following components: + +- Monarch Mapping files via [Monarch Mapping Commons](https://github.com/monarch-initiative/monarch-mapping-commons) +- Knowledge Graph via [Monarch Ingest](https://github.com/monarch-initiative/monarch-ingest) +- Data library and API via [Monarch-Py](https://github.com/monarch-initiative/monarch-app/backend) +- Monarch website via [Monarch-App](https://github.com/monarch-initiative/monarch-app/frontend) + + +## Monarch Mapping Commons + +[Monarch Mapping Commons](https://github.com/monarch-initiative/monarch-mapping-commons) is a repository that contains code used to generate the mapping files used in the creation of the Monarch knowledge graph. +The nodes and edges in the knowledge graph come from a variety of sources, and have varying IDs and prefixes. +The mapping files are used to map these IDs to IDs in Monarch's preferred namespaces. + +These mapping files are generated via a Jenkins job on a weekly basis, and are stored in the [Monarch Data Bucket](https://data.monarchinitiative.org/mappings/index.html). + +## Monarch Ingest (Knowledge Graph) + +Monarch's knowledge graph is built using the Monarch Ingest pipeline. +The pipeline is run on a Jenkins server, and the resulting knowledge graph is uploaded to both Monarch's data bucket on Google Cloud, as well as the KG-Hub AWS S3 bucket. + +Changes to the Monarch Ingest pipeline are made in the [Monarch Ingest](https://github.com/monarch-initiative/monarch-ingest) repository. + +After the knowledge graph has been built, the [QC Dashboard](https://github.com/monarch-initiative/monarch-qc) is used to verify the difference between the new build of the knowledge graph and the previous build. + +Once the knowledge graph has been verified, additional steps are required to make the new knowledge graph available to the dev, beta, and production versions of the Monarch website. + +### Deploying the Knowledge Graph + +#### Deploying to dev + +While the Github Actions workflow for Monarch App will automatically update and deploy API & UI code to the dev environment, the knowledge graph must be manually deployed to the dev environment. + +Preparing the environment for deployment: + +* Make sure dependancies from monarch-stack-v3/README.md are installed +* Ensure secrets are installed in $home/.secrets + +To deploy the knowledge graph to the dev environment, follow these steps: + +* Checkout (or update) [Monarch Stack V3](https://github.com/monarch-initiative/monarch-stack-v3) +* Source the dev environment: `cd deployment && source site-envs/monarch-dev.env` +* Run the provision script to update the dev environment: `./provision.sh` +* After running the provision script to update the dev environment, a manual restart of the Solr container is necessary: + +``` +gcloud compute ssh --zone us-central1-a monarch-v3-${TF_VAR_env}-manager -- sudo docker service update --force monarch-v3_solr +``` + +From this point forward, code updates on the dev environment will be automatically deployed and additional work will happen to finish the work planned for the milestone. Ideally changes to the graph will happen early in the release cycle. + +#### Deploying to beta + +Once work on the milestone is complete, we need to tag the release in GitHub then we can deploy to the beta environment. + +To tag the release, go to the [Monarch App](https://github.com/monarch-initiative/monarch-app) and click on releases. Create a new release with the new version number and click generate release notes. Make any changes to the release notes that are necessary (generally none) and click publish release. + +You may want to set an environment variable for the release version to make it easier to copy and paste the version number in the following steps (update for your current version): + +``` +RELEASE="2024-02-13" +``` + +First, copy the KG release from monarch-kg-dev to monarch-kg: +``` +gsutil cp -r gs://data-public-monarchinitiative/monarch-kg-dev/${RELEASE} gs://data-public-monarchinitiative/monarch-kg/${RELEASE} +``` +Then, we need to copy in the archive: +``` +gsutil cp -r gs://monarch-archive/monarch-kg-dev/${RELEASE} gs://monarch-archive/monarch-kg/${RELEASE} +``` + +Within monarch-stack-v3, copy the latest release env file to a new env, for example: `cp site-envs/monarch-2023-10-11.env site-envs/monarch-${RELEASE}.env` +The date for the environment file name should match the KG release version, rather than today's date. +Edit the top two lines in new env to match the latest KG & API versions: + +``` +export MONARCH_KG_VERSION="2023-11-16" +export MONARCH_API_VERSION="0.18.1" +``` + +Then source the new environment and run provision.sh to create the new VM stack, paying attention to the terrform output to make sure that it's creating VMs with a version name you expect: + +``` +source site-envs/monarch-2023-11-16.env +./provision.sh +``` + +Output for the provision script should look something like this: + +``` +... +Changes to Outputs: + + api_image_tag = "1.0.0" + + env = "2024-02-13" + + full_prefix = "monarch-v3-2024-02-13-" + + neo4j_archive_url = "https://data.monarchinitiative.org/monarch-kg-dev/latest/monarch-kg.neo4j.dump" + + phenio_archive_url = "https://data.monarchinitiative.org/monarch-kg/2024-02-13/phenio.db.gz" + + project = "monarch-initiative" + + semsimian_image_tag = "latest" + + solr_archive_url = "https://data.monarchinitiative.org/monarch-kg/2024-02-13/solr.tar.gz" + + sqlite_archive_url = "https://data.monarchinitiative.org/monarch-kg/2024-02-13/monarch-kg.db.gz" + + stack = "monarch-v3" + + ui_image_tag = "latest" + + vm_svc_acct_email = "terraform@monarch-initiative.iam.gserviceaccount.com" + +Do you want to perform these actions? + Terraform will perform the actions described above. + Only 'yes' will be accepted to approve. +``` + +At the end of the run you should see a message like this: + +``` +PLAY RECAP *************************************************************************************************** +monarch-v3-2024-02-13-api : ok=11 changed=3 unreachable=0 failed=0 skipped=2 rescued=0 ignored=0 +monarch-v3-2024-02-13-manager : ok=12 changed=3 unreachable=0 failed=0 skipped=2 rescued=0 ignored=0 +monarch-v3-2024-02-13-neo4j : ok=11 changed=3 unreachable=0 failed=0 skipped=2 rescued=0 ignored=0 +monarch-v3-2024-02-13-solr : ok=11 changed=3 unreachable=0 failed=0 skipped=2 rescued=0 ignored=0 +``` + +#### Connecting beta to the load balancer + +Once this completes, open the [GCP load balancer configuration](https://console.cloud.google.com/net-services/loadbalancing/details/http/monarch-balancer?project=monarch-initiative). + +1. Click on the **edit** link at the top of the page. +2. Click on **Backend Configuration** +3. Open the **Backend services & backend buckets** pull down on the right side and check `monarch-v3-{release}-api-backend` & `monarch-v3-{release}-nginx-backend`, leave the other boxes checked, and click ok. +4. Open the `Host and path rules` section to point `beta.monarchinitiative.org` to the `nginx` backend, `api-beta.monarchinitiative.org` to the `api` backend, and `neo4j-beta.monarchinitiative.org` to the `neo4j` backend. +5. Then for each of these endpoints add `/*` to the path matcher, and click update. + +If you get a pop-up window error, you may have forgotten to delete one of the old routes when pointing to the new backend. You will need to redo the configuration if this happens. + +The load balancer will automatically restart with the new configuration. Then we'll need to confirm that the site is up and running. + +Get yourself a cup of hot chocolate / ice cold lemonade (season dependent) and settle in to go through the issues in the milestone. Make sure that each issue appears to actually be fixed, and close them with a note that they're confirmed to be working on beta.monarchinitiative.org. (with some additional explanation for externally submitted issues about when the change is expected to be visible on the production site) + + +#### Deploying to production + +Edit the load balancer +1. Remove the nginx and api backends from the last release +2. Point `api-beta.monarchinitiative.org`, `api-v3.monarchinitiative.org`, and `api-next.monarchinitiative.org` to `monarch-v3-{release}-api-backend` +3. Point `next.monarchinitiative.org` and `monarchinitiative.org` to `monarch-v3-{release}-nginx-backend` +4. At the top of the host and path rules seciton, change the default backend ("Backend 1") to point to `monarch-v3-{release}-nginx-backend` as well + +Then turn off the former production VMs (but keep them around for disaster recovery) by going to the GCP console VM listings and just clicking stop on each VM. + +Source the former former env in v3 stack to delete it (say yes to deleting, and no to creating in the terraform dialogs) +``` +source site-envs/monarch-2023-10-17.env +./provision.sh -d +``` + +#### Troubleshooting + +Here are some known issues that we have seen before: + +In `./provision.sh` you may see an error like this: + +``` +fatal: [monarch-v3-2024-02-13-api]: UNREACHABLE! => changed=false + msg: |- + Data could not be sent to remote host "monarch-v3-2024-02-13-api". Make sure this host can be reached over ssh: Pseudo-terminal will not be allocated because stdin is not a terminal. + sa_116692422516913491665@34.42.108.156: Permission denied (publickey). + + Recommendation: To check for possible causes of SSH connectivity issues and get + recommendations, rerun the ssh command with the --troubleshoot option. + + gcloud compute ssh monarch-v3-2024-02-13-api --project=monarch-initiative --zone=us-central1-a --troubleshoot + + Or, to investigate an IAP tunneling issue: + + gcloud compute ssh monarch-v3-2024-02-13-api --project=monarch-initiative --zone=us-central1-a --troubleshoot --tunnel-through-iap + + ERROR: (gcloud.compute.ssh) [/usr/bin/ssh] exited with return code [255]. + unreachable: true +``` + +If so you may want to run the stated command (update to your version): + +```commandline +gcloud compute ssh monarch-v3-2024-02-13-api --project=monarch-initiative --zone=us-central1-a --troubleshoot +``` + diff --git a/mkdocs.yaml b/mkdocs.yaml index 2f0b88326..348fc7d90 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -1,14 +1,15 @@ -site_name: 'monarch-py' +site_name: 'Monarch KG Tools' repo_name: 'monarch-app/backend' repo_url: 'https://github.com/monarch-initiative/monarch-app/tree/main/backend' site_url: 'https://monarch-app.monarchinitiative.org/docs/' nav: - - Welcome: 'index.md' - - Usage: + - monarch-py: + - Overview: 'index.md' - Usage: 'Usage/index.md' - CLI: 'Usage/CLI.md' + - Data Model: 'Data-Model/index.md' - Interfaces: - Overview: 'Usage/Interfaces/index.md' - Entity: 'Usage/Interfaces/Entity.md' @@ -20,12 +21,11 @@ nav: - Solr: 'Usage/Implementations/Solr.md' - SQL: 'Usage/Implementations/SQL.md' # - OAK: 'Usage/Implementations/OAK.md' + - Release Process: 'release-process.md' - FastAPI: - Overview: 'FastAPI/index.md' - Endpoints: - 'FastAPI/Endpoints/index.md' - - API Reference: 'API-Reference/index.md' - - Response Data Model: 'Data-Model/index.md' theme: