ontology

knowledge.ontology

title: “Ontology Module for TVB-O”

author: Leon Martin

This module provides a set of functions to interact with the ontology of TVB-O. It includes functions to:

Retrieve package version.
Render ontology objects using labels or IRIs.
Access and extract various parts of the ontology like models, variables, parameters, etc.
Compare different models based on their parameters.
Get properties of parameters.

Usage:

from tvbo.knowledge import ontology
jansen_rit_model = ontology.get_model("JansenRit")

Author

Leon K. Martin (2023)

Copyright

Functions

Name	Description
compare_models	Compares two TVB models based on their parameters or another specified metric.
disintersection	Computes the unique elements of two lists.
filter_cls_list	Filters out classes from a list that have a specific ancestor.
find_best_fuzzy_match	Find the best fuzzy match for a target string in a list of strings,
find_variables	Finds a variable in a TVB model.
find_version	Retrieves the package version from the `__init__.py` file.
get_def	Retrieve the description or definition of a class based on the specified mode.
get_default_values	Retrieves the default values for a given TVB model’s parameters.
get_definition	Retrieves the definition for a given ontology class.
get_model	Retrieves a specific TVB-O model using its label.
get_model_acronym	Retrieves the acronym for a given TVB model.
get_model_arguments	Retrieves the arguments for a given TVB model.
get_model_coefficients	Retrieves the coefficients for a given TVB model.
get_model_coupling_terms	Retrieves the coupling terms for a given TVB model.
get_model_cvars	Retrieves the cvars (coupling variables) for a given TVB model.
get_model_derivatives	Retrieves the derivatives for a given TVB model.
get_model_functions	Retrieves the functions for a given TVB model.
get_model_parameters	Retrieves the parameters for a given TVB model.
get_model_statevariables	Retrieves the state variables for a given TVB model.
get_model_suffix	Retrieves the suffix for a given TVB model, based on its acronym.
get_model_variables	Retrieves the variables for a given TVB model.
get_models	Retrieves all TVB-O models of a given type.
get_parameters_by_catalogue	Retrieves parameters for a given TVB model, based on a specified parameter catalogue.
get_property_annotation	Retrieves annotations for a given ontology class and property.
get_range	Retrieves the range for a given ontology variable.
get_sorted_dict	Creates a dictionary from a list of ontology classes. The dictionary’s keys are the class labels
get_subclass_list	Retrieves subclasses for a given ontology class, up to a specified depth.
get_subclasses	Retrieves the subclasses for a given TVB-O class.
get_superclasses	Retrieves the superclasses for a given TVB-O class.
get_type	Retrieves the type of a TVB class for a given entity.
hangident	Indent a string by a specified amount.
intersection	Computes the intersection of two lists.
render_using_iri	Renders the ontology objects using their IRIs.
render_using_label	Renders the ontology objects using their labels.
search_class	Searches for an ontology class using a given label.
select_variables	Selects variables from a list based on a given property.
wrap_text	Pretty print a string with automatic line breaks at specified intervals,

compare_models

knowledge.ontology.compare_models(model1, model2, by='ParameterCatalogue')

Compares two TVB models based on their parameters or another specified metric.

Parameters

Name	Type	Description	Default
model1	owlready2.ThingClass or str	The first TVB model for comparison.	required
model2	owlready2.ThingClass or str	The second TVB model for comparison.	required
by	str	The metric to use for comparison. Default is “ParameterCatalogue”.	`'ParameterCatalogue'`

Returns

Name	Type	Description
	pd.DataFrame	pandas.DataFrame: A dataframe comparing the two TVB models based on the specified metric.

disintersection

knowledge.ontology.disintersection(lst1, lst2)

Computes the unique elements of two lists.

Parameters

Name	Type	Description	Default
lst1	list	The first list.	required
lst2	list	The second list.	required

Returns

Name	Type	Description
list	list	The elements that are unique to each list.

filter_cls_list

knowledge.ontology.filter_cls_list(cls_list, by)

Filters out classes from a list that have a specific ancestor.

Parameters

Name	Type	Description	Default
cls_list	list	The list of classes to be filtered.	required
by	owlready2.ThingClass	The ancestor class to filter by.	required

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The filtered list of classes.

find_best_fuzzy_match

knowledge.ontology.find_best_fuzzy_match(target, cls_list)

Find the best fuzzy match for a target string in a list of strings, prioritizing strings that start with the target followed by an underscore.

Parameters

Name	Type	Description	Default
target	str	The target string to match.	required
cls_list	list of str	The list of strings to search.	required

Returns

Name	Type	Description
str	owlready2.ThingClass	The string from the list that best matches the target.

find_variables

knowledge.ontology.find_variables(
    var,
    model,
    type='all',
    include_synonyms=False,
    find_best_match=True,
)

Finds a variable in a TVB model. Parameters: var (str): The variable to find. model (owlready2.ThingClass or str): The TVB model to search in. type (str, optional): The type of variable to find. Default is “all”. include_synonyms (bool, optional): If True, includes synonyms in the search. Default is False. find_best_match (bool, optional): If True, finds the best fuzzy match if multiple matches are found. Default is True. Returns: owlready2.ThingClass or None: The found variable class, or None if not found.

find_version

knowledge.ontology.find_version()

Retrieves the package version from the __init__.py file.

Returns

Name	Type	Description
str	str	The version of the TVBO package.

Raises

Name	Type	Description
	RuntimeError	If the version cannot be found in the `__init__.py` file.

get_def

knowledge.ontology.get_def(cls, mode='short')

Retrieve the description or definition of a class based on the specified mode.

This function fetches either a short description or a long definition of the given class. If the requested type (short or long) is not available, it attempts to fetch the other type.

Parameters

cls : class The class for which the description or definition is being retrieved. mode : str, optional The mode specifying the type of text to retrieve: ‘short’ for a brief description or ‘long’ for a detailed definition. The default is ‘short’.

Returns

str The description or definition of the class. If neither is available, it returns None.

get_default_values

knowledge.ontology.get_default_values(NMM, tvb_name=False, class_as_key=False)

Retrieves the default values for a given TVB model’s parameters.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the default values for.	required
tvb_name	bool	If True, uses the TVB name for the parameter. Default is False.	`False`

Returns

Name	Type	Description
dict	Dict[str, Union[float, bool, int]]	A dictionary of parameter names and their default values.

get_definition

knowledge.ontology.get_definition(tvbo_class)

Retrieves the definition for a given ontology class.

Parameters

Name	Type	Description	Default
tvbo_class	owlready2.ThingClass or str	The ontology class to retrieve the definition for.	required

Returns

Name	Type	Description
str	str	The definition for the given ontology class.

get_model

knowledge.ontology.get_model(label='JansenRit', model_type='NMM', verbose=False)

Retrieves a specific TVB-O model using its label.

Parameters

Name	Type	Description	Default
label	str	The label of the model to retrieve. Default is “JansenRit”.	`'JansenRit'`
model_type	str	The type of model to retrieve. Default is “NMM”.	`'NMM'`

Returns

Name	Type	Description
	owlready2.ThingClass	owlready2.ThingClass: The ontology class for the specified model.

get_model_acronym

knowledge.ontology.get_model_acronym(NMM)

Retrieves the acronym for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the acronym for.	required

Returns

Name	Type	Description
str	Optional[str]	The acronym for the given TVB model.

get_model_arguments

knowledge.ontology.get_model_arguments(NMM)

Retrieves the arguments for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the arguments for.	required

Returns

Name	Type	Description
dict	Dict[str, owlready2.ThingClass]	A dictionary of argument labels and their corresponding ontology class objects.

get_model_coefficients

knowledge.ontology.get_model_coefficients(NMM)

Retrieves the coefficients for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the coefficients for.	required

Returns

Name	Type	Description
dict	Dict[str, owlready2.ThingClass]	A dictionary of coefficient labels and their corresponding ontology class objects.

get_model_coupling_terms

knowledge.ontology.get_model_coupling_terms(
    NMM,
    only_global=True,
    return_as_dict=True,
)

Retrieves the coupling terms for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the coupling terms for.	required

Returns

Name	Type	Description
dict	Union[Dict[str, owlready2.ThingClass], List[owlready2.ThingClass]]	A dictionary of coupling term labels and their corresponding ontology class objects.

get_model_cvars

knowledge.ontology.get_model_cvars(NMM, return_as_dict=True)

Retrieves the cvars (coupling variables) for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the cvars for.	required

Returns

Name	Type	Description
list	Union[Dict[str, owlready2.ThingClass], List[owlready2.ThingClass]]	The cvars for the given TVB model.

get_model_derivatives

knowledge.ontology.get_model_derivatives(NMM, return_as_dict=True)

Retrieves the derivatives for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the derivatives for.	required

Returns

Name	Type	Description
dict	Union[Dict[str, owlready2.ThingClass], List[owlready2.ThingClass]]	A dictionary of derivative labels and their corresponding ontology class objects.

get_model_functions

knowledge.ontology.get_model_functions(NMM)

Retrieves the functions for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the functions for.	required

Returns

Name	Type	Description
dict	Dict[str, owlready2.ThingClass]	A dictionary of function labels and their corresponding ontology class objects.

get_model_parameters

knowledge.ontology.get_model_parameters(NMM, return_as_dict=True)

Retrieves the parameters for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the parameters for.	required

Returns

Name	Type	Description
dict	Union[Dict[str, owlready2.ThingClass], List[owlready2.ThingClass]]	A dictionary of parameter labels and their corresponding ontology class objects.

get_model_statevariables

knowledge.ontology.get_model_statevariables(NMM, return_as_dict=True)

Retrieves the state variables for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the state variables for.	required
return_as_dict	bool	If True, returns the state variables as a dictionary. Default is True.	`True`

Returns

Name	Type	Description
dict	Union[Dict[str, owlready2.ThingClass], List[owlready2.ThingClass]]	A dictionary of state variable labels and their corresponding ontology class objects.

get_model_suffix

knowledge.ontology.get_model_suffix(NMM)

Retrieves the suffix for a given TVB model, based on its acronym.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the suffix for.	required

Returns

Name	Type	Description
str	str	The suffix for the given TVB model.

get_model_variables

knowledge.ontology.get_model_variables(NMM)

Retrieves the variables for a given TVB model.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve the variables for.	required

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The list of variables for the given TVB model.

get_models

knowledge.ontology.get_models(model_type='NMM', from_df=False)

Retrieves all TVB-O models of a given type.

Parameters

Name	Type	Description	Default
model_type	str	The type of model to retrieve. Default is “NMM”.	`'NMM'`
from_df	bool	If True, retrieves models from a dataframe. Default is False.	`False`

Returns

Name	Type	Description
dict	Dict[str, owlready2.ThingClass]	A dictionary of model labels and their corresponding ontology class objects.

get_parameters_by_catalogue

knowledge.ontology.get_parameters_by_catalogue(NMM, param_key)

Retrieves parameters for a given TVB model, based on a specified parameter catalogue.

Parameters

Name	Type	Description	Default
NMM	owlready2.ThingClass or str	The TVB model to retrieve parameters for.	required
param_key	str	The parameter catalogue to use for retrieving parameters.	required

Returns

Name	Type	Description
	pd.DataFrame	pandas.DataFrame: A dataframe of parameters, their definitions, and their categories.

get_property_annotation

knowledge.ontology.get_property_annotation(tvbo_class, property)

Retrieves annotations for a given ontology class and property.

Parameters

Name	Type	Description	Default
tvbo_class	owlready2.ThingClass or str	The ontology class to retrieve annotations for.	required
property	str	The property to retrieve annotations for.	required

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The annotations for the given ontology class and property.

get_range

knowledge.ontology.get_range(variable, return_array=False)

Retrieves the range for a given ontology variable.

Parameters

Name	Type	Description	Default
variable	owlready2.ThingClass or str	The ontology variable to retrieve the range for.	required
return_array	bool	If True, returns the range as an array. Default is False.	`False`

Returns

Name	Type	Description
	Union[Tuple, np.ndarray]	tuple or numpy.ndarray: The range for the given ontology variable.

get_sorted_dict

knowledge.ontology.get_sorted_dict(class_list)

Creates a dictionary from a list of ontology classes. The dictionary’s keys are the class labels and its values are the class objects. The dictionary is sorted alphabetically based on its keys.

Parameters

Name	Type	Description	Default
class_list	list	The list of ontology classes.	required

Returns

Name	Type	Description
dict	dict	A sorted dictionary of class labels and their corresponding class objects.

get_subclass_list

knowledge.ontology.get_subclass_list(cls, level=1, exclude_cls=None)

Retrieves subclasses for a given ontology class, up to a specified depth.

Parameters

Name	Type	Description	Default
cls	owlready2.ThingClass	The ontology class to retrieve subclasses for.	required
level	int	The depth to retrieve subclasses up to. Default is 1.	`1`
exclude_cls	owlready2.ThingClass	A class to exclude from the results. Default is None.	`None`

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The list of subclasses for the given ontology class.

get_subclasses

knowledge.ontology.get_subclasses(tvbo_class, recursive=False)

Retrieves the subclasses for a given TVB-O class.

Parameters

Name	Type	Description	Default
tvbo_class	owlready2.ThingClass	The TVB-O class to retrieve subclasses for.	required
recursive	bool	If True, retrieves subclasses recursively. Default is False.	`False`

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The list of subclasses for the given TVB-O class.

get_superclasses

knowledge.ontology.get_superclasses(tvbo_class)

Retrieves the superclasses for a given TVB-O class.

Parameters

Name	Type	Description	Default
tvbo_class	owlready2.ThingClass	The TVB-O class to retrieve superclasses for.	required

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The list of superclasses for the given TVB-O class.

get_type

knowledge.ontology.get_type(c)

Retrieves the type of a TVB class for a given entity.

Parameters

Name	Type	Description	Default
c	owlready2.ThingClass	The TVB class instance.	required

Returns

Name	Type	Description
str	owlready2.ThingClass	The type of the TVB entity.

hangident

knowledge.ontology.hangident(text, indent=4)

Indent a string by a specified amount.

Parameters

Name	Type	Description	Default
text	str	The text to be indented.	required
indent	int	The amount to indent the text by.	`4`

intersection

knowledge.ontology.intersection(lst1, lst2)

Computes the intersection of two lists.

Parameters

Name	Type	Description	Default
lst1	list	The first list.	required
lst2	list	The second list.	required

Returns

Name	Type	Description
list	list	The intersection of the two given lists.

render_using_iri

knowledge.ontology.render_using_iri(entity)

Renders the ontology objects using their IRIs.

Parameters

Name	Type	Description	Default
entity	owlready2.entity	The ontology class or entity to be rendered.	required

Returns

Name	Type	Description
str	str	The IRI of the given ontology entity.

render_using_label

knowledge.ontology.render_using_label(entity)

Renders the ontology objects using their labels.

Parameters

Name	Type	Description	Default
entity	owlready2.entity	The ontology class or entity to be rendered.	required

Returns

Name	Type	Description
str	str	The label of the given ontology entity.

search_class

knowledge.ontology.search_class(label)

Searches for an ontology class using a given label.

Parameters

Name	Type	Description	Default
label	str	The label to search for, with regex support.	required

Returns

Name	Type	Description
	Union[owlready2.ThingClass, owlready2.triplelite._SearchList]	owlready2.ThingClass or owlready2.triplelite._SearchList:
	Union[owlready2.ThingClass, owlready2.triplelite._SearchList]	The ontology class(es) that match the given label.

select_variables

knowledge.ontology.select_variables(variables, property)

Selects variables from a list based on a given property.

Parameters

Name	Type	Description	Default
variables	list	The list of variables to select from.	required
property	str	The property to use for selecting variables.	required

Returns

Name	Type	Description
list	List[owlready2.ThingClass]	The selected variables.

wrap_text

knowledge.ontology.wrap_text(text, line_length=100, line_breaks='\n')

Pretty print a string with automatic line breaks at specified intervals, while preserving existing new lines.

Parameters

Name	Type	Description	Default
text	str	The text to be printed.	required
line_length	int	The maximum length of each line.	`100`