# config { #tvbo.ontology.config }

`ontology.config`

TVB-O Model Configuration Module.

This module provides utility functions to configure and manage TVB neural mass models using ontology-based configurations.
These configurations can be applied to model objects to change their default behavior or parameterize them as per published studies or lab-tested configurations.

### Functions

- `get_default(NMM: str) -> dict`:
    Fetch default values for neural mass model parameters.

- `get_param_config(config_key: str, return_NMM: bool = False, use_classes: bool = False) -> Union[dict, Tuple[dict, str]]`:
    Fetch specific parameter configurations based on a reference key.

- `update_default(model_name: str, config_key: str) -> dict`:
    Update the default parameter configuration of a given model.

- `configure_model(tvb_model: tvb.simulator.models, config_key: str) -> tvb.simulator.models`:
    Apply a specific configuration to a TVB model object, altering its state variables and parameters.

### Usage

To fetch and apply configurations, use the respective functions:

```python
model_defaults = get_default("ExampleModel")
updated_defaults = update_default("ExampleModel", "custom_config")
configured_model = configure_model(model_instance, "custom_config")
```

## Dependencies

This module relies on the `ontology` module for fetching configurations. Ensure it's properly initialized and available.

## See Also

tvbo.ontology:
    For handling and fetching ontology-based configurations.

::: {.callout-note}
- Configurations are either sourced from peer-reviewed publications or have been extensively tested in labs.
- Ensure you've set up the environment and dependencies correctly for smooth operation of these utilities.
:::

## Classes

| Name | Description |
| --- | --- |
| [ModelConfiguration](#tvbo.ontology.config.ModelConfiguration) | A class that handles parameter settings for a given Neural Mass Model (NMM). |

### ModelConfiguration { #tvbo.ontology.config.ModelConfiguration }

```python
ontology.config.ModelConfiguration(NMM)
```

A class that handles parameter settings for a given Neural Mass Model (NMM).



#### Attributes: {.doc-section .doc-section-attributes}

model : ontology.NMM
    Neural Mass Model instance or identifier.
config : dict
    Configuration settings for the NMM.
config_key : str
    Key identifying the current configuration.
report : str
    Report generated by the `get_report` method.



#### Parameters {.doc-section .doc-section-parameters}

NMM : ontology.NMM or str
    An instance or identifier of the Neural Mass Model.



#### Methods: {.doc-section .doc-section-methods}

apply_config(config_key)
    Apply a new configuration based on the provided key.
get_report(format="latex", decimals=3, **kwargs)
    Generate a report for the current configuration.
save_report(path=".", format="latex", **kwargs)
    Save the generated report to a file.

#### Methods

| Name | Description |
| --- | --- |
| [apply_config](#tvbo.ontology.config.ModelConfiguration.apply_config) | Apply a new configuration based on the provided key. |
| [get_report](#tvbo.ontology.config.ModelConfiguration.get_report) | Generate a report for the current configuration. |
| [save_report](#tvbo.ontology.config.ModelConfiguration.save_report) | Save the generated report to a file. |

##### apply_config { #tvbo.ontology.config.ModelConfiguration.apply_config }

```python
ontology.config.ModelConfiguration.apply_config(config_key)
```

Apply a new configuration based on the provided key.



###### Parameters {.doc-section .doc-section-parameters}

config_key : str
    Key identifying the new configuration to apply.

##### get_report { #tvbo.ontology.config.ModelConfiguration.get_report }

```python
ontology.config.ModelConfiguration.get_report(
    format='latex',
    decimals=3,
    **kwargs,
)
```

Generate a report for the current configuration.



###### Parameters {.doc-section .doc-section-parameters}

format : str, optional
    Format of the report, by default "latex".
decimals : int, optional
    Number of decimal places to use in the report, by default 3.
**kwargs :
    Additional keyword arguments.



###### Returns: {.doc-section .doc-section-returns}

str
    Generated report.

##### save_report { #tvbo.ontology.config.ModelConfiguration.save_report }

```python
ontology.config.ModelConfiguration.save_report(
    path='.',
    format='latex',
    **kwargs,
)
```

Save the generated report to a file.



###### Parameters {.doc-section .doc-section-parameters}

path : str, optional
    Path to save the report, by default ".".
format : str, optional
    Format of the report, by default "latex".
**kwargs :
    Additional keyword arguments.

## Functions

| Name | Description |
| --- | --- |
| [configure_model](#tvbo.ontology.config.configure_model) | Apply specific parameter configuration stored in TVB-O. All configurations have been either published in a peer-reviewed journal or tested extensively in our lab. Each configuration has a specific reference with further information. |
| [get_coupling_parameters](#tvbo.ontology.config.get_coupling_parameters) | Collect the default parameters of a coupling function. |
| [get_default](#tvbo.ontology.config.get_default) | Retrieve the default values for a given Neural Mass Model (NMM). |
| [get_model_configurations](#tvbo.ontology.config.get_model_configurations) | List the configuration instances available for a model. |
| [get_param_config](#tvbo.ontology.config.get_param_config) | Retrieve the parameter configuration for a given configuration key. |
| [getattr_case_insensitive](#tvbo.ontology.config.getattr_case_insensitive) | Get the value of an attribute from an object, ignoring case sensitivity. |
| [update_default](#tvbo.ontology.config.update_default) | Update the default configuration for a specific model using a given configuration key. |

### configure_model { #tvbo.ontology.config.configure_model }

```python
ontology.config.configure_model(tvb_model, config_key)
```

Apply specific parameter configuration stored in TVB-O. All configurations have been either published in a peer-reviewed journal or tested extensively in our lab. Each configuration has a specific reference with further information.



#### Parameters {.doc-section .doc-section-parameters}

tvb_model : tvb.simulator.models
    TVB model object
config_key : str
    Reference-key for Parameter configuration.



#### Returns: {.doc-section .doc-section-returns}

tvb.simulator.models
    Updated model instance with parameter values according to specific configuration.

### get_coupling_parameters { #tvbo.ontology.config.get_coupling_parameters }

```python
ontology.config.get_coupling_parameters(CF)
```

Collect the default parameters of a coupling function.

#### Parameters {.doc-section .doc-section-parameters}

| Name   | Type   | Description                                                                                                                        | Default    |
|--------|--------|------------------------------------------------------------------------------------------------------------------------------------|------------|
| CF     |        | The coupling function, either as an ontology coupling-function object or as a string identifier that is resolved via the ontology. | _required_ |

#### Returns {.doc-section .doc-section-returns}

| Name   | Type   | Description                                                           |
|--------|--------|-----------------------------------------------------------------------|
|        |        | A dictionary mapping each parameter name to its default value. The    |
|        |        | coupling-function acronym suffix (`_<acronym>`) is stripped from each |
|        |        | parameter label, and parameters without a default value fall back to  |
|        |        | `1`.                                                                  |

### get_default { #tvbo.ontology.config.get_default }

```python
ontology.config.get_default(NMM)
```

Retrieve the default values for a given Neural Mass Model (NMM).

If the provided NMM is a string identifier, it attempts to fetch the actual NMM instance.
It then collects the default values for each descendant class of the NMM.



#### Parameters {.doc-section .doc-section-parameters}

NMM : ontology.NMM or str
    An instance or identifier of the Neural Mass Model.



#### Returns: {.doc-section .doc-section-returns}

dict
    A dictionary with descendant classes of the NMM as keys and their corresponding default values as values.



#### Examples: {.doc-section .doc-section-examples}

>>> get_default("some_NMM_identifier")
{<descendant_class1>: 0.5, <descendant_class2>: 1.2, ...}

### get_model_configurations { #tvbo.ontology.config.get_model_configurations }

```python
ontology.config.get_model_configurations(model)
```

List the configuration instances available for a model.

#### Parameters {.doc-section .doc-section-parameters}

| Name   | Type   | Description                                                                                                            | Default    |
|--------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| model  |        | The Neural Mass Model, either as an ontology model object or as a string identifier that is resolved via the ontology. | _required_ |

#### Returns {.doc-section .doc-section-returns}

| Name   | Type   | Description                                                            |
|--------|--------|------------------------------------------------------------------------|
|        |        | A list of unique `ModelConfiguration` instances that declare the given |
|        |        | model among their classes.                                             |

### get_param_config { #tvbo.ontology.config.get_param_config }

```python
ontology.config.get_param_config(
    config_key='default',
    model=None,
    return_NMM=False,
    use_classes=False,
)
```

Retrieve the parameter configuration for a given configuration key.

This function searches the ontology for the provided configuration key and returns a dictionary with the relevant parameter details. Additionally, it checks for ancestors related to Neural Mass Model (NMM) and fetches the relevant variables and instances associated with the configuration.



#### Parameters {.doc-section .doc-section-parameters}

config_key : str
    The key for which the configuration details are to be fetched.
return_NMM : bool, optional
    If True, returns the Neural Mass Model associated with the configuration. Default is False.
use_classes : bool, optional
    If True, the labels in the returned dictionary will use class objects instead of string labels. Default is False.



#### Returns: {.doc-section .doc-section-returns}

dict or tuple
    If `return_NMM` is False:
        A dictionary with the configuration details.
    If `return_NMM` is True:
        A tuple where the first element is the configuration details dictionary and the second is the NMM.



#### Examples: {.doc-section .doc-section-examples}

>>> get_param_config("some_config_key")
{'some_variable': {'category': 'State Variable', 'range': [0.5, 1.2]}}

>>> get_param_config("some_config_key", return_NMM=True)
({'some_variable': {'category': 'State Variable', 'range': [0.5, 1.2]}}, 'NMM_instance')

### getattr_case_insensitive { #tvbo.ontology.config.getattr_case_insensitive }

```python
ontology.config.getattr_case_insensitive(obj, attr_name, default=None)
```

Get the value of an attribute from an object, ignoring case sensitivity.

This function searches for an attribute with a case-insensitive match to the given `attr_name` within the `obj` object. If a match is found, the corresponding value is returned. If no match is found, the `default` value is returned.

:param obj: The object to search for the attribute.
:param attr_name: The name of the attribute to search for.
:param default: The default value to return if no matching attribute is found.
:return: The value of the matching attribute or the default value.

### update_default { #tvbo.ontology.config.update_default }

```python
ontology.config.update_default(model_name, config_key=None, config_dict=None)
```

Update the default configuration for a specific model using a given configuration key.

This function first fetches the default values for the provided model using the ontology.
If the config_key is "default", it returns the fetched default values.
Otherwise, it retrieves the parameter configuration associated with the config_key and updates the default values accordingly.



#### Parameters {.doc-section .doc-section-parameters}

model_name : str
    The name of the model for which the default values need to be updated.
config_key : str
    The reference key for the parameter configuration that will be used to update the default values.



#### Returns: {.doc-section .doc-section-returns}

dict
    The updated default configuration values for the model. If config_key is "default", the original default values are returned.



#### Examples: {.doc-section .doc-section-examples}

>>> update_default("example_model", "default")
{'param1': 1.2, 'param2': 2.3}

>>> update_default("example_model", "custom_config")
{'param1': 1.8, 'param2': 2.3}



#### Notes: {.doc-section .doc-section-notes}

The function makes use of `ontology` for its operations. Ensure that `ontology` is properly initialized and contains the required data.