Models¶

This page gives a discription of the implemented models and their relations.

Prompt¶

class Prompt¶

A Prompt is an abstract definition of a task or question that will be presented to a user in order to collect responses.

In order to present a Prompt to a user, it needs to be instantiated by calling :method:`get_instance()`.

In its simplest form, a Prompt defines some text and a type for either free-form or rating respones.

A more advanced version can be connected to any other type of object. When instantiated, these Prompts will be populated with one object chosen from the set of objects of the defined type. The default implementation returns one random object, but this can be customized.

The most advanced version defines two types of objects and allows for tagging, i.e. the user is asked to rate the relationship between objects of the first set and objects of the second. When instantiated, these Prompts will be populated with one object chosen of the first type and a number of objects of the second type.

Prompts also offer a range of analysis functions. For the sake of readability, these are documented here.

type¶: The type of the Prompt. Currently supported types: likert, openended, tagging

text¶: The text to be displayed to the user. The string can use the {object} placeholder which will be replace by the object the prompt is instantiated with.

scale_min¶: For prompts with scale responsed, the minimum value of the scale. Defaults to 1

scale_max¶: For prompts with scale responsed, the maximum value of the scale.

prompt_object_type¶: An object of class ContentType to define the model of objects this prompt will be populated with when instantiated. One prompt instance will be populated with one object of this type. A response will contain a reference to this object.

response_object_type¶: An object of class ContentType to define the model of objects this prompt will be populated with when instantiated. One prompt instance will be populated with a number of objects of this type. A response will create :class:`Tag`s with references to these objects.

get_instance()¶

Instantiate this Prompt. Will get one or more objects, depending on the type of prompt.

Returns:	`PromptInstance`

create_response()¶

Convenience function to create (and save) a Response for this prompt.

Pass rating or text, as well as user and prompt_object as needed.

To save tagging responses, pass tags=[(object1, rating1), (object2, rating2), ...] OR alternatively, tags=[{‘object_id’: id1, ‘rating’: rating2}, ...]

Note that responses per se are not unique per user (as some experiments might require asking the same question multiple times). Some of the analytics functions offer a user_unique parameter to restrict analysis to the user’s latest response only.

In contrast, tags are ensured to be unique for (prompt, user, prompt_object, response_object). If the user tagged this combination before, the Tag will be updated, incl. its response relation (i.e. the original Response object will no longer be associated with this tag).

This method verifies that the objects match the models defined in the Prompt and raises a ValidationException on a mismatch.

Returns:	the newly created `Response`

get_object()¶: Used to determine the object for instantiating this Prompt. The default implementation is to retrieve a random object from the queryset. You can override this method to customize this. See Prompt.prompt_object_type.

get_queryset()¶: The queryset from which the object will be drawn when instantiating this Prompt. The default implementation is to return all objects of type Prompt.prompt_object_type.

get_response_objects()¶: Used to determine the objects for instantiating this Prompt. The default implementation is to retrieve a random object from the queryset. You can override this method to customize this. See Prompt.response_object_type.

get_response_queryset()¶: The queryset from which the objects will be drawn when instantiating this Prompt. The default implementation is to return all objects of type Prompt.response_object_type.

Scales¶

For prompts that require rating responses, usually you want to confine the acceptable values to a certain scale.

The Prompt model offers some utility functions to create arbitrary scales for displaying them in forms.

TODO

PromptInstance¶

class PromptInstance¶

A PromptInstance is not a database model, but created on the fly when a prompt is instantiated. It encapsulates the prompt and any object instances that are needed to display it to the user. It only lives for one request.

prompt¶

Type:	`Prompt`

object¶: An object with which this prompt has been populated. See Prompt.prompt_object_type.

response_objects¶: A list of objects with which this prompt has been populated. Can be presented for tagging prompts. See Prompt.response_object_type.

__str__()¶: The string representation of this class is the prompt’s text, formatted with the object. Useful for directly printing a prompt_instance in a template. See Prompt.text.

Response¶

class Response¶

A Response can have a rating and/or a text. If the prompt has a prompt_object_type, the object obtained during instantiation should be saved as prompt_object.

rating¶

Type:	integer

text¶

Type:	string

prompt_object¶: Any object that this response is related to. Its type should match prompt_object_type.

prompt¶: The Prompt that this response is related to. This is a required field.

user¶: The user that this response belongs to. This is a required field.

Tag¶

class Tag¶

User ratings for associations between two objects. Tags are contained in a Response. You shouldn’t need to create these objects yourself – rather, refer to Prompt.create_response().

response_object¶: The object that this tag refers to. Should match the type defined in the Prompt. When you instantiate a Prompt, this should be one of the instance’s response_objects. See Prompt.response_object_type.

rating¶

Type:	integer

response¶: The Response that this tag is related to. This is a required field.

PromptSet¶

class PromptInstance

You can optionally use PromptSets to organize several prompts together. PromptSets have a name and contain an ordered list of Prompt objects.

name¶: A name to identify this set. Should be in slug format.

prompts¶: A many-to-many field to add any number of Prompts to this set. Prompts are orderable. If you use the Django admin and added sortedm2m to your INSTALLED_APPS, the widget should allow drag and drop. See django-sortedm2m’s documentation for details about how this works.