BMSS.models submodule

Submodules

BMSS.models.ia_results module

BMSS.models.ia_results.dump_sg_results(sg_results, variables, config_data, user_core_models={}, save=False)

Adds sg_results for each core_model to the csv file indexed under core_model[‘ia’] where the system_type of each core_model is specified in config_data.

If the core_model is not in the database, you must provide your own core_model in user_core_models and index it under its system_type.

BMSS.models.ia_results.export_sg_results(sg_results, variables, config_data, user_core_models={}, filename='sg_results.yaml'): Exports the results as a human-readable .yaml file

BMSS.models.ia_results.make_columns(core_model): Generates column tuples using states and parameters. Inputs are not included since

BMSS.models.ia_results.make_new_nested_dict(sg_result, model_variables, init, input_conditions, fixed_parameters, measured_states, core_model, **kwargs): Generates a nested dict from the return value of make_new_row

BMSS.models.ia_results.make_new_row(sg_result, model_variables, init, input_conditions, fixed_parameters, measured_states, core_model, **kwargs): Generates a row in dictionary form that can be appended to a DataFrame. Each column is a tuple where the first value is “known” or “unknown” and the second value is a string variable that corresponds to a state, parameter of input in a core_model. Ignores kwargs.

BMSS.models.ia_results.make_new_row_template(core_model, init, input_conditions, fixed_parameters, measured_states, **kwargs): Creates a dictionary that can be used as a template.

BMSS.models.ia_results.update_core_model(sg_result, model_variables, init, input_conditions, fixed_parameters, measured_states, system_type, core_model, pd_args={}, save=False, **kwargs): Generates a new row by calling make_new_row and updates the database with replacement if save is True.

BMSS.models.ia_results.update_row_with_sg_result(row, sg_result, model_variables): Updates the row with information from sg_result and model_variables where sg_result is the output from the function strike_goldd and model_variables is a dict that maps a str variable in row to a symbolic variable in sg_result.

BMSS.models.ia_results.write_new_row_to_file(sg_result, model_variables, init, input_conditions, fixed_parameters, measured_states, system_type, core_model, pd_args={}, local=False, **kwargs)

Generates a new row by calling make_new_row and updates the file indexed under core_model[‘ia’] with replacement to prevent duplication.

The file will be created if it does not exist. model_handler.quick_search is called if the core_model is not provided.

BMSS.models.model_handler module

BMSS.models.model_handler.add_to_database(core_model, dialog=True): Accepts a core_model and adds it to UBase.

BMSS.models.model_handler.config_to_database(filename, dialog=True)

Reads a config file containing information for a core_model data structure and adds the core_model to the database.

Parameters

filename (str) – Name of the file to be read
dialog (bool, optional) – For backend use, defaults to True

BMSS.models.model_handler.create_connection(db_file): Creates database specified by db_file.

BMSS.models.model_handler.create_table(db, *args): Creates table. Use args to add additional sql commands.

BMSS.models.model_handler.delete(system_type): Sets the value of the active column of the core_model in the .db file to 0. Can be restored using the restore function.

BMSS.models.model_handler.from_config(filename)

Reads a file and returns a core_model data structure.

Parameters: filename (str) – The name of the file to read.

BMSS.models.model_handler.list_models(database=None): Returns a list of system_types

BMSS.models.model_handler.make_core_model(system_type, states, parameters, inputs, equations, descriptions=None, ia='', **kwargs)

Returns a dictionary with the keys id, system_type, states, parameters, inputs, equations, ia.

Otherwise referred to as a core_model in the BMSS2 documentation. Redundant states, parameters and inputs are disallowed.

param system_type: A string of keywords serving as a unique identifier for the core_model separated by commas, will be formatted so there is one space after each comma, keywords should be in CamelCase
type system_type: str
param states: A list of strings corresponding to state names used in the core_model
type states: list
param parameters: A list of strings corresponding to parameter names used in the core_model
type parameters: list
param inputs: A list of strings corresponding to input names used in the core_model
type inputs: list
param equations: A list of strings corresponding to lines of equations used in the core_model where the lines form coherent Python code when joined by ‘

‘.join

type equations: list
param descriptions: A description of the model.
type descriptions: dict, optional
param ia: For IA results as a string that can be read into csv format. Avoid using this argument.
type ia: string, optional
kwargs: Will be ignored

BMSS.models.model_handler.quick_search(system_type, error_if_no_result=True, **kwargs): Searches both system_type/id and returns an exact match in system_type/id. Raises an error when no matches are found if error_if_no_result is set to True.

BMSS.models.model_handler.read_ia(core_model, mode='df', filename='')

Reads the string in core_model[‘ia’] and converts into a DataFrame.

If mode is df, the DataFrame is returned.

If mode is csv, the string is written to a csv file.

If mode is yaml, the method to_dict(“record”) is called and the resulting dict is converted to .yaml.

BMSS.models.model_handler.restore(system_type): Sets the value of the active column of the core_model in the .db file to 1.

BMSS.models.model_handler.search_database(keyword, search_type='system_type', database=None, active_only=True)

Searches database for core_model data structure based on a keyword and a key(field) in the core_model. Returns a list of core_model dictionaries.

Parameters

keyword (str) – A string that will be matched against entries in the database
search_type (str) – A string corresponding to any key in the core_model, will be used for matching
database (SQL Connection, optional) – Can be either MBase or UBase, if None, this function will search both databases, defaults to None
active_only (bool, optional) – A boolean for backend use, if True, this limits the search to rows where the value of active is True, defaults to True

BMSS.models.model_handler.split_at_top_level(string, delimiter=','): Use this for nested lists. This is also a helper function for string_to_dict.

BMSS.models.model_handler.to_config(core_model, filename)

Exports a core_model data structure to a config file.

Parameters

core_model (dict) – The core_model to be exported
filename (str) – The name of the file to write to

BMSS.models.model_handler.to_df(database=None)

Returns a copy of the databases as a pandas DataFrame.

Parameters: database (SQL Connection) – The database to be read, if None, both databases will be read, defaults to None

BMSS.models.model_handler.update_ia(core_model, new_row, save=True)

Appends new_row to the core_model[‘ia’] where new_row can be a dict or Series.

If save is True and the core_model is in the database, the changes will be applied to database.

BMSS.models.settings_handler module

BMSS.models.settings_handler.add_to_database(settings, dialog=False): Accepts a settings data structure and adds it to UBase. dialog is currently ignored.

BMSS.models.settings_handler.config_to_database(filename): Adds settings in file to the database. Returns a list of tuples of system_type, settings_name pairs.

BMSS.models.settings_handler.delete(system_type, settings_name): Sets the value of the active column of the core_model in the .db file to 0. Can be restored using the restore function.

BMSS.models.settings_handler.from_config(filename, user_core_models={})

Returns a settings data structure.

Parameters

filename (str) – Name of file to read.
user_core_models (dict, optional) – A dictionary of core_models required for calling make_settings, to be ignored if the core_model is already in the database.

BMSS.models.settings_handler.list_settings(database=None): Returns a list of tuples in the form (system_type, settings_name) from database.

BMSS.models.settings_handler.make_settings(system_type, settings_name, units, parameters, init=None, tspan=None, priors={}, parameter_bounds={}, fixed_parameters=[], solver_args={}, init_orient='scenario', user_core_model=None, **ignored)

Checks and standardizes formatting of data types. Ignores irrelavant keyword arguments. Returns a settings data structure which is a dict.

Parameters

system_type (str) – A string of keywords serving as a unique identifier for the core_model separated by commas, will be formatted so there is one space after each comma, keywords should be in CamelCase
settings_name (str) – A string, forms a unique identifier when paired with system_type
units (dict) – A dict where the keys are parameter names and the values are the units in strings
parameters (pandas DataFrame or dict) – A pandas DataFrame of parameter values OR a dictionary, column names/keys must match the parameter names of the corresponding core_model
init (dict) – A dictionary where the keys correspond to a state in the core_model and the values are the initial values for numerical integration OR where the keys correspond to different scenarios
tspan (list, optional) – A list of segments for piecewise numerical integration where each segments is a list of time points, defaults to values generated using numpy.linspace
priors (dict, optional) – A dictionary of Gaussian priors for parameter estimation where each key is a parameter name and each value a tuple in the form (mean, standard_deviation)
parameter_bounds (dict, optional) – A dictionary of parameter bounds for parameter estimation where each key is a parameter name and each value a tuple in the form (lower, upper)
fixed_parameters (list, optional) – A list of parameter names that will be fixed during parameter estimation.
solver_args (dict, optional) – Additional keyword arguments for scipy.integrate.odeint, defaults to None
init_orient (str) – ‘scenario’ if the keys in init are scenario numbers, ‘state’ if the keys are the state names, defaults to ‘scenario’
user_core_model (dict) – A core_model data structure for cross-checking. If None, this function will search the database for the core_model.

BMSS.models.settings_handler.make_settings_template(system_types_settings_names, filename='')

Writes settings to a config file. Returns the code as a string.

Parameters

system_types_settings_names (list or tuple) – Pairs of tuples containing (system_type, settings_name)
filename (str, optional) – The name of the file to write to

BMSS.models.settings_handler.quick_search(system_type='', settings_name='', error_if_no_result=True, **kwargs): Searches database and returns first search result. If no settings name is given, will attempt to search for the settings indexed under “__default__”.

BMSS.models.settings_handler.restore(system_type, settings_name): Sets the value of the active column of the core_model in the .db file to 1.

BMSS.models.settings_handler.search_database(system_type='', settings_name='', database=None, skip_constructor=False, active_only=True)

Searches database for settings data structure based on system_type and settings name. Returns a list of settings dictionaries.

Parameters

system_type (str) – A string that will be matched against entries in the database
settings_name (str) – A string corresponding to any key in the core_model, will be used for matching
database (SQL Connection, optional) – Can be either MBase or UBase, if None, this function will search both databases, defaults to None
skip_constructor (bool, optional) – For backend use, defaults to False
active_only (bool, optional) – A boolean for backend use, if True, this limits the search to rows where the value of active is True, defaults to True

BMSS.models.settings_handler.to_df(database=None)

Returns a copy of the databases as a pandas DataFrame.

Parameters: database (SQL Connection) – The database to be read, if None, both databases will be read, defaults to None

BMSS.models.setup_cf module

BMSS.models.setup_cf.from_config(filename, sampler='sa')

Opens a config file and reads the fields/subfields required for setting up the analysis while ignoring the irrelavant ones. Returns a dictionary of the collected information.

Parameters

filename (str) – Name of file to read.
sampler (str, optional) – “sa” for simulated annealing; “bh” for scipy’s basin hopping; “da” for scipy’s dual annealing; “de” for scipy’s differential evolution; defaults to “sa”

BMSS.models.setup_cf.get_sampler_args(filename, sampler='sa', user_core_models={})

Reads the config file and adds combines it with core_model data. If you are using a core model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type. Returns a dictionary of keyword arguments and the config_data.

Parameters

filename (str) – The name of the file to read
sampler (str, optional) – “sa” for simulated annealing; “bh” for scipy’s basin hopping; “da” for scipy’s dual annealing; “de” for scipy’s differential evolution; defaults to “sa”
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_cf.get_sampler_args_bh(filename, user_core_models={})

Shortcut for setting up differential evolution for one model

BMSS.models.setup_cf.get_sampler_args_da(filename, user_core_models={})

Shortcut for setting up differential evolution for one model

BMSS.models.setup_cf.get_sampler_args_de(filename, user_core_models={})

Shortcut for setting up differential evolution for one model

BMSS.models.setup_cf.get_sampler_args_op(filename, user_core_models={})

Shortcut for setting up differential evolution for one model

BMSS.models.setup_cf.get_sampler_args_sa(filename, user_core_models={})

Shortcut for setting up simulated annealing for one model

BMSS.models.setup_cf.make_settings_template(system_types_settings_names, filename='', user_core_models={})

Writes settings to a config file. If you are using a core_model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type.Returns the code as a string.

Parameters

system_types_settings_names (list or tuple) – Pairs of tuples containing (system_type, settings_name)
filename (str, optional) – The name of the file to write to
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sen module

BMSS.models.setup_sen.from_config(filename)

Opens a config file and reads the fields/subfields required for setting up the analysis while ignoring the irrelavant ones. Returns a dictionary of the collected information.

Parameters: filename (str) – Name of file to read.

BMSS.models.setup_sen.get_sensitivity_args(filename, user_core_models={})

Reads the config file and adds combines it with core_model data. If you are using a core model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type. Returns a dictionary of keyword arguments and the config_data.

Parameters

filename (str) – The name of the file to read
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sen.make_settings_template(system_types_settings_names, filename='', user_core_models={})

Writes settings to a config file. If you are using a core_model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type.Returns the code as a string.

Parameters

system_types_settings_names (list or tuple) – Pairs of tuples containing (system_type, settings_name)
filename (str, optional) – The name of the file to write to
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sg module

BMSS.models.setup_sg.from_config(filename)

Opens a config file and reads the fields/subfields required for setting up the analysis while ignoring the irrelavant ones. Returns a dictionary of the collected information.

Parameters: filename (str) – Name of file to read.

BMSS.models.setup_sg.get_strike_goldd_args(filename, user_core_models={}, write_file=False)

Reads the config file and adds combines it with core_model data. If you are using a core model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type. Returns a dictionary of keyword arguments and the config_data.

Parameters

filename (str) – The name of the file to read
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sg.make_settings_template(system_types_settings_names, filename='', user_core_models={})

Writes settings to a config file. If you are using a core_model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type.Returns the code as a string.

Parameters

system_types_settings_names (list or tuple) – Pairs of tuples containing (system_type, settings_name)
filename (str, optional) – The name of the file to write to
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sim module

BMSS.models.setup_sim.from_config(filename)

Opens a config file and reads the fields/subfields required for setting up the analysis while ignoring the irrelavant ones. Returns a dictionary of the collected information.

Parameters: filename (str) – Name of file to read.

BMSS.models.setup_sim.get_models_and_params(filename, user_core_models={})

Reads the config file and adds combines it with core_model data. If you are using a core model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type. Returns the models, params and config_data.

Parameters

filename (str) – Name of file to read.
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sim.make_settings_template(system_types_settings_names, filename='', user_core_models={})

Writes settings to a config file. If you are using a core_model that is not in the database, you must provide the core_model using the core_models argument where the key is the system_type.Returns the code as a string.

Parameters

system_types_settings_names (list or tuple) – Pairs of tuples containing (system_type, settings_name)
filename (str, optional) – The name of the file to write to
user_core_model (dict, optional) – A dictionary of core_models indexed by their system_type. core_models already in the database do not need to be specified here.

BMSS.models.setup_sim.setup_helper(filename, reader, user_core_models={})

The first return value is the config_data which will be generated based on three possible scenarios:

filename is a dictionary The filename is already config_data. No processing needed.

filename is a string filename is name of the settings file to be opened and parsed by reader.

filename is neither of the above filename is an iterable containing names of settings file. It will be iteratively parsed by reader and subsequently reindexed to give config_data.

The second return value is a list of core_model data structures associated with config_data. The list is arranged in the order given by config_data and the core_models are retrieved based on two possible scenarios:

The system_type in config_data[model_num][‘system_type’] is in core_models The core_model indexed under core_models[system_type] will be used.

The system_type in config_data[model_num][‘system_type’] is not in core_models The function searches the BMSS database for the appropriate core_model using quick_search