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

get_entity(
    id, get_association_counts=False, get_hierarchy=False
)

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

get_associations(
    category=None,
    subject=None,
    predicate=None,
    subject_closure=None,
    object=None,
    object_closure=None,
    entity=None,
    offset=0,
    limit=20,
)

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

autocomplete(q)

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_association_counts(entity)

Get counts of associations for a given entity

Parameters:

Name	Type	Description	Default
entity	str	Entity to get association counts for	required

Returns:

Type	Description
List[FacetValue]	List[FacetValue]: List of FacetValue objects representing the counts of associations for the given entity

get_association_facets

get_association_facets(
    facet_fields=None,
    facet_queries=None,
    category=None,
    predicate=None,
    subject=None,
    subject_closure=None,
    object=None,
    object_closure=None,
    entity=None,
)

Get facet counts and facet query counts for associations

Parameters:

Name	Type	Description	Default
facet_fields	List[str]	Facet fields to return counts for	None
facet_queries	List[str]	Facet queries to return counts for	None
category	str	Filter to only associations matching the specified category	None
predicate	str	Filter to only associations matching the specified predicate	None
subject	str	Filter to only associations matching the specified subject	None
subject_closure	str	Filter to only associations with the specified term ID as an ancestor of the subject	None
object	str	Filter to only associations matching the specified object	None
object_closure	str	Filter to only associations with the specified term ID as an ancestor of the object	None
entity	str	Filter to only associations where the specified entity is the subject or the object	None

Returns:

Name	Type	Description
SearchResults	SearchResults	Dataclass representing results of a search, with zero rows returned but total count
	SearchResults	and faceting information populated

get_association_table

get_association_table(
    entity,
    category,
    query=None,
    sort=None,
    offset=0,
    limit=5,
)

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

search(
    q,
    offset=0,
    limit=20,
    category=None,
    in_taxon=None,
    facet_fields=None,
    filter_queries=None,
    facet_queries=None,
    sort=None,
)

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

Implementation of Monarch Interfaces for Solr endpoint

get_association_counts

get_association_counts(entity)

Get association counts for a given entity

This method uses chunks of solr query syntax mapped to the association type

Parameters:

Name	Type	Description	Default
entity	str		required

get_associations

get_associations(
    category=None,
    subject=None,
    predicate=None,
    object=None,
    subject_closure=None,
    object_closure=None,
    entity=None,
    direct=None,
    offset=0,
    limit=20,
)

Retrieve paginated association records, with filter options

Parameters:

Name	Type	Description	Default
category	List[str]	Filter to only associations matching the specified categories. Defaults to None.	None
predicate	List[str]	Filter to only associations matching the specified predicates. Defaults to None.	None
subject	List[str]	Filter to only associations matching the specified subjects. Defaults to None.	None
object	List[str]	Filter to only associations matching the specified objects. 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 with the specified term ID as an ancestor of the object. Defaults to None	None
entity	List[str]	Filter to only associations where the specified entities are 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

Returns:

Name	Type	Description
AssociationResults	AssociationResults	Dataclass representing results of an association search.

get_entity

get_entity(id, extra)

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	Node	Dataclass representing results of an entity search.

search

search(
    q="*:*",
    offset=0,
    limit=20,
    category=None,
    in_taxon=None,
    facet_fields=None,
    facet_queries=None,
    filter_queries=None,
    sort=None,
)

Search for entities by label, with optional filters

SQLImplementation dataclass

Bases: EntityInterface, AssociationInterface

Implementation of Monarch Interfaces for SQL endpoint

get_associations

get_associations(
    category=None,
    subject=None,
    predicate=None,
    object=None,
    subject_closure=None,
    object_closure=None,
    entity=None,
    direct=None,
    offset=0,
    limit=20,
)

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
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	AssociationResults	Dataclass representing results of an association search.

get_entity

get_entity(id, update=False, extra=False)

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.