README.md 6.22 KB
Newer Older
Christopher Bohn's avatar
Christopher Bohn committed
1
2
3
4
5
6
7
8
9
# Analyze Grades

This program will produce statistics, by major, for selected assignments in
selected courses.

## Preparation

### Dependencies

10
11
12
13
14
You can use this tool either from the cse.unl.edu Linux server or an another
Linux installation that you control.

If (and only if) you download and run the tool on your own Linux system, then:

15
- [x] You need Python. I think Python 3.6 and newer will work fine.
Christopher Bohn's avatar
Christopher Bohn committed
16

17
18
19
20
- [x] You need the `canvasapi` module. Run
  ```
  pip install canvasapi
  ```
Christopher Bohn's avatar
Christopher Bohn committed
21

22
23
24
25
26
If you run the tool from cse.unl.edu then you can launch it from your
cse.unl.edu account with the command `~cabohn/abet-oat/analyze_grades.py`.

Either way, you will need a Canvas API key.

Christopher Bohn's avatar
Christopher Bohn committed
27
28
### Getting a Canvas API Key

29
To interface with Canvas, you need a Canvas API Key.
Christopher Bohn's avatar
Christopher Bohn committed
30

31
32
- [ ] Log into Canvas and click on the *Account* icon in the left gutter. In 
  the resulting menu, click on *Settings*.
Christopher Bohn's avatar
Christopher Bohn committed
33

34
  ![Go to your Canvas account settings](README-images/canvas-account-settings.png)
Christopher Bohn's avatar
Christopher Bohn committed
35

36
37
38
39
- [ ] On your account settings page, scroll down until you see the `+ New
  Access Token` button. Click on that button. Fill out the fields in the popup 
  window and click on `Generate Token`. You will then get a new popup window 
  with the token's details. ***DO NOT close this window yet***.
Christopher Bohn's avatar
Christopher Bohn committed
40

41
42
43
44
45
46
47
  ![Canvas API Key details](README-images/canvas-token-details.png)
  
- [ ] Copy the `abet_oat-example.json` file to `~/.abet_oat.json` and open
  `~/.abet_oat.json` for editing. Delete the text *Your Canvas API Key goes 
  here* (leave the opening- and closing-quotes). Copy the token from your
  browser's popup window and paste it between the opening- and closing-quotes 
  in `~/.abet_oat.json`.
Christopher Bohn's avatar
Christopher Bohn committed
48

49
  ![Copy/Paste your Canvas API Key into config.py](README-images/abet_oat-json.png)
Christopher Bohn's avatar
Christopher Bohn committed
50

51
52
- [ ] Override the default file permissions: `chmod 600 ~/.abet_oat.json`

53
### You no longer need to...
Christopher Bohn's avatar
Christopher Bohn committed
54

55
56
You no longer need to manually retrieve students' majors from MyRed. The program
now retrieves students' majors from directory.unl.edu.
Christopher Bohn's avatar
Christopher Bohn committed
57

58
59
You no longer need to maintain a rosters file. The program now retrieves your
courses from Canvas for a specified semester.
Christopher Bohn's avatar
Christopher Bohn committed
60
61
62
63
64

## Run the program

Start the program with
```
Christopher Bohn's avatar
Christopher Bohn committed
65
~cabohn/abet-oat/analyze_grades.py
Christopher Bohn's avatar
Christopher Bohn committed
66
```
67
68
69
70
You will be prompted to confirm the program's best-guess of the semester you
want to analyze. Confirm the semester or select a different semester. You will
then be presented with a list of the courses that you are associated with for
that semester. (Note that this is now based on Canvas courses, so if you
71
merged courses then it will only present the courses as sthey appear in
72
Canvas.) Select one.
Christopher Bohn's avatar
Christopher Bohn committed
73
74
75

![Select the course to analyze](README-images/selecting-a-course.png)

76
77
78
79
80
81
Please wait patiently at ths step. To determine each student's major, the
program must access Canvas to determine their login name and then must access
the UNL directory to determine their major(s). Canvas queries in particular can
take longer than you might like. There is a progress bar to reassure you that
the program is, well, progressing.

82
83
84
85
86
87
88
89
90
91
After the students' majors have been retrieved, you'll be given the option of
printing statistics for the entire course or to print statistics for each
individual section. In most cases you'll want statistics for the entire course.
The only example I can think of in which printing statistics for each section
would be desirable is the capstone program, in which we don't want to commingle
the statistics from students in their first year of capstone with those from
students in their second year of capstone.

You'll then be presented with an assignment group, and after you select one,
you'll be presented with a list of assignments in that group. Select one.
Christopher Bohn's avatar
Christopher Bohn committed
92
93
94

![Select the assignment to analyze](README-images/selecting-an-assignment.png)

95
96
After you select the assignment, you'll be provided the statistics for it.
(Again, please be patient, as the Canvas queries can take a few seconds.)
Christopher Bohn's avatar
Christopher Bohn committed
97

98
99
100
101
102
![Getting assignment statistics](README-images/assignment-statistics.png)

You will then be given then option to select another assignment from the same
course. If you choose not to do so, then you will be given the option to select
a different course.
Christopher Bohn's avatar
Christopher Bohn committed
103
104
105
106
107
108
109
110

Right now this program will only analyze a full assignment. If you're using a
particular question off of an exam or quiz, you're going to have to do that
analysis manually for now. I know how to get data from individual Canvas quiz
questions -- so if we want to use this program going forward then I can make
that happen, but for my immediate purposes it wasn't necessary so I didn't add
that code.

111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
## Notes

- The program will provide statistics for *all* computing majors, explicitly
  stating when there are no students in a particular computing major in the
  course. The program will also provide statistics for non-computing majors
  represented in the course: even though this is not required for OAT, you may
  find it interesting. (Due to students taking multiple majors, the numbers of
  students may exceed the number of students in the course.) The program does
  *not* report statistics for computing minors.
- For majors with particularly long names (*e.g.*, "Criminology and Criminal
  Justice"), the formatting may be a little off.
- The program only works at the assignment level. If you are making an OAT
  assessment with a specific quiz/exam question (and the quiz/exam is a Canvas
  quiz), let me know and I'll add question-level functionality.

126
127
128
If you print statistics for each individual section, you may see advisories
indicating that one or more students could not be located. If you pay close
attention, these are students who dropped the course.
129

Christopher Bohn's avatar
Christopher Bohn committed
130
131
132
## For the curious, the code

- `analyze_grades.py` contains the `main` function and is pretty simple code,
133
134
  a hair over 100 lines. I hope it's readable enough that I don't need to
  describe it.
Christopher Bohn's avatar
Christopher Bohn committed
135
136
- `config.py` you've already met.
- `majors.py` defines a data structure to hold information about majors and 
137
138
139
  then defines our three computing majors as well business majors (so that the
  program lumps Raikes students in business majors with non-Raikes students in
  business majors).
Christopher Bohn's avatar
Christopher Bohn committed
140
141
142
- `common_functions.py` has a few utility functions that I made for another 
  project. I only use one of them here.
- `api/canvas_classes.py` is also from another project; it has a slew of 
143
  classes that use the `canvasapi` package.