The Virtual Brain Project

Table Of Contents

Previous topic

project_update_scripts Package

Next topic

traits Package

This Page

services Package

This module contains the ‘services’ layer in TVB application.

Most of the business logic happens here; which is agnostic of the UI.



Bases: object

Simple class, to mimic the same behavior we are expecting from StandAloneClient, but firing behind the cluster job scheduling process..

static execute(operation_id, user_name_label, adapter_instance)[source]

Call the correct system command to submit a job to the cluster.

static stop_operation(operation_id)[source]

Stop a thread for a given operation id


Bases: threading.Thread

Thread in charge for starting an operation, used both on cluster and with stand-alone installations.


Get the required data from the operation queue and launch the operation.


Mark current thread for stop

static stop_pid(pid)[source]

Stop a process specified by PID. :returns: True when specified Process was stopped in here, False in case of exception(e.g. process stopped in advance).


Check if current thread was marked for stop.


Bases: object

Instead of communicating with a back-end cluster, fire locally a new thread.

static execute(operation_id, user_name_label, adapter_instance)[source]

Start asynchronous operation locally

static stop_operation(operation_id)[source]

Stop a thread for a given operation id


Service for serianlizing a Burst (Simulator) configuration.


Bases: object

Constructs data types based on a burst configuration. Updates the burst configuration.


Prepare Connectivity


Prepare Surface

static group_parameter_values_by_name(model_parameters_list)[source]
@:param model_parameters_list: Given a list of model parameters like this:
[{“a”: 2.0, ‘b’: 1.0},
{“a”: 3.0, ‘b’: 7.0}])
@:return: This method will group them by param name to get:
{‘a’: [2.0, 3.0], ‘b’: [1.0, 7.0]}

Returns True if the burst configuration describes a range on a model parameter

Returns:A model and an integrator.
Return type:Model, Integrator
write_model_parameters(model_name, model_parameters_list)[source]

Update model parameters in burst config.

  • model_name – This model will be selected in burst
  • model_parameters_list – A list of model parameter configurations. One for each connectivity node. Ex. [{‘a’: 1, ‘b’: 2}, ...]

Set noise dispersions in burst config. It will set all nsig fields it can find in the config (at least 1 per stochastic integrator). :param noise_dispersions: A list of noise dispersions. One for each connectivity node. Ex [{‘V’: 1, ‘W’:2}, ...]



Bases: object

Service layer for Burst related entities.

build_portlet_interface(portlet_configuration, project_id)[source]

From a portlet_id and a project_id, first build the portlet entity then get it’s configurable interface.

  • portlet_configuration – a portlet configuration entity. It holds at the least the portlet_id, and in case any default parameters were saved they can be rebuilt from the analyzers // visualizer parameters
  • project_id – the id of the current project

the portlet interface will be of the following form:: [{‘interface’: adapter_interface, ‘prefix’: prefix_for_parameter_names, ‘subalg’: {algorithm_field_name: default_algorithm_value}, ‘algo_group’: algorithm_group, ‘alg_ui_name’: displayname}, ......] A list of dictionaries for each adapter that makes up the portlet.

cancel_or_remove_burst(*args, **kwargs)[source]

Cancel (if burst is still running) or Remove the burst given by burst_id. :returns True when Remove operation was done and False when Cancel

static get_available_bursts(project_id)[source]

Return all the burst for the current project.

static get_available_portlets()[source]
Returns:a list of all the available portlet entites
static get_portlet_by_id(portlet_id)[source]
Returns:the portlet entity with the id =@portlet_id
static get_portlet_by_identifier(portlet_identifier)[source]
Returns:the portlet entity with the algorithm identifier =@portlet_identifier
static get_portlet_status(portlet_cfg)[source]

Get the status of a portlet configuration.

launch_burst(burst_configuration, simulator_index, simulator_id, user_id, launch_mode='new')[source]

Given a burst configuration and all the necessary data do the actual launch.

  • burst_configuration – BurstConfiguration
  • simulator_index – the position within the workflows step list that the simulator will take. This is needed so that the rest of the portlet workflow steps know what steps do their dynamic parameters come from.
  • simulator_id – the id of the simulator adapter as stored in the DB. It’s needed to load the simulator algo group and category that are then passed to the launcher’s prepare_operation method.
  • user_id – the id of the user that launched this burst
  • launch_mode – new/branch/continue
static launch_visualization(visualization, frame_width=None, frame_height=None, is_preview=True)[source]
Parameters:visualization – a visualization workflow step
Parameters:burst_id – the id of the burst that should be loaded

Having this input the method should:

  • load the entity from the DB

  • get all the workflow steps for the saved burst id

  • go trough the visualization workflow steps to create the tab

    configuration of the burst using the tab_index and index_in_tab fields saved on each workflow_step

load_tab_configuration(burst_entity, op_id)[source]

Given a burst entity and an operation id, find the workflow to which the op_id belongs and the load the burst_entity’s tab configuration with those workflow steps.


Return a new burst configuration entity with all the default values.

new_portlet_configuration(portlet_id, tab_nr=-1, index_in_tab=-1, portlet_name='Default')[source]

Return a new portlet configuration entity with default parameters.

  • portlet_id – the id of the portlet for which a configuration will be stored
  • tab_nr – the index of the currently selected tab
  • index_in_tab – the index from the currently selected tab
static populate_burst_disk_usage(bursts)[source]

Adds a disk_usage field to each burst object. The disk usage is computed as the sum of the datatypes generated by a burst

static rename_burst(burst_id, new_name)[source]

Rename the burst given by burst_id, setting it’s new name to burst_name.


Stop all the entities for the current burst and set the burst status to canceled.


For each burst_id received in the id_list read new status from DB and return a list [id, new_status] pair.

update_portlet_configuration(portlet_configuration, submited_parameters)[source]
  • portlet_configuration – the portlet configuration that needs to be updated
  • submited_parameters – a list of parameters as submitted from the UI. This is a dictionary in the form : {‘dynamic’ : {name:value pairs}, ‘static’ : {name:value pairs}}

All names are prefixed with adapter specific generated prefix.

email_sender, address_to, email_subject, email_content)[source]

Sends an Email Message


Exceptions for services layer of the application.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem at project import.

exception, parent_exception=None)[source]


Exception thrown in cases related to wrong portlet configurations.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem at project import.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem related to Launching and Executing TVB specific Operations.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem at project import.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem in the projectservice module.

exception, parent_exception=None)[source]


Exception to be thrown in case some one tries to remove an entity that is used by other entities.

exception, parent_exception=None)[source]

Bases: tvb.basic.traits.exceptions.TVBException

Base Exception class for Services layer in the application.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem related to Structure Storage.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem related to creating or managing a user.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem related to creating or managing a workflow.

exception, parent_exception=None)[source]


Exception to be thrown in case of a problem happened between steps of a workflow. Status ERROR needs to be reported at a top level (e.g. Burst) as workflow steps individually can not be made responsible.


Service layer, for storing/retrieving Resulting Figures in TVB.


Service layer for Figure entities.

edit_result_figure(figure_id, **data)[source]

Retrieve and edit a previously stored figure.

static load_figure(figure_id)[source]

Loads a stored figure by its id.


Remove figure from DB and file storage.

retrieve_result_figures(project, user, selected_session_name='all_sessions')[source]

Retrieve from DB all the stored Displayer previews that belongs to the specified session. The previews are for current user and project; grouped by session.

store_result_figure(project, user, img_type, export_data, image_name=None, operation_id=None)[source]

Store into a file, Result Image and reference in DB.


Service layer, for executing computational steps in the application. Code related to launching/duplicating operations is placed here.


Service Layer for all TVB generic Work-Flow operations.

For a list of dataType IDs and a project id create all the required links.

fire_operation(adapter_instance, current_user, project_id, visible=True, **data)[source]

Launch an operation, specified by AdapterInstance, for CurrentUser, Current Project and a given set of UI Input Data.

static get_algorithm_by_identifier(ident)[source]

Retrieve Algorithm entity by ID. Return None, if ID is not found in DB.

static get_algorithm_by_module_and_class(module, classname)[source]

Get the db entry from the algorithm table for the given module and class.

Returns:list of AlgorithmTransientGroup entities
static get_available_datatypes(project_id, data_type_cls, filters=None)[source]

Return all dataTypes that match a given name and some filters. :param data_type_cls: either a fully qualified class name or a class object


Pass to DAO the retrieve of category by ID operation.

static get_generic_entity(entity_type, filter_value, select_field)[source]
Parameters:datatype_gid – Filter only algorithms compatible with this GUID
Returns:dict(category_name: List AlgorithmTransientGroup)
static get_operation_numbers(proj_id)[source]

Count total number of operations started for current project.

static get_raw_categories()[source]
Returns:AlgorithmCategory list of entities that have results in RAW state (Creators/Uploaders)
static get_selections_for_project(project_id, datatype_gid)[source]

Retrieved from DB saved selections for current project. If a certain selection doesn’t have all the labels between the labels of the given connectivity than this selection will not be returned. :returns: List of ConnectivitySelection entities.

static get_stored_pse_filters(datatype_group_gid)[source]
static get_upload_algorithms()[source]
Returns:List of StoredAdapter entities
static get_visualisers_category()[source]

Retrieve all Algorithm categories, with display capability

static load_operation(operation_id)[source]

Retrieve previously stored Operation from DB, and load operation.burst attribute

prepare_adapter(project_id, stored_adapter)[source]

Having a StoredAdapter, return the Tree Adapter Interface object, populated with datatypes from ‘project_id’.

Remove the link from the datatype given by dt_id to project given by project_id.

static save_measure_points_selection(ui_name, selected_nodes, datatype_gid, project_id)[source]

Store in DB a ConnectivitySelection.

static save_pse_filter(ui_name, datatype_group_gid, threshold_value, applied_on)[source]

Store in DB a PSE filter.



Bases: object

Service for importing TVB entities into system. It supports TVB exported H5 files as input, but it should also handle H5 files generated outside of TVB, as long as they respect the same structure.

import_project_operations(project, import_path, dt_burst_mappings=None, burst_ids_mapping=None)[source]

This method scans provided folder and identify all operations that needs to be imported

import_project_structure(*args, **kwargs)[source]

Execute import operations:

  1. check if ZIP or folder

  2. find all project nodes

  3. for each project node:
    • create project
    • create all operations
    • import all images
    • create all dataTypes
import_workflow_steps(workflow, wf_steps, view_steps)[source]

Import all workflow steps for the given workflow. We create both wf_steps and view_steps in the same method, since if a wf_step has to be omited for some reason, we also need to omit that view step. :param workflow: a model.Workflow entity from which we need to add workflow steps

  • wf_steps – a list of WorkflowStepInformation entities, from which we will rebuild the workflow steps
  • view_steps – a list of WorkflowViewStepInformation entities, from which we will rebuild the workflow view steps
import_workflows(project, bursts_dict, burst_ids_mapping)[source]

Import the workflow entities for all bursts imported in the project.

  • project – the current
  • bursts_dict – a dictionary that holds all the required information in order to import the bursts from the new project
  • burst_ids_mapping – a dictionary of the form {old_burst_id : new_burst_id} so we know what burst to link each workflow to
load_burst_entity(json_burst, project_id)[source]

Load BurstConfiguration from JSON (possibly exported from a different machine). Nothing gets persisted in DB or on disk.

  • json_burst – Burst JSON export
  • project_id – Current project ID (it will be used if the user later starts this simulation)

BurstConfiguration filled from JSON

load_datatype_from_file(storage_folder, file_name, op_id, datatype_group=None, move=True)[source]

Creates an instance of datatype from storage / H5 file :returns: datatype


This method stores data type into DB

initializer, skip_import=False)[source]

Initialize when Application is starting. Check for new algorithms or new DataTypes.[source]

Service Layer for Database reset.


Module in charge with Launching an operation (creating the Operation entity as well, based on gathered parameters).


Class responsible for preparing an operation launch. It will prepare parameters, and decide if the operation is to be executed immediately, or to be sent on the cluster.

ATT_UID = 'uid'
get_range_values(kwargs, ranger_name)[source]

For the ranger given by ranger_name look in kwargs and return the array with all the possible values.

group_operation_launch(user_id, project_id, algorithm_id, category_id, existing_dt_group=None, **kwargs)[source]

Create and prepare the launch of a group of operations.

initiate_operation(current_user, project_id, adapter_instance, temporary_storage, visible=True, **kwargs)[source]

Gets the parameters of the computation from the previous inputs form, and launches a computation (on the cluster or locally).

Invoke custom method on an Adapter Instance. Make sure when the operation has finished that the correct results are stored into DB.

initiate_prelaunch(operation, adapter_instance, temp_files, **kwargs)[source]

Public method. This should be the common point in calling an adapter- method.

launch_operation(operation_id, send_to_cluster=False, adapter_instance=None)[source]

Method exposed for Burst-Workflow related calls. It is used for cascading operation in the same workflow.

prepare_operations(user_id, project_id, algorithm, category, metadata, visible=True, existing_dt_group=None, **kwargs)[source]

Do all the necessary preparations for storing an operation. If it’s the case of a range of values create an operation group and multiple operations for each possible instance from the range. :param metadata: Initial MetaData with potential Burst identification inside.

prepare_operations_for_workflowsteps(workflow_step_list, workflows, user_id, burst_id, project_id, group, sim_operations)[source]

Create and store Operation entities from a list of Workflow Steps. Will be generated workflows x workflow_step_list Operations. For every step in workflow_step_list one OperationGroup and one DataTypeGroup will be created (in case of PSE).


Stop the operation given by the operation id.


Service Layer for the Project entity.


Services layer for Project entities.

static count_datatypes_generated_from(datatype_gid)[source]

A list with all the datatypes resulted from operations that had as input the datatype given by ‘datatype_gid’.

static count_filtered_operations(project_id, filters=None)[source]

Pass to DAO counters for filtered operations


Simply retrieve Project entity from Database.

static get_all_operations_for_uploaders(project_id)[source]

Returns all finished upload operations.

get_datatype_and_datatypegroup_inputs_for_operation(operation_gid, selected_filter)[source]

Returns the dataTypes that are used as input parameters for the given operation. ‘selected_filter’ - is expected to be a visibility filter.

If any dataType is part of a dataType group then the dataType group will be returned instead of that dataType.

static get_datatype_by_id(datatype_id)[source]

Retrieve a DataType DB reference by its id.

static get_datatype_details(datatype_gid)[source]
Returns:an array. First entry in array is an instance of DataTypeOverlayDetails The second one contains all the possible states for the specified dataType.
static get_datatype_in_group(group)[source]

Return all dataTypes that are the result of the same DTgroup.

static get_datatypegroup_by_gid(datatypegroup_gid)[source]

Returns the DataTypeGroup with the specified gid.

static get_datatypegroup_by_op_group_id(operation_group_id)[source]

Returns the DataTypeGroup with the specified id.

static get_datatypes_from_datatype_group(datatype_group_id)[source]

Retrieve all dataType which are part from the given dataType group.

get_datatypes_inputs_for_operation_group(group_id, selected_filter)[source]

Returns the dataType inputs for an operation group. If more dataTypes are part of the same dataType group then only the dataType group will be returned instead of them.

static get_filterable_meta()[source]

Contains all the attributes by which the user can structure the tree of DataTypes

static get_linkable_projects_for_user(user_id, data_id)[source]

Find projects with are visible for current user, and in which current datatype hasn’t been linked yet.

get_operation_details(operation_gid, is_group)[source]
Returns:an entity OperationOverlayDetails filled with all information for current operation details.
static get_operation_group_by_gid(operation_group_gid)[source]

Loads OperationGroup from DB

static get_operation_group_by_id(operation_group_id)[source]

Loads OperationGroup from DB

static get_operations_for_datatype(datatype_gid, visibility_filter, only_in_groups=False)[source]

Returns all the operations which uses as an input parameter the dataType with the specified GID.

If only_in_groups is True than this method will return only the operations that are part from an operation group, otherwise it will return only the operations that are NOT part of an operation group.

static get_operations_for_datatype_group(datatype_group_id, visibility_filter, only_in_groups=False)[source]

Returns all the operations which uses as an input parameter a dataType from the given DataTypeGroup. visibility_filter - is a filter used for retrieving all the operations or only the relevant ones.

If only_in_groups is True than this method will return only the operations that are part from an operation group, otherwise it will return only the operations that are NOT part of an operation group.

static get_operations_in_group(operation_group)[source]

Return all the operations from an operation group.

get_project_structure(project, visibility_filter, first_level, second_level, filter_value)[source]

Find all DataTypes (including the linked ones and the groups) relevant for the current project. In case of a problem, will return an empty list.

static get_results_for_operation(operation_id, selected_filter=None)[source]

Retrieve the DataTypes entities resulted after the execution of the given operation.

static is_datatype_group(datatype_gid)[source]

Used to check if the dataType with the specified GID is a DataTypeGroup.

static is_upload_operation(operation_gid)[source]

Returns True only if the operation with the given GID is an upload operation.

static load_operation_by_gid(operation_gid)[source]

Retrieve loaded Operation from DB

remove_datatype(project_id, datatype_gid, skip_validation=False)[source]

Method used for removing a dataType. If the given dataType is a DatatypeGroup or a dataType from a DataTypeGroup than this method will remove the entire group. The operation(s) used for creating the dataType(s) will also be removed.


Remove a given operation

remove_project(*args, **kwargs)[source]

Remove Project from DB and File Storage.

retrieve_project_full(project_id, applied_filters=None, current_page=1)[source]

Return a Tuple with Project entity and Operations for current Project. :param project_id: Current Project Identifier :param applied_filters: Filters to apply on Operations :param current_page: Number for current page in operations

retrieve_projects_for_user(user_id, current_page=1)[source]

Return a list with all Projects visible for current user.

static set_datatype_visibility(datatype_gid, is_visible)[source]

Sets the dataType visibility. If the given dataType is a dataType group or it is part of a dataType group than this method will set the visibility for each dataType from this group.

set_operation_and_group_visibility(entity_gid, is_visible, is_operation_group=False)[source]

Sets the operation visibility.

If ‘is_operation_group’ is True than this method will change the visibility for all the operation from the OperationGroup with the GID field equal to ‘entity_gid’.

store_project(current_user, is_create, selected_id, **data)[source]

We want to create/update a project entity.


Update DataType/ DataTypeGroup metadata THROW StructureException when input data is invalid.[source]

Create Projects storage root folder in case it does not exist.


Service layer for saving/editing TVB settings.


Bases: object

Handle all TVB Setting related problems, at the service level.


Validate DB URL, that a connection can be done.

static get_disk_free_space(storage_path)[source]
Returns:the available HDD space in KB in TVB_STORAGE folder.

Check if new settings are correct. Make necessary changes, then save new data in configuration file.

Returns:two boolean values -there were any changes to the configuration; -a reset should be performed on the TVB relaunch.


Converts a color scheme texture image to json arrays, img_width, band_height)[source]
  • img_pth – Path to the texure
  • img_width – Texture width
  • band_height – Height of a color scheme band

A list of img_width/band_height color schemes. A scheme is a list of img_width colors


Service layer for USER entities.


CRUD methods for USER entities are here.

static check_login(username, password)[source]

Service layer to check if given UserName and Password are according to DB.

static compute_user_generated_disk_size(user_id)[source]
create_user(username=None, password=None, password2=None, role=None, email=None, comment=None, email_msg=None, validated=False, skip_import=False)[source]

Service Layer for creating a new user.


Delete a user with a given ID. Return True when successfully, or False.

edit_user(edited_user, old_password=None)[source]

Retrieve a user by and id, then modify it’s role and validate status.

static get_administrators()[source]

Retrieve system administrators. Will be used for sending emails, for example.

static get_user_by_id(user_id)[source]

Retrieves a user by its id.

get_users_for_project(user_name, project_id, page=1)[source]

Return tuple: (All Users except the project administrator, Project Members). Parameter “user_name” is the current user. Parameter “user_name” is used for new projects (project_id is None). When “project_id” not None, parameter “user_name” is ignored.

static is_username_valid(name)[source]

Service layer for checking if a given UserName is unique or not.


Service Layer for resetting a password.

static retrieve_all_users(username, current_page=1)[source]

Return all users from the database except the given user

static save_project_to_user(user_id, project_id)[source]

Mark for current user that the given project is the last one selected.

validate_user(name='', user_id=None)[source]

Service layer for editing a user and validating the account.



service layer for work-flow entity.

static create_and_store_workflow(project_id, burst_id, simulator_index, simulator_id, operations)[source]

Create and store the workflow given the project, user and burst in which the workflow is created. :param simulator_index: the index of the simulator in the workflow :param simulator_id: the id of the simulator adapter :param operations: a list with the operations created for the simulator steps

mark_burst_finished(burst_entity, burst_status=None, error_message=None)[source]

Mark Burst status field. Also compute ‘weight’ for current burst: no of operations inside, estimate time on disk...

  • burst_entity – BurstConfiguration to be updated, at finish time.
  • burst_status – BurstConfiguration status. By default BURST_FINISHED
  • error_message – If given, set the status to error and perpetuate the message.
persist_operation_state(operation, operation_status, message=None)[source]

Update Operation instance state. Store it in DB and on HDD/ :param operation: Operation instance :param operation_status: new status :param message: message in case of error :return: operation instance changed


If the operation with id ‘last_executed_op_id’ resulted after the execution of a workflow step then this method will launch the operation corresponding to the next step from the workflow.

static set_dynamic_step_references(workflow_step, step_reference)[source]
  • workflow_step – a valid instance of a workflow_step
  • step_reference – the step to which every dataType reference index should be set

For each dynamic parameter of the given workflow_step set the ‘step_index’ at step_reference.

static store_workflow_step(workflow_step)[source]

Store a workflow step entity.


Used for updating the state of an executed workflow. Only if the operation with the specified id has resulted after the execution of an ExecutedWorkflowStep than the state of the ExecutedWorkflow to which belongs the step will be updated.