API Reference
This section outlines the monarch-py API.
Here you can find detailed documentation and source code for its interfaces and implementations.
Interfaces
EntityInterface
Bases: ABC
Abstract interface for entities in the Monarch KG
get_entity
abstractmethod
Retrieve a specific entity by exact ID match, with optional extras
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id |
str
|
id of the entity to search for. |
required |
get_association_counts |
bool
|
Whether to get a count of associations for the entity. Defaults to False. |
False
|
get_hierarchy |
bool
|
Whether to get the entity's heirarchy in the data model. Defaults to False. |
False
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Use a specific implementation (see the documentation for a list of implementations) |
Returns:
| Name | Type | Description |
|---|---|---|
Entity |
Entity
|
Dataclass representing results of an entity search. |
AssociationInterface
Bases: ABC
Abstract interface for associations in the Monarch KG
get_associations
abstractmethod
Retrieve paginated association records, with filter options
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category |
str
|
Filter to only associations matching the specified category. Defaults to None. |
None
|
predicate |
str
|
Filter to only associations matching the specified predicate. Defaults to None. |
None
|
subject |
str
|
Filter to only associations matching the specified subject. Defaults to None. |
None
|
subject_closure |
str
|
Filter to only associations with the specified term ID as an ancestor of the subject. Defaults to None |
None
|
object |
str
|
Filter to only associations matching the specified object. Defaults to None. |
None
|
object_closure |
str
|
Filter to only associations with the specified term ID as an ancestor of the object. Defaults to None |
None
|
entity |
str
|
Filter to only associations where the specified entity is the subject or the object. Defaults to None. |
None
|
offset |
int
|
Result offset, for pagination. Defaults to 0. |
0
|
limit |
int
|
Limit results to specified number. Defaults to 20. |
20
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Use a specific implementation (see the documentation for a list of implementations) |
Returns:
| Type | Description |
|---|---|
AssociationResults
|
AssociationResults: Dataclass representing results of an association search. |
SearchInterface
Bases: ABC
Abstract interface for searching the Monarch KG in a Lucene way
autocomplete
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q |
str
|
Query string to match against |
required |
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Use a specific implementation (see the documentation for a list of implementations) |
Returns:
| Name | Type | Description |
|---|---|---|
SearchResults |
SearchResults
|
Dataclass representing results of a generic entity search. |
get_association_counts
Get counts of associations for a given entity Args: entity (str): Entity to get association counts for Returns: List[FacetValue]: List of FacetValue objects representing the counts of associations for the given entity
get_association_facets
Get facet counts and facet query counts for associations Args: facet_fields (List[str]): Facet fields to return counts for facet_queries (List[str]): Facet queries to return counts for category (str): Filter to only associations matching the specified category predicate (str): Filter to only associations matching the specified predicate subject (str): Filter to only associations matching the specified subject subject_closure (str): Filter to only associations with the specified term ID as an ancestor of the subject object (str): Filter to only associations matching the specified object object_closure (str): Filter to only associations with the specified term ID as an ancestor of the object entity (str): Filter to only associations where the specified entity is the subject or the object Returns: SearchResults: Dataclass representing results of a search, with zero rows returned but total count and faceting information populated
get_association_table
Get associations for an entity matching a specified type, with optional search and sort parameters
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entity |
str
|
Entity to get associations for |
required |
category |
str
|
Category of associations to return |
required |
query |
str
|
Query string to match against |
None
|
sort |
str
|
Sort order, defaults to None |
None
|
offset |
int
|
Offset of the first result to return, defaults to 0 |
0
|
limit |
int
|
Limit the number of results to return, defaults to 20 |
5
|
Returns:
| Name | Type | Description |
|---|---|---|
AssociationResults |
AssociationTableResults
|
Dataclass representing results of an association search. |
search
abstractmethod
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q |
str
|
Query string to match against |
required |
category |
str
|
Limit results to only this category |
None
|
taxon |
str
|
Limit results to only this taxon |
required |
offset |
int
|
Offset of the first result to return, defaults to 0 |
0
|
limit |
int
|
Limit the number of results to return, defaults to 20 |
20
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
Use a specific implementation (see the documentation for a list of implementations) |
Returns:
| Name | Type | Description |
|---|---|---|
EntityResults |
SearchResults
|
Dataclass representing results of a generic entity search. |
Implementations
SolrImplementation
dataclass
Bases: EntityInterface, AssociationInterface, SearchInterface, GroundingInterface
Implementation of Monarch Interfaces for Solr endpoint
get_association_counts
Get list of association counts for a given entity
get_associations
Retrieve paginated association records, with filter options
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category |
List[AssociationCategory]
|
Filter to only associations matching the specified categories. Defaults to None. |
None
|
predicate |
List[AssociationPredicate]
|
Filter to only associations matching the specified predicates. Defaults to None. |
None
|
subject |
Optional[List[str]]
|
Filter to only associations matching the specified subjects. Defaults to None. |
None
|
object |
Optional[List[str]]
|
Filter to only associations matching the specified objects. Defaults to None. |
None
|
subject_closure |
Optional[str]
|
Filter to only associations with the specified term ID as an ancestor of the subject. Defaults to None |
None
|
object_closure |
Optional[str]
|
Filter to only associations with the specified term ID as an ancestor of the object. Defaults to None |
None
|
entity |
Optional[List[str]]
|
Filter to only associations where the specified entities are the subject or the object. Defaults to None. |
None
|
q |
Optional[str]
|
Query string to search within matches. Defaults to None. |
None
|
compact |
bool
|
Return compact results with fewer fields. Defaults to False. |
False
|
offset |
int
|
Result offset, for pagination. Defaults to 0. |
0
|
limit |
int
|
Limit results to specified number. Defaults to 20. |
20
|
Returns:
| Name | Type | Description |
|---|---|---|
AssociationResults |
Union[AssociationResults, CompactAssociation]
|
Dataclass representing results of an association search. |
get_counterpart_entities
Get a list of entities directly associated with this_entity fetched from associations in the Solr index
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
this_entity |
Entity
|
The entity to get associations for |
required |
entity |
str
|
an entity ID occurring in either the subject or object. Defaults to None. |
None
|
subject |
str
|
an entity ID occurring in the subject. Defaults to None. |
None
|
predicate |
str
|
a predicate value. Defaults to None. |
None
|
object |
str
|
an entity ID occurring in the object. Defaults to None. |
None
|
get_entity
Retrieve a specific entity by exact ID match, with optional extras
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id |
str
|
id of the entity to search for. |
required |
extra |
bool
|
Whether to include association counts and hierarchy in the response. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Entity |
Optional[Union[Node, Entity]]
|
Dataclass representing results of an entity search. |
Node |
Optional[Union[Node, Entity]]
|
Dataclass representing results of an entity search with extra=True. |
get_histopheno
Get histopheno counts for a given subject_closure
get_multi_entity_associations
Get associations between multiple entities and counterparts of a given category
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
entity |
List[str]
|
List of entity IDs to get associations for |
required |
counterpart_category |
List[str]
|
List of categories of counterpart entity to get associations for. Defaults to None. |
None
|
offset |
int
|
Result offset, for pagination. Defaults to 0. |
0
|
limit |
int
|
Limit results to specified number. Defaults to 20. |
required |
limit_per_group |
int
|
Limit results to specified number per group. Defaults to 20. |
20
|
ground_entity
search
Search for entities by label, with optional filters
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
q |
str
|
Query string. Defaults to ":". |
'*:*'
|
offset |
int
|
Result offset, for pagination. Defaults to 0. |
0
|
limit |
int
|
Limit results to specified number. Defaults to 20. |
20
|
category |
List[str]
|
Filter to only entities matching the specified categories. Defaults to None. |
None
|
in_taxon_label |
List[str]
|
Filter to only entities matching the specified taxon label. Defaults to None. |
None
|
facet_fields |
List[str]
|
List of fields to include facet counts for. Defaults to None. |
None
|
facet_queries |
List[str]
|
List of queries to include facet counts for. Defaults to None. |
None
|
filter_queries |
List[str]
|
List of queries to filter results by. Defaults to None. |
None
|
sort |
str
|
Sort results by the specified field. Defaults to None. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
SearchResults |
SearchResults
|
Dataclass representing results of a search. |
solr_is_available
Check if the Solr instance is available
SQLImplementation
dataclass
Bases: EntityInterface, AssociationInterface
Implementation of Monarch Interfaces for SQL endpoint
get_associations
Retrieve paginated association records, with filter options
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
category |
str
|
Filter to only associations matching the specified category. Defaults to None. |
None
|
predicate |
str
|
Filter to only associations matching the specified predicate. Defaults to None. |
None
|
subject |
str
|
Filter to only associations matching the specified subject. Defaults to None. |
None
|
object |
str
|
Filter to only associations matching the specified object. Defaults to None. |
None
|
subject_closure |
str
|
Filter to only associations with the specified term ID as an ancestor of the subject. Defaults to None. |
None
|
object_closure |
str
|
Filter to only associations the specified term ID as an ancestor of the object. Defaults to None. |
None
|
entity |
str
|
Filter to only associations where the specified entity is the subject or the object. Defaults to None. |
None
|
association_type |
str
|
Filter to only associations matching the specified association label. Defaults to None. |
required |
compact |
bool
|
Whether to return compact or full association records. Defaults to False. |
False
|
offset |
int
|
Result offset, for pagination. Defaults to 0. |
0
|
limit |
int
|
Limit results to specified number. Defaults to 20. |
20
|
Returns:
| Name | Type | Description |
|---|---|---|
AssociationResults |
Union[AssociationResults, CompactAssociationResults]
|
Dataclass representing results of an association search. |
get_entity
Retrieve a specific entity by exact ID match, writh optional extras
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
id |
str
|
id of the entity to search for. |
required |
get_association_counts |
bool
|
Whether to get association counts. Defaults to False. |
required |
get_hierarchy |
bool
|
Whether to get the entity hierarchy. Defaults to False. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Entity |
Entity
|
Dataclass representing results of an entity search. |