Merge pull request #288 from Apgomeznext/anapaula/Course_Comparison_D…

…ashboard_documentation

docs: course comparison dashboard documentation

docs/administrator/how_to/access_superset.rst

@@ -0,0 +1,44 @@
+How to Access Aspects Superset
+##############################
+
+Apache Superset is an open-source platform that is the primary data visualization and exploration tool for Aspects. You can access the different dashboards from this platform, edit them, or create new ones. You can also modify the charts and `data sets <https://docs.openedx.org/projects/openedx-aspects/en/latest/administrator/how_to/database_connections.html>`_, control the SQL connection, and `add or edit users <https://docs.openedx.org/projects/openedx-aspects/en/latest/administrator/how_to/create_new_role.html>`_ accessing the analytics system.
+
+.. image:: /_static/superset_access_overview.png
+
+There are two ways to access Superset. The first one is the Superset Aspects URL of your platform. The second one is through the link in the Instructor dashboard of the LMS. Let’s learn more about these two forms.
+
+Superset Aspects URL:
+*********************
+As an `administrator or site operator <https://docs.openedx.org/projects/openedx-aspects/en/latest/administrator/concepts/role_description.html>`_, you can access Superset using the URL given/created during installation.
+
+The process is quite simple.
+
+1. In the browser of your choice, type the URL of your Aspects platform and press **Enter**. The URL usually follows a format like “superset.axim.atlas.edunext.link.”
+
+2. Click the **Sign In with OPENEDXSSO** button. The system will use your Open edX platform credentials to access Aspects’ Superset platform. Make sure you are signed in to your Open edX platform with credentials that have permission to access Superset.
+
+.. image:: /_static/superset_access_1.png
+
+Aspects’ Superset LMS Link:
+***************************
+The other method to access Superset is through the link in the LMS. This is useful for users with different roles, like the `Course Delivery Team <https://docs.openedx.org/projects/openedx-aspects/en/latest/course_team/index.html>`_. Follow these steps to access the platform.
+
+.. note:: The site operator of the Aspects platform must enable this link to appear on the LMS Open edX instance. 
+
+1. From a course page in the LMS, go to the **Instructor dashboard**.
+
+2. In the Instructor dashboard, select the **Reports tab**.
+
+.. image:: /_static/superset_access_3.png
+
+3. Click on **View dashboard in Superset**.
+
+.. image:: /_static/superset_access_4.png
+
+4. If it is your first time accessing Superset with that account's credentials, an authorization for the Superset-SSO box will appear. Click on **Allow**.
+
+.. image:: /_static/superset_access_5.png
+
+5. Click the **Sign in with OpenedXSSO button** to finally access Superset.
+
+.. image:: /_static/superset_access_1.png

docs/administrator/how_to/index.rst

@@ -5,6 +5,7 @@ How-to's
 .. toctree::
    :maxdepth: 2
 
+   access_superset
    create_new_role
    activity_logs
    database_connections

docs/course_team/concepts/filters.rst

@@ -1,7 +1,23 @@
 Filters
 #######
 
-Superset dashboards allow you to filter the data displayed in the charts and graphs, which can help you focus on specific data sets or trends. 
+Filters in Superset for Open edX Aspects are powerful tools that allow users to refine and customize their view of course and learner data. By applying specific criteria, users can isolate and analyze subsets of data, enabling more profound insights into course performance, learner engagement, and other vital metrics. 
+
+These filters provide a flexible and efficient way to:
+
+- Compare courses: Identify similarities and differences between courses.
+- Analyze learner behavior: Understand how learners interact with course content.
+- Identify trends and patterns: Discover trends in course performance and learner engagement.
+- Troubleshoot issues: Pinpoint areas where courses may need improvement.
+
+By leveraging these filters, users can gain valuable insights into the effectiveness of their online courses and make data-driven decisions to improve the learning experience.
+
+Their key functionalities are:
+
+1. Customization: Users can create precise filters to meet their unique analysis needs.
+2. Flexibility: Filters can be combined to create complex queries.
+3. Efficiency: Quickly isolate relevant data for in-depth analysis.
+4. Visualization: Filters can be integrated with visualizations to create informative dashboards.
 
 Types of Filters
 ****************
@@ -17,4 +33,28 @@ There are three main types of filters in Superset dashboards:
 
 .. image:: /_static/time_filters.png
 
-- **Individual Learner Filters:** These filters on the Individual Learner Dashboard allow you to filter the enrollment, engagement, and performance information for a single learner in your course at a time. By default, no filter is applied to the Name, Username, or Email filter.  
+- **Individual Learner Filters:** These filters on the Individual Learner Dashboard allow you to filter the enrollment, engagement, and performance information for a single learner in your course at a time. By default, no filter is applied to the Name, Username, or Email filter.  
+
+Filters for the Course Comparison Dashboard:
+============================================
+
+The `Course Comparison Dashboard <https://docs.openedx.org/projects/openedx-aspects/en/latest/reference/course_comparison_dashboard.html>`_ has different filters that allow you to refine your search and compare and analyze the performance of other courses or versions of the same course.  Let’s find the function of these filters.
+
+- **Organization filter:** This allows you to filter the courses or course runs you are viewing and comparing throughout the Course Comparison Dashboard by the Organization with which the course or course run is associated. You can filter this by multiple organizations or leave the filter blank to compare courses or course runs across the instance.
+
+- **Tag Filter:** This filter will allow you to filter the course and course run data in this dashboard by courses with one or more filtered tags applied to the entire course. For example, if you wish to see all of your microbiology courses, use a microbiology course level tag filter to compare only courses and course runs that share the microbiology tag. You can filter by multiple tags. For example, you can filter on biochemistry and microbiology. The resulting courses and course run on this dashboard will include all courses with the biochemistry, or the microbiology tag or courses or course runs that have both tags applied to the whole course/course run. This filter will only work for instances running the Redwood Release or later.
+
+- **Course Name filter:** This filter allows you to filter the courses or course runs you compare by one or more courses. Applying a course filter and navigating to the Run Metrics tab in the dashboard can be a powerful way to compare all runs of the same course.
+
+- **Course Run filter:** This allows you to filter the course you compare by one or more course runs.
+
+.. image:: /_static/filters_comparison.png
+
+Additional Considerations About Filters:
+========================================
+
+- Data granularity: The granularity of the data available for filtering will vary depending on the specific implementation of Superset for Open edX Aspects.
+- Performance: The performance of filters can be impacted by the size and complexity of the dataset.
+
+In essence, filters in Superset for Open edX Aspects are essential tools for data exploration and analysis, providing users with valuable insights into the performance of their online courses.
+

docs/course_team/how-tos/access_aspects.rst

@@ -11,17 +11,3 @@ Once the Administrator has assigned you the course delivery team role and permit
 
 There you will see the three principal dashboards of Aspects: the `Course Dashboard <https://docs.openedx.org/projects/openedx-aspects/en/latest/reference/course_overview_dashboard.html>`_, the `Individual Learner Dashboard <https://docs.openedx.org/projects/openedx-aspects/en/latest/reference/individual_learner_dashboard.html>`_, and the `At Risk Learner Dashboard <https://docs.openedx.org/projects/openedx-aspects/en/latest/reference/learner_groups_dashboard.html>`_. From these dashboards, you will see the course and learner information that Aspects has collected.
 
-
-3. Above the dashboards, you will find a link to access the dashboards from Superset, modify the filters, and download the reports.
-
-.. image:: /_static/superset_link.png
-
-4. Click the **Allow** button.
-
-.. image:: /_static/superset_permissions.png
-
-5. Click **Sign in with Open edX SSO** button.
-
-.. image:: /_static/superset_singin.png
-
-.. note:: If the link to Superset does not appear, your site operator has elected to disable this link from being shown on your Open edX instance.

docs/reference/course_comparison_dashboard.rst

@@ -1,2 +1,77 @@
 Course Comparison Dashboard Reports
 ###################################
+
+The Course Comparison Dashboard allows you to compare the courses in your instance using high-level data to help you identify trends in how your users interact with the content. It also enables you to understand which courses have more or less success or are more popular to create better strategies for your initiative. You can even compare subsets of courses by using the filters available on the dashboard's filters panel.
+
+.. image:: /_static/comparison_dashboard_1.png
+
+The information about the compared courses will be divided into two tabs: **Course Metrics** and **Run Metrics**. The Course Metrics tab provides that information for those who want to compare aggregate data for all runs of one course against all runs of another course. For those who wish to compare course runs to other course runs, the Runs Metrics tab provides the same types of information as the Course Metrics tab, but at the run level. Let’s learn more about it.
+
+Course Metrics:
+===============
+
+The Course Metrics tab contains information about the selected courses, including enrollment counts, high-level problem performance and course grade information, and the video engagement of each course.
+
+Unlike the `Course Dashboards <https://docs.openedx.org/projects/openedx-aspects/en/latest/reference/course_overview_dashboard.html>`_, here you will see a compendium of the information of the courses you are comparing instead of the details of each course. However, even if you don't drill down into the details, you will have access to the most relevant values to assess the performance of one course compared to another, including the count of recently-active and at-risk students in the course, so you know how many of them may be at risk of losing or dropping out of the course.
+
+.. image:: /_static/course_metrics.png
+
+Run Metrics:
+============
+This tab will contain information on the different course runs, including enrollments, performance data, and video engagement. With this information, you can compare a course delivered more than once on your platform and evaluate when and under what circumstances it performed best.
+
+.. image:: /_static/run_metrics.png
+
+.. note:: If you select one course or organization in the Course Metrics, a cross-filter will activate in the Run Metrics data. You can learn more about `Cross filter here <https://docs.openedx.org/projects/openedx-aspects/en/latest/course_team/how-tos/cross_filter.html>`_.
+
+Data Sections:
+**************
+
+The Course Metrics and Run Metrics tab will allow you to display the course information in the following sections:
+
+Course Info:
+------------
+The Course Info table allows users to sort the courses or course runs they compare by their principal features, such as name, organization, the link to their information in the Course Dashboard, the current enrollees, the number of students active in the last seven days, and their course-level tags.
+
+.. image:: /_static/course_info.png
+
+Enrollment Counts:
+------------------
+The Enrollment Counts table allows users to see the enrollment breakdown of courses or courses run by current enrollment to see which courses are the most and least popular or by a specific enrollment track available on their instance. For example, if their enrollment track only has Verified and Unverified Enrollees, this table should show a Verified Enrollees and an Unverified Enrollees column. This information might answer the question: what courses or course runs are the most learners pursuing certificates for?
+
+.. image:: /_static/enrollment_counts.png
+
+Learner Performance Breakdown:
+------------------------------
+The Learner Performance Breakdown visually conveys how much of your currently enrolled learner base for each course is active, how many learners have passed, and how many are at risk of not completing the course. This last group represents learners who have enrolled in the course, have done something other than visit the course homepage, have not yet passed the course, and have not visited the course in seven or more days. By default, this graph shows the top 10 courses or course runs by total current enrollment. If a user applies a filter, this graph will update to show the top 10 courses or course runs of the courses that have been filtered.
+
+.. image:: /_static/learner_performance_breakdown.png
+
+Learner Performance:
+--------------------
+The Learner Performance table allows users to view and sort the courses or course runs they are comparing by high-level learner performance metrics and other metrics, such as the average of correct answers in the first attempt across the entire course or course run that measures how well matched your learners are to the difficulty level of the problems in that course. This is useful for evaluating if the metric is too high and the problems may be too easy. If the metric is lower, the problems may be too complex for your students. If very high or deficient numbers appear for a course, users can navigate to the course dashboard for a single course to dig a little deeper into which problems may be causing the most problems for learners. This metric represents the percentage of learners who submitted the correct response on the first attempt across all problems in the course only among learners who have submitted a response to each problem.
+
+.. image:: /_static/learner_performance.png
+
+Video Engagement:
+-----------------
+The Video Engagement table presents important video metrics for all filtered courses or course runs for comparison. These metrics can be sorted to identify any outliers quickly. The percentage of video seconds watched metric gives a quick overview of how much video content learners who have started a video in the course are watching. A high percentage of video seconds re-watched can indicate that there may be one or more videos in the course that are unclear or confusing to learners. The number of videos and average video length metrics provide additional context for these measurements. For example, a low percentage of video seconds watched for a course might be because the average video length is long. 
+
+.. image:: /_static/video_engagement.png
+
+How to Access Course Comparison Dashboard?
+******************************************
+
+This dashboard's essential feature is that it can only be accessed from Superset. You can access it via the link to Superset in the Reports tab in the Instructor section from any course in the LMS. If the user's instance does not show the link at the top of the other dashboards, you must connect with your instance administrator. 
+
+.. seealso:: To learn more about `Superset click here <https://docs.openedx.org/projects/openedx-aspects/en/latest/course_team/concepts/superset_overview.html>`_.
+
+.. seealso:: To learn more about accessing Superset, `visit this documentation <https://docs.openedx.org/projects/openedx-aspects/en/latest/administrator/how-tos/access_superset.html>`_.
+
+Also, depending on the combination of Django permissions of your Open edx Platform and your course role, you might or might not be able to access this dashboard.
+
+.. image:: /_static/matrix_permissions.png
+
+Another critical point is that depending on your role and permissions in Superset, you will see more or fewer data from your Open edX instance courses in this dashboard. For example, if you only have a `Course Delivery Team role <https://docs.openedx.org/projects/openedx-aspects/en/latest/course_team/concepts/role_and_permissions.html>`_, you can see only the courses or course runs to which you have been added as staff. But if you have the `role of superuser or administrator <https://docs.openedx.org/projects/openedx-aspects/en/latest/administrator/concepts/role_description.html>`_, you will see all the course data.
+
+