EMMAA’s Database (emmaa.db)

The Database Schema (emmaa.db.schema)

class emmaa.db.schema.User(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base, emmaa.db.schema.EmmaaTable

A table containing users of EMMAA: User(_id_, email)

Parameters:

• id (int) – (from indralab_auth_tools.src.models.User.id, primary key) A database-generated integer from the User table in indralab auth tools.
• email (str) – The email of the user (must be unique)

class emmaa.db.schema.Query(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base, emmaa.db.schema.EmmaaTable

Queries run on each model: Query(_hash_, model_id, json, qtype)

The hash column is a hash generated from the json and model_id columns that can be derived from the

Parameters:

• hash (big-int) – (primary key) A 32 bit integer generated from the json and model_id.
• model_id (str) – (20 character) The short id/acronym for the given model.
• json (json) – A json dict containing the relevant parameters defining the query.

class emmaa.db.schema.UserQuery(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base, emmaa.db.schema.EmmaaTable

A table linking users to queries:

UserQuery(_id_, user_id, query_hash, date, subscription, count)

Parameters:

• id (int) – (auto, primary key) A database-assigned integer id.
• user_id (int) – (foreign key -> User.id) The id of the user related to this query.
• query_hash (big-int) – (foreign key -> Query.hash) The hash of the query json, which can be directly generated.
• date (datetime) – (auto) The date that this entry was added to the database.
• subscription (bool) – Record whether the user has subscribed to see results of this model.
• count (int) – Record the number of times the user associated with user id has done this query

class emmaa.db.schema.Result(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base, emmaa.db.schema.EmmaaTable

Results of queries to models:

Result(_id_, query_hash, date, result_json, mc_type, all_result_hashes, delta)

Parameters:

• id (int) – (auto, primary key) A database-assigned integer id.
• query_hash (big-int) – (foreign key -> Query.hash) The hash of the query json, which can be directly generated.
• date (datetime) – (auto) The date the result was entered into the database.
• result_json (json) – A json dict containing the results for the query.
• mc_type (str) – A name of a ModelChecker used to answer the query.

class emmaa.db.schema.UserModel(**kwargs)

Bases: sqlalchemy.orm.decl_api.Base, emmaa.db.schema.EmmaaTable

A table linking users to models:

UserModel(_id_, user_id, model_id, date, subscription)

Parameters:

• id (int) – (auto, primary key) A database-assigned integer id.
• user_id (int) – (foreign key -> User.id) The id of the user related to this query.
• model_id (str) – (20 character) The short id/acronym for the given model.
• date (datetime) – (auto) The date that this entry was added to the database.
• subscription (bool) – Record whether the user has subscribed to see results of this model.

Database Manager (emmaa.db.manager)

class emmaa.db.manager.EmmaaDatabaseManager(host, label=None)

Bases: object

A class used to manage sessions with EMMAA’s database.

add_user(user_id, email)

Add a new user’s email and id to Emmaa’s User table.

create_tables(tables=None)

Create the tables from the EMMAA database

Optionally specify tables to be created. List may contain either table objects or the string names of the tables.

drop_tables(tables=None, force=False)

Drop the tables from the EMMAA database given in tables.

If tables is None, all tables will be dropped. Note that if force is False, a warning prompt will be raised to asking for confirmation, as this action will remove all data from that table.

get_all_result_hashes(qhash, mc_type)

Get a set of all result hashes for a given query and mc_type.

get_model_users(model_id)

Get all users who are subscribed to a given model.

Parameters:model_id (str) – A standard name of a model to get users for. Returns:A list of email addresses corresponding to all users who are subscribed to this model. Return type:list[str]

get_queries(model_id)

Get queries that refer to the given model_id.

Parameters:model_id (str) – The short, standard model ID. Returns:queries – A list of queries retrieved from the database. Return type:list[emmaa.queries.Query]

get_results(user_email, latest_order=1, query_type=None)

Get the results for which the user has registered.

Parameters:

• user_email (str) – The email of a user.
• latest_order (int) – Which result in the order from the latest to get. Default: 1 ( latest).
• query_type (str) – Filter results to specific query type. Default: None (all query types will be returned).

Returns:

results – A list of tuples, each of the form: (model_id, query, mc_type, result_json, delta, date) representing the result of a query run on a model on a given date.

Return type:

list[tuple]

get_subscribed_queries(email)

Get a list of (query object, model id, query hash) for a user

Parameters:email (str) – The email address to check subscribed queries for Returns: Return type:list(tuple(emmaa.queries.Query, str, query_hash))

get_subscribed_users()

Get all users who have subscriptions :returns: A list of email addresses corresponding to all users who have

any subscribed query

Return type:list[str]

get_user_models(email)

Get all models a user is subscribed to.

put_queries(user_email, user_id, query, model_ids, subscribe=True)

Add queries to the database for a given user.

Parameters:

• user_email (str) – the email of the user that entered the queries.
• user_id (int) – the user id of the user that entered the queries. Corresponds to the user id in the User table in indralab_auth_tools
• query (emmaa.queries.Query) – A query object containing all necessary information.
• model_ids (list[str]) – A list of the short, standard model IDs to which the user wishes to apply these queries.
• subscribe (bool) – True if the user wishes to subscribe to this query.

put_results(model_id, query_results)

Add new results for a set of queries tested on a model_id.

Parameters:

• model_id (str) – The short, standard model ID.
• query_results (list of tuples) – A list of tuples of the form (query, mc_type, result_json), where the query is the query object run against the model, mc_type is the model type for the result, and the result_json is the json containing corresponding result.

subscribe_to_model(user_email, user_id, model_id)

Subsribe a user to model updates.

Parameters:

• user_email (str) – the email of the user that entered the queries.
• user_id (int) – the user id of the user that entered the queries. Corresponds to the user id in the User table in indralab_auth_tools
• model_id (str) – Standard model ID to which the user wishes to subscribe.

update_email_subscription(email, queries, models, subscribe)

Update email subscriptions for user queries

NOTE: For now this method simply unsubscribes to the given queries but should in the future differentiated into recieving email notifications or not and subscribing to queries or not.

Parameters:

• email (str) – The email assocaited with the query
• queries (list(int)) – A list of query hashes.
• " list[str] (models) – A list of models.
• subscribe (bool) – The subscription status for all matching query hashes

Returns:

Return True if the update was successful, False otherwise

Return type:

bool

exception emmaa.db.manager.EmmaaDatabaseError

Bases: Exception