Skip to content

Participant

participant.models:#

Participant #

Bases: Model

Main participant, base for profile and sessions

Attributes:

Name Type Description
unique_hash str

Unique identifier string
country_code str

Country code of the participant
access_info str

HTTP_USER_AGENT info
participant_id_url str

URL code to link an experiment to a participant
Source code in participant/models.py 
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
class Participant(models.Model):
    """Main participant, base for profile and sessions

    Attributes:
        unique_hash (str): Unique identifier string
        country_code (str): Country code of the participant
        access_info (str): HTTP_USER_AGENT info
        participant_id_url (str): URL code to link an experiment to a participant
    """

    unique_hash = models.CharField(
        max_length=64, unique=True, default=uuid.uuid4)
    country_code = models.CharField(max_length=3, default="")
    access_info = models.CharField(max_length=512, default="", null=True)
    participant_id_url = models.CharField(max_length=128, null=True, unique=True)

    def __str__(self):
        return "Participant {}".format(self.id)

    def session_count(self) -> int:
        """Get the total number of started sessions by this participant

        Returns:
            Number of started sessions by a Participant

        Example:
            Get the number of started sessions by this Participant
            ```python
            session_count = participant.session_count()
            ```
        """
        return self.session_set.count()

    session_count.short_description = 'Sessions'

    def result_count(self) -> int:
        """Get the total number of results

        Returns:
            Total number of results from all the sessions by a Participant

        Example:
            Get the number of results from this Participant
            ```python
            result_count = participant.result_count()
            ```
        """
        c = 0
        for session in self.session_set.all():
            c += session.result_set.count()
        return c

    result_count.short_description = 'Results'

    def _export_admin(self)  -> dict:
        """Export data to admin

        Returns:
            Participant data for admin
        """
        return {
            "id": self.id,
            "unique_hash": self.unique_hash,
            "country_code": self.country_code,
            "access_info": self.access_info,
            "participant_id_url": self.participant_id_url,
            "profile": self.profile_object()
        }

    def export_profiles(self) -> QuerySet[Result]:
        """Export participant profile result objects

        Returns:
            All profile results from a participant

        Example:
            Print all the questions and answers from a participant's profile results
            ```python
            all_profile_results = participant.export_profiles()
            for profile in all_profile_results:
                print(f"{profile.question_key} - {profile.given_response}")
            ```
        """

        return self.result_set.all()

    def profile(self) -> QuerySet[Result]:
        """Get all the answered profile results of this participant

        Returns:
            All answered profile results from a participant

        Example:
            Print all the questions and answers from a participant's profile results
            ```python
            all_profile_results = participant.profile()
            for profile in all_profile_results:
                print(f"{profile.question_key} - {profile.given_response}")
            ```
        """
        return self.result_set.all().filter(given_response__isnull=False)

    def profile_object(self) -> dict:
        """Get full profile data in one object

        Returns:
            All profile data from a Participant in one object

        Example:
            Print all the questions, answers and scores from a participant's profile results
            ```python
            all_profile_results = participant.profile_object()
            for key, value in all_profile_results:
                print(f"{key} - {value}")
            ```
        """
        profile_object = {}
        for profile in self.profile():
            profile_object[profile.question_key] = profile.given_response
            if profile.score:
                profile_object['{}_score'.format(
                    profile.question_key)] = profile.score
        return profile_object

    def is_dutch(self) -> bool:
        """Return if a participant is tagged with the country code of the Netherlands (nl)

        Returns:
            Wether a participant is located in the Netherlands or not.

        Example:
            Check if the participant is from the netherlands.
            ```python
            if participant.is_dutch():
                # block of code to be executed if the condition is true
            ```
        """
        return self.country_code == "nl"

    def scores_per_experiment(self) -> list[dict]:
        """Scores per finished experiment session

        Returns:
            All finished sessions and best scores from a Participant

        Example:
            Print score per experiment
            ```python
            scores_list = participant.scores_per_experiment()
            for scores_object in scores_list:
                for key, value in scores_object:
                    print(f"{key} - {value}")
            ```
        """
        scores = []

        # Get all finished sessions
        sessions = self.session_set.exclude(
            finished_at=None).order_by('-final_score')

        hits = {}

        # Create best rank/score data per experiment session
        for session in sessions:

            if session.block.slug in hits:
                continue

            hits[session.block.slug] = True

            scores.append(
                {
                    "block_slug": session.block.slug,
                    "rank": session.block.get_rules().rank(session),
                    "score": session.final_score,
                    "date": naturalday(session.finished_at),
                }
            )

        return scores

    def score_sum(self, question_group_key:str) -> float:
        """ Sums scores of all profile results with questions in a question group

        Args:
            question_group_key: from `question.models.QuestionGroup.key`

        Returns:
            Total score of all profile results from a Participant

        Example:
            Get the total score of all participant's profile results from a specific question group
            ```python
            score_sum = participant.score_sum()
            ```
        """

        question_keys = QuestionGroup.objects.get(key=question_group_key).questions.values_list("key", flat=True)

        return self.result_set.all().filter(question_key__in=question_keys).aggregate(Sum("score"))['score__sum']

export_profiles() #

Export participant profile result objects

Returns:

Type Description
QuerySet[Result]

All profile results from a participant
Example

Print all the questions and answers from a participant’s profile results 

all_profile_results = participant.export_profiles()
for profile in all_profile_results:
    print(f"{profile.question_key} - {profile.given_response}")

Source code in participant/models.py 
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def export_profiles(self) -> QuerySet[Result]:
    """Export participant profile result objects

    Returns:
        All profile results from a participant

    Example:
        Print all the questions and answers from a participant's profile results
        ```python
        all_profile_results = participant.export_profiles()
        for profile in all_profile_results:
            print(f"{profile.question_key} - {profile.given_response}")
        ```
    """

    return self.result_set.all()

is_dutch() #

Return if a participant is tagged with the country code of the Netherlands (nl)

Returns:

Type Description
bool

Wether a participant is located in the Netherlands or not.
Example

Check if the participant is from the netherlands. 

if participant.is_dutch():
    # block of code to be executed if the condition is true

Source code in participant/models.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
def is_dutch(self) -> bool:
    """Return if a participant is tagged with the country code of the Netherlands (nl)

    Returns:
        Wether a participant is located in the Netherlands or not.

    Example:
        Check if the participant is from the netherlands.
        ```python
        if participant.is_dutch():
            # block of code to be executed if the condition is true
        ```
    """
    return self.country_code == "nl"

profile() #

Get all the answered profile results of this participant

Returns:

Type Description
QuerySet[Result]

All answered profile results from a participant
Example

Print all the questions and answers from a participant’s profile results 

all_profile_results = participant.profile()
for profile in all_profile_results:
    print(f"{profile.question_key} - {profile.given_response}")

Source code in participant/models.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def profile(self) -> QuerySet[Result]:
    """Get all the answered profile results of this participant

    Returns:
        All answered profile results from a participant

    Example:
        Print all the questions and answers from a participant's profile results
        ```python
        all_profile_results = participant.profile()
        for profile in all_profile_results:
            print(f"{profile.question_key} - {profile.given_response}")
        ```
    """
    return self.result_set.all().filter(given_response__isnull=False)

profile_object() #

Get full profile data in one object

Returns:

Type Description
dict

All profile data from a Participant in one object
Example

Print all the questions, answers and scores from a participant’s profile results 

all_profile_results = participant.profile_object()
for key, value in all_profile_results:
    print(f"{key} - {value}")

Source code in participant/models.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def profile_object(self) -> dict:
    """Get full profile data in one object

    Returns:
        All profile data from a Participant in one object

    Example:
        Print all the questions, answers and scores from a participant's profile results
        ```python
        all_profile_results = participant.profile_object()
        for key, value in all_profile_results:
            print(f"{key} - {value}")
        ```
    """
    profile_object = {}
    for profile in self.profile():
        profile_object[profile.question_key] = profile.given_response
        if profile.score:
            profile_object['{}_score'.format(
                profile.question_key)] = profile.score
    return profile_object

result_count() #

Get the total number of results

Returns:

Type Description
int

Total number of results from all the sessions by a Participant
Example

Get the number of results from this Participant 

result_count = participant.result_count()

Source code in participant/models.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def result_count(self) -> int:
    """Get the total number of results

    Returns:
        Total number of results from all the sessions by a Participant

    Example:
        Get the number of results from this Participant
        ```python
        result_count = participant.result_count()
        ```
    """
    c = 0
    for session in self.session_set.all():
        c += session.result_set.count()
    return c

score_sum(question_group_key) #

Sums scores of all profile results with questions in a question group

Parameters:

Name Type Description Default
question_group_key str

from question.models.QuestionGroup.key

 required

Returns:

Type Description
float

Total score of all profile results from a Participant
Example

Get the total score of all participant’s profile results from a specific question group 

score_sum = participant.score_sum()

Source code in participant/models.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
def score_sum(self, question_group_key:str) -> float:
    """ Sums scores of all profile results with questions in a question group

    Args:
        question_group_key: from `question.models.QuestionGroup.key`

    Returns:
        Total score of all profile results from a Participant

    Example:
        Get the total score of all participant's profile results from a specific question group
        ```python
        score_sum = participant.score_sum()
        ```
    """

    question_keys = QuestionGroup.objects.get(key=question_group_key).questions.values_list("key", flat=True)

    return self.result_set.all().filter(question_key__in=question_keys).aggregate(Sum("score"))['score__sum']

scores_per_experiment() #

Scores per finished experiment session

Returns:

Type Description
list[dict]

All finished sessions and best scores from a Participant
Example

Print score per experiment 

scores_list = participant.scores_per_experiment()
for scores_object in scores_list:
    for key, value in scores_object:
        print(f"{key} - {value}")

Source code in participant/models.py 
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
def scores_per_experiment(self) -> list[dict]:
    """Scores per finished experiment session

    Returns:
        All finished sessions and best scores from a Participant

    Example:
        Print score per experiment
        ```python
        scores_list = participant.scores_per_experiment()
        for scores_object in scores_list:
            for key, value in scores_object:
                print(f"{key} - {value}")
        ```
    """
    scores = []

    # Get all finished sessions
    sessions = self.session_set.exclude(
        finished_at=None).order_by('-final_score')

    hits = {}

    # Create best rank/score data per experiment session
    for session in sessions:

        if session.block.slug in hits:
            continue

        hits[session.block.slug] = True

        scores.append(
            {
                "block_slug": session.block.slug,
                "rank": session.block.get_rules().rank(session),
                "score": session.final_score,
                "date": naturalday(session.finished_at),
            }
        )

    return scores

session_count() #

Get the total number of started sessions by this participant

Returns:

Type Description
int

Number of started sessions by a Participant
Example

Get the number of started sessions by this Participant 

session_count = participant.session_count()

Source code in participant/models.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
def session_count(self) -> int:
    """Get the total number of started sessions by this participant

    Returns:
        Number of started sessions by a Participant

    Example:
        Get the number of started sessions by this Participant
        ```python
        session_count = participant.session_count()
        ```
    """
    return self.session_set.count()