README.md

# Analyze Grades

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

## Preparation

### Dependencies

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:

- [x] You need Python. I think Python 3.6 and newer will work fine.

- [x] You need the `canvasapi` module. Run
  ```
  pip install canvasapi
  ```

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.

### Getting a Canvas API Key

To interface with Canvas, you need a Canvas API Key.

- [ ] Log into Canvas and click on the *Account* icon in the left gutter. In 
  the resulting menu, click on *Settings*.

  ![Go to your Canvas account settings](README-images/canvas-account-settings.png)

- [ ] 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***.

  ![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`.

  ![Copy/Paste your Canvas API Key into config.py](README-images/abet_oat-json.png)

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

### You no longer need to...

You no longer need to manually retrieve students' majors from MyRed. The program
now retrieves students' majors from directory.unl.edu.

You no longer need to maintain a rosters file. The program now retrieves your
courses from Canvas for a specified semester.

## Run the program

Start the program with
```
~cabohn/abet-oat/analyze_grades.py
```
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
merged courses then it will only present the courses as sthey appear in
Canvas.) Select one.

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

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.

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.

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

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.)

![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.

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.

## 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.

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.

## For the curious, the code

- `analyze_grades.py` contains the `main` function and is pretty simple code,
  a hair over 100 lines. I hope it's readable enough that I don't need to
  describe it.
- `config.py` you've already met.
- `majors.py` defines a data structure to hold information about majors and 
  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).
- `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 
  classes that use the `canvasapi` package.