Skip to content

E
edx-analytics-data-api
Commit 2e3a154d by Alison Hodges Committed by Daniel Friedman
Options

Copy editing pass through the descriptive strings.

parent 08e412bf
Showing with 113 additions and 87 deletions
analytics_data_api/v0/views/learners.py
......@@ -28,7 +28,7 @@ from analytics_data_api.v0.views.utils import split_query_argument
class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
"""
Get a particular student's data for a particular course.
Get data for a particular learner in a particular course.
**Example Request**
......@@ -36,24 +36,33 @@ class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
**Response Values**
Returns the learner metadata and engagement data:
Returns metadata and engagement data for the learner in JSON format.
* username: User's username.
* enrollment_mode: Enrollment mode (e.g. "honor).
* name: User's full name.
* email: User's email.
* segments: Classification for this course based on engagement, (e.g. "has_potential").
* username: The username of the enrolled learner.
* enrollment_mode: The learner's selected learning track (for
example, "audit" or "verified").
* name: The learner's full name.
* email: The learner's email address.
* segments: Classification, based on engagement, of this learner's
work in this course (for example, "highly_engaged" or
"struggling").
* engagements: Summary of engagement events for a time span.
* videos_viewed: Number of times a video was played.
* problems_completed: Unique number of problems completed.
* problems_attempted: Unique number of problems attempted.
* discussions_contributed: Number of discussions (e.g. forum posts).
* videos_viewed: Number of times any course video was played.
* problems_completed: Number of unique problems the learner
answered correctly.
* problems_attempted: Number of unique problems attempted.
This is a count of the individual problems the learner
tried. Each problem in a course can increment this count by
a maximum of 1.
* discussions_contributed: Number of posts, responses, or
comments the learner contributed to course discussions.
**Parameters**
You can specify the course ID for which you want data.
course_id -- The course within which user data is requested.
course_id -- The course identifier for which user data is requested.
For example, edX/DemoX/Demo_Course.
"""
serializer_class = LearnerSerializer
......@@ -76,7 +85,7 @@ class LearnerView(CourseViewMixin, generics.RetrieveAPIView):
class LearnerListView(CourseViewMixin, generics.ListAPIView):
"""
Get a paginated list of student data for a particular course.
Get a paginated list of data for all learners in a course.
**Example Request**
......@@ -85,55 +94,66 @@ class LearnerListView(CourseViewMixin, generics.ListAPIView):
**Response Values**
Returns a paginated list of learner metadata and engagement data.
Pagination data is returned in the top-level of the returned JSON
object:
Pagination data is returned in the top level of the returned JSON
object.
* count: The number of learners matching the query.
* count: The number of learners that match the query.
* page: The current one-indexed page number.
* next: A hyperlink to the next page if one exists, otherwise null.
* previous: A hyperlink to the previous page if one exists, otherwise null.
The 'results' key in the returned JSON object maps to an array of
learners which contains at most a full page's worth of learners. Each
learner is a JSON object containing the following keys:
* username: User's username.
* enrollment_mode: Enrollment mode (e.g. "honor).
* name: User's full name.
* email: User's email.
* segments: Classification for this course based on engagement, (e.g. "has_potential").
* previous: A hyperlink to the previous page if one exists,
otherwise null.
The 'results' key in the returned object maps to an array of
learners that contains, at most, a full page's worth of learners. For
each learner there is an object that contains the following keys.
* username: The username of an enrolled learner.
* enrollment_mode: The learner's selected learning track (for
example, "audit" or "verified").
* name: The learner's full name.
* email: The learner's email address.
* segments: Classification, based on engagement, of each learner's
work in this course (for example, "highly_engaged" or
"struggling").
* engagements: Summary of engagement events for a time span.
* videos_viewed: Number of times a video was played.
* problems_completed: Unique number of problems completed.
* problems_attempted: Unique number of problems attempted.
* discussions_contributed: Number of discussions (e.g. forum posts).
* videos_viewed: Number of times any course video was played.
* problems_completed: Number of unique problems the learner
answered correctly.
* problems_attempted: Number of unique problems attempted.
This is a count of the individual problems the learner
tried. Each problem in a course can increment this count by
a maximum of 1.
* discussions_contributed: Number of posts, responses, or
comments the learner contributed to course discussions.
**Parameters**
You can filter the list of learners by course ID and other parameters
such as enrollment mode and text search. You can also control the
page size and page number of the response, as well as sort the learners
in the response.
course_id -- The course within which user data is requested.
page -- The page of results which should be returned.
page_size -- The maximum number of results which should be returned per page.
text_search -- A string to search over the name, username, and email of learners.
segments -- A comma-separated string of segments to which
learners should belong. Semgents are "OR"-ed together.
Cannot use in combination with `ignore_segments`
argument.
ignore_segments -- A comma-separated string of segments to
which learners should NOT belong. Semgents are "OR"-ed
together. Cannot use in combination with `segments`
argument.
You can filter the list of learners by course ID and by other
parameters, including enrollment mode and text search. You can also
control the page size and page number of the response, as well as sort
the learners in the response.
course_id -- The course identifier for which user data is requested.
For example, edX/DemoX/Demo_Course.
page -- The page of results that should be returned.
page_size -- The maximum number of results to return per page.
text_search -- An alphanumeric string that is used to search name,
username, and email address values to find learners.
segments -- A comma-separated list of segment names that is used
to select learners. Only learners who are categorized in at least
one of the segments are returned. Cannot be used in combination
with the `ignore_segments` argument.
ignore_segments -- A comma-separated list of segment names that is
used to exclude learners. Only learners who are NOT categorized
in any of the segments are returned. Cannot be used in combination
with the `segments` argument.
cohort -- The cohort to which all returned learners must
belong.
enrollment_mode -- The enrollment mode to which all returned
enrollment_mode -- The learning track to which all returned
learners must belong.
order_by -- The field for sorting the response. Defaults to 'username'.
sort_order -- The sort direction. One of 'asc' or 'desc'.
Defaults to 'asc'.
order_by -- The field for sorting the response. Defaults to 'username'.
sort_order -- The sort direction. One of 'asc' (ascending) or 'desc'
(descending). Defaults to 'asc'.
"""
serializer_class = LearnerSerializer
......@@ -210,8 +230,8 @@ class LearnerListView(CourseViewMixin, generics.ListAPIView):
class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
"""
Get a particular learner's engagement timeline for a particular course. Days
without data will not be returned.
Get a particular learner's engagement timeline for a particular course.
Days without data are not returned.
**Example Request**
......@@ -219,20 +239,26 @@ class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
**Response Values**
Returns the engagement timeline.
* days: Array of the learner's daily engagement timeline.
* problems_attempted: Unique number of unique problems attempted.
* problems_completed: Unique number of problems completed.
* discussions_contributed: Number of discussions participated in (e.g. forum posts)
* videos_viewed: Number of videos watched.
Returns the engagement timeline in an array.
* days: An array of the learner's daily engagement timeline.
* problems_attempted: Number of unique problems attempted.
This is a count of the individual problems the learner
tried. Each problem in a course can increment this count by
a maximum of 1.
* problems_completed: Number of unique problems the learner
answered correctly.
* discussions_contributed: Number of posts, responses, or
comments the learner contributed to course discussions.
* videos_viewed: Number of times any course video was played.
* problem_attempts_per_completed: TBD
**Parameters**
You can specify course ID for which you want data.
You can specify the course ID for which you want data.
course_id -- The course within which user data is requested.
course_id -- The course identifier for which user data is requested.
For example, edX/DemoX/Demo_Course.
"""
serializer_class = EngagementDaySerializer
......@@ -258,8 +284,8 @@ class EngagementTimelineView(CourseViewMixin, generics.ListAPIView):
class CourseLearnerMetadata(CourseViewMixin, generics.RetrieveAPIView):
"""
Get metadata on learners within a course. Includes data on segments,
cohorts, enrollment modes, and an engagement rubric.
Get metadata about the learners in a course. Includes data on segments,
cohorts, and enrollment modes. Also includes an engagement rubric.
**Example Request**
......@@ -267,33 +293,33 @@ class CourseLearnerMetadata(CourseViewMixin, generics.RetrieveAPIView):
**Response Values**
Returns a JSON object with the following keys:
Returns an object with the following keys.
* cohorts: An object mapping the names of cohorts in the course to
the number of students belonging to those cohorts.
* segments: An object mapping the names of segments in the course
to the number of students belonging to those segments. The
current set of segments are: "highly_engaged", "disengaging",
* cohorts: An object that maps the names of cohorts in the course
to the number of learners belonging to those cohorts.
* segments: An object that maps the names of segments in the course
to the number of learners belonging to those segments. The
current set of segments is "highly_engaged", "disengaging",
"struggling", "inactive", and "unenrolled".
* enrollment_modes: An object mapping the names of enrollment modes
in the course to the number of students belonging to those
enrollment modes. Examples include "honor" and "verified".
* enrollment_modes: An object that maps the names of learning
tracks in the course to the number of learners belonging to those
tracks. Examples include "audit" and "verified".
* engagement_ranges: An object containing ranges of learner
engagement with the courseware. Each range has 'below_average',
'average', and 'above_average' keys which map to two-element
arrays of which the first element is the lower bound (inclusive)
and the second element is the upper bound (exclusive). It has
the following keys:
* date_range: The time duration for which this data applies
* problems_attempted: engagement ranges for the number of
problems attempted in the date range.
* problems_completed: engagement ranges for the number of
problems completed in the date range.
* problem_attempts_per_completed: engagement ranges for the
engagement with the courseware. Each range has 'below_average',
'average', and 'above_average' keys. These keys map to
two-element arrays, in which the first element is the lower bound
(inclusive) and the second element is the upper bound
(exclusive). It has the following keys.
* date_range: The time period to which this data applies.
* problems_attempted: Engagement ranges for the number of
unique problems tried in the date range.
* problems_completed: Engagement ranges for the number of
unique problems answered correctly in the date range.
* problem_attempts_per_completed: Engagement ranges for the
number of problem attempts per completed problem in the date
range.
* discussions_contributed: engagement ranges for the number of
discussions contributed in the date range.
* discussions_contributed: Engagement ranges for the number of
times learners participated in discussions in the date range.
"""
serializer_class = CourseLearnerMetadataSerializer
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment