ubc-mds/pygtracker

A python package designed to store, track grades, provide grade adjustments and ranking for the UBC MDS program.

pygtracker

Package Overview

pygtracker is a Python package that allows UBC MDS lecturers to record, analyze and adjust grades for students in a particular program. Users can record grades from each course, generate a summary report to determine which class is more challenging than the rest, or identify students who may need help. Finally, the package can suggest ways to adjust the grades for students to ensure the average grades match predefined benchmarks.

Python Ecosystem

There are existing packages to manage students' grades in the Python ecosystem. For example, grades-report is a package purely generating statistics from all grades. In addition, edx-bulk-grades aids lecturers in grading and modifying students' grades in bulk. However, these packages are lacking useful features that are unique to the MDS program, such as identifying students / courses that are much different from their peers or adjusting grades to make sure they conform to MDS standard. As a result, we come up with this useful tool which helps UBC MDS lecturers have a better control of student performance.

Features

This package contains seven functions: register_courses, record_grades, calculate_final_grade, generate_course_statistics, rank_courses, rank_students and suggest_grade_adjustment.

The main components of this package are:

• Register courses
  • Read/store the courses information as a dataframe
• Record grades for students
  • Read/store the students' grades for each assessment as a dataframe
• Calculate the final grade
  • Provide the final grade for each student in each course using the courses information and students' grade
• Generate course statistics
  • Provide grade statistics on the courses, including mean, 1st quantile, median and 3rd quantile
• Rank courses
  • Provide the rankings of courses based on courses' average grades
• Rank students
  • Provide the rankings of students based on their average grades for the selected course (or the whole program).
• Suggest grade adjustment
  • Suggest grade adjustments for any course based on predefined benchmarks

Installation

$ pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple pygtracker

Dependencies

• You can find all dependencies in pyproject.toml file

Usage

A toy dataset is used to showcase the usage of the functions. Any csv file containing the grades and courses for the UBC MDS program may be used.

1. you will need to import the pygtracker package, create an instance of the class, and store courses, grades as data frames by function register_courses() and record_grades().

# import packages 
from pygtracker import pygtracker 
import os 

# call an instance of the class
tracker = pygtracker.GradeTracker()

# read in the toy dataset 
courses = pd.read_csv(os.path.join(".", "tests", "test_data", "course_info.csv"))
grades = pd.read_csv(os.path.join(".", "tests", "test_data", "student_info.csv"))

# read and stores data as a dataframe 
tracker.register_courses(courses)
tracker.record_grades(grades)

2. By specifying a list of courses, function generate_course_statistics() would allow you to create a data frame with summary statistics, including mean, 1st-quantile, median and 3rd-quantile of grades so far.

# generates a dataframe with summary statistics for a specified course 
tracker.generate_course_statistics(["511"])

	course_id	mean	1st-quantile	median	3rd-quantile
0	511	87.87	86.91	88	88.96

3. Function rank_courses() generates a data frame of course ranking based on specified method (default is mean) in descending order by default. This would allow the user to find which course students perform better and which they may struggle with so far.

# generates a dataframe for course ranking by grade 
tracker.rank_courses()

	course_id	grade
0	522	91.29
1	511	87.87

4. To look into more details on performance of individual students, function rank_students() would generate a data frame with student ranking by grades based on specified courses (default is all courses completed so far) in descending order. Thus, the students who may need more help or guidance could be found.

# generates a dataframe with student ranking by grade 
tracker.rank_students()

	student_id	grade	rank
0	joel	91.81	1.0
1	tom	90.09	2.0
2	mike	88.29	3.0

5. Lastly, based on function suggest_grade_adjustment(), the user is able to find adjusting suggestions by setting benchmark of the whole course, labs, or quizzes of that course, such that the final grades meet or exceed these benchmarks.

# calculates the adjustment for a course for a specified benchmark 
tracker.suggest_grade_adjustment("511", benchmark_course=100)

	course_id	student_id	feedback	lab1	lab2	lab3	lab4	milestone1	milestone2	milestone3	milestone4	quiz1	quiz2
0	511	joel	0	100	100	100	100	0	0	0	0	100	100
1	511	mike	0	100	100	100	100	0	0	0	0	100	100
2	511	tiff	0	100	100	100	100	0	0	0	0	100	100
3	511	tom	0	100	100	100	100	0	0	0	0	100	100

Documentation

The official documentation is hosted on Read the Docs: https://pygtracker.readthedocs.io/en/latest/

Contributors

We welcome and recognize all contributions. You can see a list of current contributors in the contributors tab.

• Javairia Raza
• Jianru Deng
• Tran Doan Khanh Vu
• Yanhua Chen

Credits

This package was created with Cookiecutter and the UBC-MDS/cookiecutter-ubc-mds project template, modified from the pyOpenSci/cookiecutter-pyopensci project template and the audreyr/cookiecutter-pypackage.

pygtracker's Issues

meeting minute March 2

• generated 2 toy dataset saved in data directory
• first function: check the df has correct cols; all assessments sum up to be 1 and each one should be (0, 1)
• 2nd fn: check df has correct cols; grade should be in (0, 100);
• 3rd fn: check the course_id exists, stats values are correct
• rank_courses : stats should be one of the four; descending/ascending should work;
• rank_students: course_id does exist; n should be <=total # of; descending/ascendingshould work; output should have proper cols(cols#, type, value, name of cols);
• suggest_grade_adjustment: check all benchmark should be (0, 1); test for no adjustment; tests for each benchmark
  (feel free to edit as you need)

Updating Readme

• a summary paragraph that describes the project at a high level @tdkhanhvu

• a bulleted list of the functions (and datasets if applicable) that will be included in the package (this should be a 1-2 sentence description for each function/dataset) @yhchen20

• a paragraph describing where your packages fit into the Python ecosystem (are there any other Python packages that have the same/similar functionality? Provide links to any that do. If none exist, then clearly state this as well). @yhchen20 and @jianructose

• add contributors name @yhchen20

Milestone 1 Agenda

I) Task breakdown

Canvas submission instruction

#	Task	Marks	Description	Deliverables	Assignee
1	Working style (10%)	mechanics:10	Commit to git every time you work on this project with meaningful messages (graded) Follow branching approach (Create branch -> Push commits -> Create Pull Request -> Reviewed and approved by another person) Use GitHub for project-related communication Use proper grammar and full sentences throughout the project, especially in your README.		TBD
2	Follow Submission Instruction (10%)	mechanics:10	Include the URL of your public project’s repo Include the URL to a release on your project repo named v0.1.0 Include a link to your team work document that is accessible to the teaching team	canvas-submission.html	TBD
3	Teamwork contract (10%)	correctness:10	Similar to 522	Google Docs link in the submission file	TBD
4	Pick a topic		Discuss the topic with your TA or lab instructor and proceed only after your topic has been approved by one of them	Topic chosen	TBD
5	Create project structure for the Python project (40%)	mechanics:40	Create project structure & push it as a public repository in the UBC-MDS organization on Github.com Choose a relevant name Choose MIT license (can change later) Add the contributor names to CONTRIBUTORS.md Add code of conduct to CONDUCT.md Agree upon a collaboration strategy and edit CONTRIBUTING.md Outline the package you would like to build in the README.md file	LICENSE.txt /CONTRIBUTORS.md /CONDUCT.md /CONTRIBUTING.md /README.md	TBD
6	Function specifications (20%)	quality:20	Set up empty functions (with appropriate names) containing no code in the files where you will eventually write code. Write function documentation (e.g., complete docstrings).	Empty functions with documentation	TBD
7	Manage issues (10%)	mechanics:10	Create an issue for each function in the package for one person	Github issues	TBD

II) Things to do:

1) Choose a topic:

Each person

• Comes up with 1 topic for discussion, including functions to be implemented
• Posts in a Github issue and comments on others' topics

Team:

• Discuss, finalize during lab time and ask for TA's approval.

2) Teamwork contract:

Agree on below points:

• Deadline to finish the tasks given
• Availability for team meeting
• People take turns to do the release
• Rotate reviewers for each person's work every week
• ...

III) Tentative deadlines for this week:

(Can be adjusted after our discussion)

• Thursday 9AM: Topics + functions proposed (Pros + Cons if possible)
• Thursday 2PM: Feedback on other's topics and functions
• Thursday 4PM (after lab): Topic finalized and tasks assigned
• Saturday 9AM: All tasks completed
• Saturday 2PM: All tasks reviewed and merged
• Saturday 5PM: Milestone submitted on Canvas and released on Github

IV) Tentative workflow for this week:

Tue - Thu 9AM:

• Finalize teamwork contract
• Create Github issues

Thu 4PM - Fri 9AM:

• 1 person: Create project structure skeleton (name depends on the topic). @tdkhanhvu can volunteer.
• Others: Work on other documentation files in the projects (README.md, CONDUCT.md...) (put in notepad or temporary project and update in the real project later)

Fri 9AM - Sat 9AM:

• Work on function specifications (1 person / 1 function / 1 github issue)

2. Pick a topic

• Come up with a topic for your project. Discuss the topic with your TA or lab instructor and proceed only after your topic has been approved by one of them.
• Please vote by emojis.
• It would be great to also include Pros/Cons of your proposed package topic.
• Please have this ready by 2pm Thursday lab time.

Function - Suggest grade adjustment

Purpose:
Based on a predefined benchmark (90% for each lab, 90% for whole course, 85% for quiz), suggest grade adjustments for any course and return the suggested grades.

Input - three benchmark variables (course, lab, quiz), course ID
Output - summary table with suggested grade adjustment

function(courseid, benchmark_course = 0.9, benchmark_lab = 0.85, benchmark_quiz = 0.85)

Function - Summarise the grades by students

Purpose:
Calculate the average grade for all students and provide the ranking for the course selected or the whole program.
Lecturers can find students that are struggling with the courses

Input - a specified course with a default option for the entire program
Output - student’s ranking

Function: Load the course and record the grade

see #2

Function - Calculate Final Grade for each student in each course

Teamwork Contract

Tuesday Team meeting - we got together to discuss the teamwork contract. I finalized and completed the contract. We will be submitting a google doc link.

Milestone 2 Agenda

I) Task breakdown

Canvas submission instruction

#	Task	Marks	Description	Deliverables	Assignee
1	Working style (10%)	mechanics:10	Commit to git every time you work on this project with meaningful messages (graded) Follow branching approach (Create branch -> Push commits -> Create Pull Request -> Reviewed and approved by another person) Use GitHub for project-related communication Use proper grammar and full sentences throughout the project, especially in your README.		TBD
2	Follow Submission Instruction (10%)	mechanics:10	The URL for each of your your public projects’ repositories The URL to a release for each of your projects repositories	canvas-submission.html	TBD
3	Python - Write test cases and code iteratively (40%)	accuracy:20 quality:10 mechanics:10	Revisit function specifications & revise Write unit tests for 3 to 5 edge cases / function and name them after the function being tested (foo -> test_foo) Write the internal code for Python functions. Follow this flow: tests → function improvement → writing more tests → function improvement... Make sure that the tests cover all branches Update code documentation and document unit tests Use pytest package to run those tests	Unit tests written Code documentation updated Unit tests documented	TBD
4	Python - Exception handling (10%)	quality:10	Codes handle incorrect input and errors detected during execution Codes throw exceptions with useful error messages Tests confirm that the exceptions result in the expected behaviour of the function	Defensive Codes	TBD
5	R - Create project structure (20%)	mechanics:20	Create project structure & push it as a public repository in the UBC-MDS organization on Github.com Choose a relevant name Choose MIT license (can change later) Add code of conduct via usethis::use_code_of_conduct Add the team members as authors to the DESCRIPTION file Add CONTRIBUTING.md file via usethis::use_tidy_contributing() and reflect contribution strategy agreed upon Outline the package you would like to build in the README.md file	LICENSE.txt /DESCRIPTION /CONDUCT.md /CONTRIBUTING.md /README.md	TBD
6	R - Function specifications (10%)	quality:10	Set up empty functions (with appropriate names) containing no code in the files where you will eventually write code. Write function documentation (e.g., complete roxygen2 ).	Empty functions with documentation	TBD

II) Things to do:

1) Python

• Write unit tests
• Implement functions

2) R

• Setup an empty project
• Write Roxygen2 without codes

III) Tentative deadlines for this week:

(Can be adjusted after our discussion)

• Thursday 9AM: Python Code + Unit Tested Finished
• Thursday 2PM: Feedback on other's codes and unit tests
• Thursday 11:59PM: R empty project setup
• Friday 11:59PM: R Roxygen documentation finished
• Saturday 2PM: All tasks reviewed and merged
• Saturday 5PM: Milestone submitted on Canvas and released on Github

IV) Tentative workflow for this week:

Tue - Thu 9AM:

• Write unit tests for Python
• Write code implementation for Python

Thu 4PM - Thu 11:59PM:

• 1 person: Create project structure skeleton for R (name depends on the topic). rgtracker?
• Others: Work on feedback for Python codes and unit tests

Fri 0AM - Fri 11:59PM:

• Work on function specifications for R

Function - Summarize the grades by course

Purpose:
Provides summary statistics on the courses
Lecturers can benchmark the difficulty based on the average grades for all courses

Input -
method (default = summary, across_summary)

Output:
summary: summary statistics on each course - Mean / Median / Quantile 1,2,3,4
across_summary: based on average grade for each course, rank the courses in the decreasing order

Some Ideas about the function:
For each students, calculate the overall grade by using the studnets grades and the corresponding assignment assessments (each course has different assessments and different number of assignment)
Store them into a dataframe (each row represents a student and each column represent a course)
Calculate summary statistics for each course
Print the output based on the method

Release + Submit to Canvas

License Discussion

See this issue for a discussion on the license