Interfaces

monarch-py provides a collection of interfaces that abstractify implementation details, and provide a coherent set of graph operations.
Developers can code to the interface, mostly ignoring whether the implementation is a relational database, a local file, etc.

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.