ccobra

CCOBRA Module

Functions

ccobra.convert_to_basic_types(elem)

Converts an element to primitive types. If the element is a list, the inner elements will be converted instead. The preference order is bool > int > float > string.

Parameters

elem (Object) – Element to convert.

Returns

Primitive object representing the given element.

Return type

Object

ccobra.tuple_to_string(tuptup)

Converts a tuple to its string representation. Uses different separators (‘;’, ‘/’, ‘|’) for different depths of the representation.

Parameters

tuptup (list) – Tuple to convert to its string representation.

Returns

String representation of the input tuple.

Return type

str

ccobra.unnest(tup)

Unnests a nested tuple. If an element is insight nested lists, the function returns the element, otherwise the list is returned.

Parameters

tup (list) – Nested tuples.

Returns

Element or list without unneccessary nesting.

Return type

object

Submodules

ccobra.benchmark	CCOBRA benchmark functionality.
ccobra.encoders	Encoder handlers for tasks and responses.
ccobra.propositional	Propositional submodule.
ccobra.syllogistic	Syllogistic submodule.
ccobra.syllogistic_generalized	Generalized Syllogistic submodule.

Classes

class ccobra.CCobraComparator

Comparator base class.

compare(prediction, target, response_type, choices)

Base comparison method.

Parameters

• prediction (object) – Prediction object for comparison.

• target (object) – Target object for comparison.

• response_type (string) – The response type of the prediction and target.

• choices (list(object)) – The choice options that were available for this comparison.

Returns

Comparison result.

Return type

float

get_name()

Returns the name of the comparator.

Returns

Comparator name.

Return type

string

class ccobra.CCobraData(data, target_columns)

CCobra experimental data container.

Initializes the CCOBRA data container by passing a data frame and validating its contents.

Parameters

• data (pd.DataFrame) – DataFrame to store in the CCOBRA data container.

• required_fields (list(str), optional) – List of required columns in the data. Defaults to [‘id’, ‘sequence’, ‘task’, ‘choices’, ‘response’, ‘response_type’, ‘domain’]

get()

Returns the contained data.

Returns

Dataframe containing the data.

Return type

pd.DataFrame

head()

Displays the first 10 lines of the dataframe.

prefix_identifiers(prefix='_train_')

Prefixes the subject identifier keys.

Parameters

prefix (str) – Prefix to apply to key numerical identifiers.

prepare_data()

Prepares the dataset by adding internally_used columns

to_eval_dict()

Converts the dataset to an evaluation dictionary mapping from individuals to data.

Returns

Dictionary mapping from subject identifiers to lists of experimental data.

Return type

dict(object, list)

verify_data(data)

Verifies if all required fields are in the data.

Parameters

data (pd.DataFrame) – DataFrame to verify.

Raises

ValueError – Thrown if data does not contain required columns.

class ccobra.CCobraModel(name, supported_domains, supported_response_types)

Base class for CCOBRA models.

Base constructor of CCOBRA models.

Parameters

• name (str) – Unique name of the model. Will be used throughout the CCOBRA framework as a means for identifying the model.

• supported_domains (list(str)) – List containing the domains that are supported by the model (e.g. ‘syllogistic’).

• supported_response_types (list(str)) – List containing the response types that are supported by the model (e.g., ‘single-choice’)

adapt(item, target, **kwargs)

Trains the model based on a given task-target combination.

Parameters

• item (ccobra.Item) – Task information container. Holds the task text, response type, response choices, etc.

• target (str) – True response given by the human reasoner.

end_participant(identifier, model_log, **kwargs)

Hook for when participant simulation ends.

Parameters

• identifier (str or int) – Participant identifier.

• model_log (dict(str, object)) – Dictionary to allow the model to log information for the final output (e.g., parameter configurations for this participant).

pre_person_background(dataset)

Background information about the person to be predicted for. In contrast to the data supplied by pre_adapt, the data given here is not extracted from the test data. For example, could be responses given by the individual in question to an external independent experiment (e.g., participated in a spatial-relation experiment and later in a syllogistic experiment which serve as the test data).

Parameters

dataset (list(dict(str, object))) – Training data for the model. List of tasks containing the items and corresponding responses.

pre_train(dataset)

Pre-trains the model based on given group data. This data is not necessarily other participants from the same experiment, but can also refer to an unrelated external dataset. The information supplied here represents the information known about the general population in the domain of interest.

Parameters

dataset (list(list(dict(str, object)))) – Training data for the model. List of participants which each contain lists of tasks represented as dictionaries with the corresponding task information (e.g., the item container and given response).

pre_train_person(dataset)

Excerpt of the prediction data containing responses of the individual. Is supposed to combat the cold-start problem by supplying models with information about the exact individual to be predicted for. Allows to fit models to a specific individual. For example, in coverage settings, the responses given by the individual are supplied here.

If not overriden by the model implemenation, uses adapt to perform the training.

Parameters

dataset (list(dict(str, object))) – Training data for the model. List of tasks containing the items and corresponding responses.

predict(item, **kwargs)

Generates a single response prediction for a given task.

Parameters

item (ccobra.Item) – Task information container. Holds the task text, response type, response choices, etc.

Returns

Response prediction.

Return type

str

setup_environment(evaluation_type)

Setup environment of the model using information about the prediction setting and the information provided during training.

Parameters

evaluation_type (str) – Type of the CCOBRA evaluation (adaption, coverage).

start_participant(**kwargs)

Callback to indicate participant start.

class ccobra.CCobraResponseEncoder

Domain encoder class interface. Specifies the functions to be implemented by the domain-specific encoder instances.

encode_response(response, task)

Encodes a response

Parameters

• response (list(str)) – Response in tuple representation.

• task (list(list(str))) – Task in tuple representation.

Returns

Response representation.

Return type

str

class ccobra.CCobraTaskEncoder

Domain encoder class interface. Specifies the functions to be implemented by the domain-specific encoder instances.

encode_task(task)

Encodes a task.

Parameters

task (list(list(str))) – Task in tuple representation.

Returns

Task representation.

Return type

str

class ccobra.Item(identifier, domain, task, resp_type, choices, sequence_number)

Container class for representing task items.

Constructs the task item container with information about the domain, task premises, response type, and response choices.

Parameters

• identifier (object) – Unique identifier for the participant.

• domain (str) – Task domain (e.g., ‘syllogistic’).

• task (str) – Task text in tuple string encoding (e.g., ‘All;pilots;gardeners/Some;gardeners;cooks’).

• resp_type (str) – Response type (e.g., ‘single-choice’).

• choices (list(str)) – Response options in string representation.

• sequence_number (int) – Position of the item in the experimental sequence.

choices

Choices in list representation

choices_str

Choices string representation

domain

Domain of the task

identifier

Unique identifier of the participant

response_type

Response type of the task

sequence_number

Position of the task in the experimental sequence

task

Task in list representation

task_str

Task string representation