ccobra

CCOBRA Module

Functions

ccobra.convert_to_basic_types(elem)[source]

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)[source]

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)[source]

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.spatial`	Spatial reasoning submodule that contains utility functionality to facilitate modeling and analyses in the domain of spatial reasoning.
`ccobra.syllogistic`	Syllogistic submodule that contains utility functionality to facilitate modeling and analyses in the domain of syllogistic reasoning.
`ccobra.syllogistic_generalized`	Generalized Syllogistic submodule that contains utility functionality to facilitate modeling and analyses in the domain of syllogistic reasoning with generalized quantifiers.

Classes

class ccobra.CCobraComparator[source]

Comparator base class.

compare(prediction, target, response_type, choices)[source]

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()[source]

Returns the name of the comparator.

Returns:: Comparator name.
Return type:: string

class ccobra.CCobraData(data, target_columns)[source]

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()[source]

Returns the contained data.

Returns:: Dataframe containing the data.
Return type:: pd.DataFrame

head()[source]: Displays the first 10 lines of the dataframe.

prefix_identifiers(prefix='_train_')[source]

Prefixes the subject identifier keys.

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

prepare_data()[source]: Prepares the dataset by adding internally_used columns

to_eval_dict()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]: Callback to indicate participant start.

class ccobra.CCobraResponseEncoder[source]

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

encode_response(response, task)[source]

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[source]

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

encode_task(task)[source]

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)[source]

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