Experiment

backend.experiment.models

Block

Bases: Model

Root entity for configuring experiment blocks

Attributes:

Name	Type	Description
phase	Phase	The phase this block belongs to
index	int	Index of this block in the phase
slug	str	Slug for this block
name	str	Block name
description	str	Description
playlists	list(section.models.Playlist	The playlist(s) used in this block
image	Image	Image that will be showed on the dashboard
active	bool	Is this block active?
rounds	int	Number of rounds
bonus_points	int	Bonus points
rules	str	The rules used for this block
theme_config	ThemeConfig	Theme settings
rules_config	dict	a dictionary containing extra settings for the rules coupled to the block

Source code in backend/experiment/models.py

class Block(models.Model):
    """Root entity for configuring experiment blocks

    Attributes:
        phase (Phase): The phase this block belongs to
        index (int): Index of this block in the phase
        slug (str): Slug for this block
        name (str): Block name
        description (str): Description
        playlists (list(section.models.Playlist)): The playlist(s) used in this block
        image (image.models.Image): Image that will be showed on the dashboard
        active (bool): Is this block active?
        rounds (int): Number of rounds
        bonus_points (int): Bonus points
        rules (str): The rules used for this block
        theme_config (theme.models.ThemeConfig): Theme settings
        rules_config (dict): a dictionary containing extra settings for the rules coupled to the block
    """

    phase = models.ForeignKey(Phase, on_delete=models.CASCADE, related_name="blocks", blank=True, null=True)
    slug = models.SlugField(
        db_index=True, max_length=64, unique=True, validators=[block_slug_validator]
    )
    index = models.IntegerField(default=0, help_text="Index of the block in the phase. Lower numbers come first.")

    name = models.CharField(max_length=64, blank=True, default="")
    description = models.TextField(blank=True, default="")

    playlists = models.ManyToManyField("section.Playlist", blank=True)

    image = models.ForeignKey(Image, on_delete=models.SET_NULL, blank=True, null=True)

    rounds = models.PositiveIntegerField(default=10)
    bonus_points = models.PositiveIntegerField(default=0)
    rules = models.CharField(default="", max_length=64)

    theme_config = models.ForeignKey(
        ThemeConfig, on_delete=models.SET_NULL, blank=True, null=True
    )

    rules_config = models.JSONField(
        default=dict,
        help_text=_("Extra settings to control the behaviour of the block's rules"),
    )

    def __str__(self):
        return self.name if self.name else self.slug

    def session_count(self) -> int:
        """Number of sessions

        Returns:
            Number of sessions
        """

        return self.sessions.count()

    session_count.short_description = "Sessions"

    def playlist_count(self) -> int:
        """Number of playlists

        Returns:
            Number of playlists
        """

        return self.playlists.count()

    playlist_count.short_description = "Playlists"

    def get_rules(self) -> "experiment.rules.base.Base":
        """Get instance of rules class to be used for this session

        Returns:
            Rules
        """

        from experiment.rules import BLOCK_RULES

        if self.rules not in BLOCK_RULES:
            raise ValueError(f"Rules do not exist (anymore): {self.rules} for block {self.name} ({self.slug})")

        cl = BLOCK_RULES[self.rules]
        return cl()

    def max_score(self) -> int:
        """Get max score from all sessions with a positive score

        Returns:
            max score from all sessions with a positive score
        """

        score = self.sessions.filter(final_score__gte=0).aggregate(
            models.Max("final_score")
        )
        if "final_score__max" in score:
            return score["final_score__max"]

        return 0

    def add_default_question_lists(self):
        """Add default question lists to block"""
        try:
            rules = self.get_rules()
        except ValueError:
            return
        question_lists = getattr(rules, "question_lists", [])
        if question_lists:
            for i, ql in enumerate(question_lists):
                self.create_question_list(ql, i)

    def create_question_list(self, question_list: dict, index: int = 0):
        """create a question list for this block based on a dict specifying name and list of question keys"""
        ql, created = QuestionList.objects.get_or_create(
            name=question_list["name"], block=self, index=index
        )
        if not created:
            "do nothing if the question series already exists"
            return

        # only set these when the object is created, so we don't overwrite changes by admin user
        ql.randomize = question_list.get("randomize", False)
        ql.save()

        for i, question in enumerate(question_list["question_keys"]):
            try:
                question_obj = Question.objects.get(pk=question)
            except Question.DoesNotExist:
                raise Question.DoesNotExist(
                    f"Question with key {question} does not exist."
                )
            QuestionInList.objects.create(
                questionlist=ql,
                question=question_obj,
                index=i + 1,
            )

    def save(self, **kwargs):
        super().save(**kwargs)  # Call the "real" save() method.
        self.add_default_question_lists()

add_default_question_lists()

Add default question lists to block

Source code in backend/experiment/models.py

def add_default_question_lists(self):
    """Add default question lists to block"""
    try:
        rules = self.get_rules()
    except ValueError:
        return
    question_lists = getattr(rules, "question_lists", [])
    if question_lists:
        for i, ql in enumerate(question_lists):
            self.create_question_list(ql, i)

create_question_list(question_list, index=0)

create a question list for this block based on a dict specifying name and list of question keys

Source code in backend/experiment/models.py

def create_question_list(self, question_list: dict, index: int = 0):
    """create a question list for this block based on a dict specifying name and list of question keys"""
    ql, created = QuestionList.objects.get_or_create(
        name=question_list["name"], block=self, index=index
    )
    if not created:
        "do nothing if the question series already exists"
        return

    # only set these when the object is created, so we don't overwrite changes by admin user
    ql.randomize = question_list.get("randomize", False)
    ql.save()

    for i, question in enumerate(question_list["question_keys"]):
        try:
            question_obj = Question.objects.get(pk=question)
        except Question.DoesNotExist:
            raise Question.DoesNotExist(
                f"Question with key {question} does not exist."
            )
        QuestionInList.objects.create(
            questionlist=ql,
            question=question_obj,
            index=i + 1,
        )

get_rules()

Get instance of rules class to be used for this session

Returns:

Type	Description
Base	Rules

Source code in backend/experiment/models.py

def get_rules(self) -> "experiment.rules.base.Base":
    """Get instance of rules class to be used for this session

    Returns:
        Rules
    """

    from experiment.rules import BLOCK_RULES

    if self.rules not in BLOCK_RULES:
        raise ValueError(f"Rules do not exist (anymore): {self.rules} for block {self.name} ({self.slug})")

    cl = BLOCK_RULES[self.rules]
    return cl()

max_score()

Get max score from all sessions with a positive score

Returns:

Type	Description
int	max score from all sessions with a positive score

Source code in backend/experiment/models.py

def max_score(self) -> int:
    """Get max score from all sessions with a positive score

    Returns:
        max score from all sessions with a positive score
    """

    score = self.sessions.filter(final_score__gte=0).aggregate(
        models.Max("final_score")
    )
    if "final_score__max" in score:
        return score["final_score__max"]

    return 0

playlist_count()

Number of playlists

Returns:

Type	Description
int	Number of playlists

Source code in backend/experiment/models.py

def playlist_count(self) -> int:
    """Number of playlists

    Returns:
        Number of playlists
    """

    return self.playlists.count()

session_count()

Number of sessions

Returns:

Type	Description
int	Number of sessions

Source code in backend/experiment/models.py

def session_count(self) -> int:
    """Number of sessions

    Returns:
        Number of sessions
    """

    return self.sessions.count()

Experiment

Bases: Model

A model to allow nesting multiple phases with blocks into a ‘parent’ experiment

Attributes:

Name	Type	Description
slug	str	Slug
name	str	Name of the experiment
description	str	Description
consent	FileField	Consent text markdown or html
about_content	str	About text
social_media_message	str	Message to post with on social media. Can contain {points} and {experiment_name} placeholders
disclaimer	str	Disclaimer text
privacy	str	Privacy statement text
theme_config	ThemeConfig	ThemeConfig instance
active	bool	Set experiment active
social_media_config	SocialMediaConfig	SocialMediaConfig instance
phases	Queryset[Phase]	Queryset of Phase instances

Source code in backend/experiment/models.py

class Experiment(models.Model):
    """A model to allow nesting multiple phases with blocks into a 'parent' experiment

    Attributes:
        slug (str): Slug
        name (str): Name of the experiment
        description (str): Description
        consent (FileField): Consent text markdown or html
        about_content (str): About text
        social_media_message (str): Message to post with on social media. Can contain {points} and {experiment_name} placeholders
        disclaimer (str): Disclaimer text
        privacy (str): Privacy statement text
        theme_config (theme.ThemeConfig): ThemeConfig instance
        active (bool): Set experiment active
        social_media_config (SocialMediaConfig): SocialMediaConfig instance
        phases (Queryset[Phase]): Queryset of Phase instances
    """

    slug = models.SlugField(
        db_index=True,
        max_length=64,
        unique=True,
        null=True,
        validators=[experiment_slug_validator],
    )
    name = models.CharField(max_length=64, blank=True, default="")
    description = models.TextField(blank=True, default="")
    consent = models.FileField(
        upload_to=consent_upload_path,
        blank=True,
        default="",
        validators=[markdown_html_validator()],
    )
    about_content = models.TextField(blank=True, default="")
    social_media_message = models.TextField(
        blank=True,
        help_text=_(
            "Content for social media sharing. Use {points} and {experiment_name} as placeholders."
        ),
        default="I scored {points} points in {experiment_name}!",
    )
    disclaimer = models.TextField(blank=True, default="")
    privacy = models.TextField(blank=True, default="")
    theme_config = models.ForeignKey("theme.ThemeConfig", blank=True, null=True, on_delete=models.SET_NULL)
    active = models.BooleanField(default=True)
    social_media_config: Optional["SocialMediaConfig"]
    phases: models.QuerySet["Phase"]

    def __str__(self):
        return self.name or self.slug

    class Meta:
        verbose_name_plural = "Experiments"

    def associated_blocks(self) -> list["Block"]:
        """Return a list of all associated blocks for this experiment

        Returns:
            Associated blocks
        """

        return Block.objects.filter(phase__experiment=self)

associated_blocks()

Return a list of all associated blocks for this experiment

Returns:

Type	Description
list[Block]	Associated blocks

Source code in backend/experiment/models.py

def associated_blocks(self) -> list["Block"]:
    """Return a list of all associated blocks for this experiment

    Returns:
        Associated blocks
    """

    return Block.objects.filter(phase__experiment=self)

Feedback

Bases: Model

A model for adding feedback to an experiment block

Attributes:

Name	Type	Description
text	str	Text
block	Block	Associated block

Source code in backend/experiment/models.py

class Feedback(models.Model):
    """A model for adding feedback to an experiment block

    Attributes:
        text (str): Text
        block (Block): Associated block
    """

    text = models.TextField()
    block = models.ForeignKey(Block, on_delete=models.CASCADE)

Phase

Bases: Model

Root entity for configuring experiment phases

Attributes:

Name	Type	Description
experiment	Experiment	Instance of an Experiment
index	int	Index of the phase
dashboard	bool	Should the dashbopard be displayed for this phase?
randomize	bool	Should the blocks of this phase be randomized?

Source code in backend/experiment/models.py

class Phase(models.Model):
    """Root entity for configuring experiment phases

    Attributes:
        experiment (Experiment): Instance of an Experiment
        index (int): Index of the phase
        dashboard (bool): Should the dashbopard be displayed for this phase?
        randomize (bool): Should the blocks of this phase be randomized?
    """

    experiment = models.ForeignKey(Experiment, on_delete=models.CASCADE, related_name="phases")
    index = models.IntegerField(
        default=0,
        help_text="Index of the phase in the experiment. Lower numbers come first.",
    )
    dashboard = models.BooleanField(default=False)
    randomize = models.BooleanField(default=False, help_text="Randomize the order of the blocks in this phase.")

    def __str__(self):
        compound_name = (
            self.experiment.name or self.experiment.slug or "Unnamed experiment"
        )
        return f"{compound_name} ({self.index})"

    class Meta:
        ordering = ["index"]

SocialMediaConfig

Bases: Model

Social media config for an experiment

Attributes:

Name	Type	Description
experiment	Experiment	Experiment instance
tags	list[str]	Tags
url	str	Url to be shared
channels	list[str]	Social media channel

Source code in backend/experiment/models.py

class SocialMediaConfig(models.Model):
    """Social media config for an experiment

    Attributes:
        experiment (Experiment): Experiment instance
        tags (list[str]): Tags
        url (str): Url to be shared
        channels (list[str]): Social media channel
    """

    experiment = models.OneToOneField(Experiment, on_delete=models.CASCADE, related_name="social_media_config")

    tags = ArrayField(
        models.CharField(max_length=100), blank=True, default=list, help_text=_("List of tags for social media sharing")
    )

    url = models.URLField(
        blank=True, help_text=_("URL to be shared on social media. If empty, the experiment URL will be used.")
    )

    SOCIAL_MEDIA_CHANNELS = [
        ("facebook", _("Facebook")),
        ("whatsapp", _("WhatsApp")),
        ("twitter", _("Twitter")),
        ("weibo", _("Weibo")),
        ("share", _("Share")),
        ("clipboard", _("Clipboard")),
    ]
    channels = ArrayField(
        models.CharField(max_length=20, choices=SOCIAL_MEDIA_CHANNELS),
        blank=True,
        default=list,
        help_text=_("Selected social media channels for sharing"),
    )

    def get_content(self, score: float) -> str:
        """Get social media share content

        Args:
            score: Score

        Returns:
            Social media shared text

        Raises:
            ValueError: If required parameters are missing when needed
        """
        social_message = self.experiment.social_media_message
        experiment_name = self.experiment.name

        if social_message:
            has_placeholders = "{points}" in social_message and "{experiment_name}" in social_message

            if not has_placeholders:
                return social_message

            if has_placeholders and (score is None or experiment_name is None):
                raise ValueError("score and experiment_name are required for placeholder substitution")

            return social_message.format(points=score, experiment_name=experiment_name)

        if score is None or experiment_name is None:
            raise ValueError("score and name are required when no social media message is provided")

        return _("I scored %(score)d points in %(experiment_name)s") % {
            "score": score,
            "experiment_name": experiment_name,
        }

    def __str__(self):
        social_media_description = self.experiment.name or self.experiment.slug
        return f"Social Media for {social_media_description}"

get_content(score)

Get social media share content

Parameters:

Name	Type	Description	Default
score	float	Score	required

Returns:

Type	Description
str	Social media shared text

Raises:

Type	Description
ValueError	If required parameters are missing when needed

Source code in backend/experiment/models.py

def get_content(self, score: float) -> str:
    """Get social media share content

    Args:
        score: Score

    Returns:
        Social media shared text

    Raises:
        ValueError: If required parameters are missing when needed
    """
    social_message = self.experiment.social_media_message
    experiment_name = self.experiment.name

    if social_message:
        has_placeholders = "{points}" in social_message and "{experiment_name}" in social_message

        if not has_placeholders:
            return social_message

        if has_placeholders and (score is None or experiment_name is None):
            raise ValueError("score and experiment_name are required for placeholder substitution")

        return social_message.format(points=score, experiment_name=experiment_name)

    if score is None or experiment_name is None:
        raise ValueError("score and name are required when no social media message is provided")

    return _("I scored %(score)d points in %(experiment_name)s") % {
        "score": score,
        "experiment_name": experiment_name,
    }

consent_upload_path(instance, filename)

Generate path to save consent file based on experiment.slug and language Returns: upload_to (str): Path for uploading the consent file

Source code in backend/experiment/models.py

def consent_upload_path(instance, filename) -> str:
    """Generate path to save consent file based on experiment.slug and language
    Returns:
        upload_to (str): Path for uploading the consent file
    """
    folder_name = instance.slug
    language = get_language()
    return join("consent", folder_name, f"consent_{language}", filename)