Tabular Data

Tabular data is data usually stored in spreadsheets. It can contain important information about subject background and performance. In large projects there may be several hundreds of variables, and a very wide spreadsheet would be required to store them.

Data is stored in a structure that can be viewed as a table. The first column would contain the ids of the subjects in the study, and the first row would contain the variable names. The values of the variables would be stored in the rest of the table.

Real variables are stored as float numbers, and the metadata contains the minimum, maximum and optimal value for each variable. This parameters can be modified by the subject, and it is not enforced that values lay in this range, however applications may check this and give warnings if there is an inconsistency. This metadata is also useful for plotting.

Nominal variables are stored as numerical labels. Metadata contains a table that maps numerical labels to strings. Which can be accessed with the function get_labels_dict(), for example

>>> get_labels_dict(4)
{
    1 : "male" ,
    2 : "female" ,
}

Several of the functions in this module return instances of pandas.DataFrame.

Subjects

Read

get_subjects()

Get a list subjects which exist in the database

Modify

recursive_delete_subject(*args, **kwargs)

Deletes a subject from the database

Warning

This may affect large amounts of information and can’t be reversed

Some references to the variable may remain in scenario data, subsamples or outside the database. There must not exist any geometrical structure (see geom_db) associated with the subject, if that is the case the operation will be aborted without modifying the database.

Parameters:var_idx (int) – Variable index

Variables

Read

get_variables(mask=None)

Gets available variables

Parameters:mask (str) – If not None, limit answer to results whose name match the given mask (sql like syntax) Returns:pandas.DataFrame with variable indexes as index, and a single column with variable names

get_var_idx(var_name)

Index of variable with given name

Parameters:var_name (str) – Variable name Returns:Index of variable with the given name if it exists, None otherwise

get_var_name(var_idx)

Name of variable with given index

Parameters:var_idx (int) – Variable index Returns:Variable name if it exists, "?" otherwise

does_variable_name_exists(var_name)

Find if the a variable with the given name exists in the database

Parameters:var_name (str) – Variable name Returns:True if a variable with the given name exists, False otherwise

Modify

register_new_variable(*args, **kwargs)

Adds a new variable to the database

Parameters:

• var_name (str) – Name for the new variable, should be unique
• is_real (bool) – Type of the new variable, True if it is real, False if it is nominal

Returns:

Database index of the new variable

recursive_delete_variable(*args, **kwargs)

Deletes a variable from all tables

Warning

This may affect large amounts of information and can’t be reversed

Some references to the variable may remain in scenario data or outside the database.

Parameters:var_idx (int) – Variable index

Special variables

LATERALITY = None

LEFT_HANDED = None

UBICAC = None

Values

Read

get_data_frame_by_index(columns, col_name_index=False)

A data frame containing one column for each variable index in columns

Parameters:columns (list) – Variable indexes Returns:pandas.DataFrame with subject ids as index and one column for each variable

get_data_frame_by_name(columns)

A data frame containing one column for each variable name in columns

Parameters:columns (list) – Variable names Returns:pandas.DataFrame with subject ids as index and one column for each variable

get_laterality(subj_id)

Gets the laterality for a given subject

Parameters:subj_id – The id of the subject Returns:“l” for a left handed subject, “r” otherwise

get_var_value(*args, **kwargs)

Gets a single variable value

Parameters:

• var_idx (int) – Variable index
• subject – Subject id

Returns:

The numerical value for the given variable and subject

get_subject_variables(subj_code, var_codes)

Get several values for one subjects

Parameters:

• subj_code – Subject id
• var_codes (list) – Variable codes

Returns:

pandas.DataFrame with two columns – Variable name, and variable value; for each index in var_codes, which will be used as indexes in the DataFrame.

Modify

update_variable_value(*args, **kwargs)

Updates a single value for a variable and a subject

Parameters:

• var_idx (int) – Variable index
• subject – Subject id
• new_value – Value to be saved

update_multiple_variable_values(*args, **kwargs)

Updates values for variables and subjects

Parameters:idx_subject_value_tuples (list) – Tuples of the form (var_idx, subject, value) where var_idx and subject are the variable and subject for whom the new value will be set.

update_variable_values(*args, **kwargs)

Updates values for one variable and some subjects

Parameters:

• var_idx (int) – Variable index
• tuples (list) – Tuples of the form (subject,value) where subject is the subject id, and value is the new value for the variable.

add_data_frame(*args, **kwargs)

Inserts a whole dataframe into the database

Parameters:

• df (pandas.DataFrame) – DataFrame with subject ids as index, and one column for each new variable.
• callback (func) – Called after each row with the index of the current column as argument, can be used for example to update a progress bar

Metadata

Read

is_variable_real(var_idx)

Find if the variable is real or nominal

Parameters:var_idx (int) – Variable index Returns:False if the variable is Nominal, True otherwise

is_variable_nominal(var_idx)

Find if the variable is real or nominal

Parameters:var_idx (int) – Variable index Returns:True if the variable is Nominal, False otherwise

is_variable_name_real(var_name)

Find if the variable is real or nominal

Parameters:var_name (str) – Variable name Returns:False if the variable is Nominal, True otherwise

is_variable_name_nominal(var_name)

Find if the variable is real or nominal

Parameters:var_name (str) – Variable name Returns:True if the variable is Nominal, False otherwise

are_variables_real(var_idxs)

For each variable in a list, find if it is real

Parameters:var_idxs (list) – variable indexes Returns:A dictionary with variable indexes as keys, and booleans as values as in is_variable_real()

are_variables_nominal(var_idxs)

For each variable in a list, find if it is real

Parameters:var_idxs (list) – variable indexes Returns:A dictionary with variable indexes as keys, and booleans as values as in is_variable_nominal()

are_variables_names_real(var_names)

For each variable in a list, find if it is real

Parameters:var_names (list) – variable names Returns:A dictionary with variable names as keys, and booleans as values as in is_variable_name_real()

are_variables_names_nominal(var_names)

For each variable in a list, find if it is real

Parameters:var_names (list) – variable names Returns:A dictionary with variable names as keys, and booleans as values as in is_variable_name_nominal()

get_labels_dict(var_idx=None, var_name=None)

Map numerical labels to strings in nominal variables

Parameters:var_idx (int) – Variable Index Returns:A dictionary with numerical labels as keys, and the text for each label as values.

get_labels_dict_by_name(var_name)

Map numerical labels to strings in nominal variables

Parameters:var_name (str) – Variable name Returns:A dictionary with numerical labels as keys, and the text for each label as values.

get_minimum_value(var_idx)

Gets the minimum value for a real variable as recorded in meta-data

If there is no metadata, it is calculated from the existing values

Parameters:var_idx (int) – Variable index Returns:Minimum values as recorded in the metadata, if there is no metadata, minimum from existing values.

get_maximum_value(var_idx)

Gets the maximum value for a real variable as recorded in meta-data

If there is no metadata, it is calculated from the existing values

Parameters:var_idx (int) – Variable index Returns:Maximum values as recorded in the metadata, if there is no metadata, maximum from existing values.

get_min_max_values(var_idx)

Gets the minimum and maximum values for a real variable as recorded in meta-data

If there is no metadata, they are calculated from the existing values

Parameters:var_idx (int) – Variable index Returns:(min_val, max_val) values as recorded in the metadata, if there is no metadata, they are calculated from existing values

get_min_max_values_by_name(var_name)

Gets the minimum and maximum values for a real variable as recorded in meta-data

If there is no metadata, they are calculated from the existing values

Parameters:var_name (str) – Variable name Returns:(min_val, max_val) values as recorded in the metadata, if there is no metadata, they are calculated from existing values

get_min_max_opt_values_by_name(var_name)

Gets the minimum, maximum and optimal values for a real variable as recorded in meta-data

If there is no metadata, they are calculated from the existing values

Parameters:var_name (str) – Variable name Returns:(min_val, max_val, optimum_val) values as recorded in the metadata, if there is no metadata, they are calculated from existing values. In this case the optimum will be the mean of existing values.

get_var_description(var_idx)

Get description for a variable

Parameters:var_idx (int) – Variable index Returns:A string containing the description of the variable.

get_var_description_by_name(var_name)

Get description for a variable

Parameters:var_name (str) – Variable name Returns:A string containing the description of the variable.

get_variable_normal_range(var_idx)

Get the range of a given variable for the reference population

Parameters:var_idx – Variable index Returns:(min_val, max_val) calculated over the values the variable takes in the reference population.

Modify

save_is_real(*args, **kwargs)

Update variable type in the metadata

Parameters:

• var_idx (int) – Variable index
• is_real (bool) – If True the variable will be registered as real, otherwise it will be registered as nominal.

save_is_real_by_name(*args, **kwargs)

Update variable type in the metadata

Parameters:

• var_name (str) – Variable name
• is_real (bool) – If True the variable will be registered as real, otherwise it will be registered as nominal.

save_nominal_labels(*args, **kwargs)

Update nominal variable labels

Parameters:

• var_idx (int) – Variable index
• label_name_tuples (list) – List of tuples, the first component of each tuple is the numeric label, and the second component its meaning. For example (1, "male")

save_nominal_labels_by_name(*args, **kwargs)

Update nominal variable labels

Parameters:

• var_name (str) – Variable name
• label_name_tuples (list) – List of tuples, the first component of each tuple is the numeric label, and the second component its meaning. For example (1, "male")

save_real_meta(*args, **kwargs)

Update real variables’ meta data

Parameters:

• var_idx (int) – Variable index
• min_value (float) – Variables minimum value
• man_value (float) – Variables maximum value
• opt_value (float) – Variables optimum value

save_real_meta_by_name(*args, **kwargs)

Update real variables’ meta data

Parameters:

• var_name (str) – Variable name
• min_value (float) – Variables minimum value
• man_value (float) – Variables maximum value
• opt_value (float) – Variables optimum value

save_var_description(*args, **kwargs)

Save or overwrite description for a variable

Parameters:

• var_idx (int) – Variable index
• description (str) – Variable description

save_var_description_by_name(*args, **kwargs)

Save or overwrite description for a variable

Parameters:

• var_name (str) – Variable Name
• description (str) – Variable description

Create New Database

initialize_database(path)

Create a new braviz database

Parameters:path (str) – Name of the new sqlite file that will contain the braviz database