Metadata-Version: 2.4
Name: mun-feas-ga-data
Version: 0.4.1
Summary: Graduate Attribute (GA) data tools for Memorial's Faculty of Engineering and Applied Science
License-File: LICENSE
Author: Jonathan Anderson
Author-email: jonathan.anderson@mun.ca
Requires-Python: >=3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: click (>=8.3.0,<9.0.0)
Requires-Dist: jinja2 (>=3.1.0,<4.0.0)
Requires-Dist: markdown (>=3.7,<4.0)
Requires-Dist: more-itertools (>=11.0,<12.0)
Requires-Dist: openpyxl (>=3.1.5,<4.0.0)
Requires-Dist: pandas (>=2.3.3,<3.0.0)
Requires-Dist: python-dotenv (>=1.2.3,<2.0.0)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: tqdm (>=4.70.1,<5.0.0)
Description-Content-Type: text/markdown

# GAD: GA Data tool

https://memorialu.gitlab.io/Engineering/ContinuousImprovement/gad

## Install

To install the latest stable version from [PyPI](pypi.org), run `pip install mun-feas-ga-data`.

To install the latest development version, clone the Git repository at https://gitlab.com/MemorialU/Engineering/continuousimprovement/gad and install with `pip install -e .`.


## Setup

Before you start using the GA data tools, it's helpful to set up some environment variables so that you don't have to type a bunch of details every time you run `gad`:

```sh
GAD_EMAIL_TEMPLATE_DIR=.email-templates
GAD_SENDER=Your Name <your.email@mun.ca>
```

The first of these environment variables will tell `gad` to look for email templates within a directory called `.email-templates` in your current working directory. This means that, if you change to a specific directory like `Fall/2026–27`, it will use email templates from `Fall/2026–27/.email-templates`: this makes it straightforward to use different template in different semesters as we update wording, etc. Defining these variables is optional, but if you don't define them you'll need more command-line arguments, e.g.:

```
gad email --from "Your Name <your.email@mun.ca>" --template-dir .email-templates [... other arguments ...]
```


## Get GA data

### Email instructors

#### Inform instructors of GA data requirements

Before the semester begins, ... TODO ...

```sh
gad email --curriculum-map ENCM-xxxx.xlsx --curriculum-map ENEL-xxxx.xlsx --department ECE inform instructors.csv
```

You can save the resulting emails via `-e` / `--save-emails` ... TODO ...


#### Request GA data from instructors

After the semester's grades have been compiled, ... TODO ...

```sh
gad email --curriculum-map ENCM-xxxx.xlsx --curriculum-map ENEL-xxxx.xlsx --department ECE request instructors.csv
```

You can save the resulting emails via `-e` / `--save-emails` ... TODO ...


### Courses requiring only the course grade

Sometimes we only need the course grade and not other, more detailed, assessment tools
from a course. This is particularly the case for courses we don't control (e.g., service
courses from other faculties), but it can also be helpful when an instructor is hard to
reach (e.g., a PCI from a previous semester) or we just don't want to bother instructors
with data we can retrieve ourselves.

To get this data, download the SWRF510 report for the semester in question from Banner,
then run `gad extract-course-grades`, passing it the SWRF510 CSV file, as well as the
course subject and course code you're interested in. For example, to extract ENGI 1020
grades from a particular SWRF510 report, you might run:

```sh
gad extract-course-grades swrf510_8804673.csv ENGI 1020
```

By default, this will write results into a file named according to the ATsheet convention,
e.g., `ENGI1010_W2026_GAdata.csv`. If that file already exists, `extract-course-grades`
will confirm whether you want to overwrite the existing file. You can specify a different
filename using the `-o` or `--output` option, e.g.:

```sh
gad extract-course-grades swrf510_8804673.csv ENGI 1020 --output ENGI1020.csv
```


## Validate GA data

To check that GA data contained in ATsheet or FEAMS format matches aligns with a
curriculum map, use the `validate` command:

```
$ gad validate ga-data/ --curriculum-map ENEL-curriculum.xlsx
ECE 4300 (Spring 2024–25) contains 81 results
1 warning(s):
 - contains 3 unnamed columns

ECE 4500 (Spring 2024–25) contains 62 results
ECE 4800 (Spring 2024–25) contains 39 results
1 warning(s):
 - contains 27 unnamed columns
```

You can, additionally, identify assessment tools that do not appear in the curriculum
map using the `-u` / `--unmapped-tools` option:

```
$ gad validate --unmapped-tools ga-data/ --curriculum-map ENEL-curriculum.xlsx
ECE 4300 (Spring 2024–25) contains 81 results
2 warning(s):
 - contains 3 unnamed columns
 - 3 unmapped tools: Final exam – design questions, Assignment – evaluate and compare designs, Design labs

ECE 4500 (Spring 2024–25) contains 62 results
1 warning(s):
 - 5 unmapped tools: Assignments, Labs – debugging sections, Design assignment and exam questions, Labs, Labs — info sources

ECE 4800 (Spring 2024–25) contains 39 results
2 warning(s):
 - contains 27 unnamed columns
 - 5 unmapped tools: Course grade , Labs – gather info, Labs – synthesize info, Assignments,  labs - communication
```


## Summarize indicators and assessment tools

To summarize all of the indicators that have been mapped to GAs in a particular
curriculum map, use the `indicator list` command with an argument of the curriculum map
file:

```
$ gad indicator list ENEL-curriculum.xlsx
GA 1: A knowledge base for engineering
KB:1	Demonstrate competence in mathematics
KB:2	Demonstrate competence in natural sciences
KB:3	Demonstrate competence in the principles of analog circuits
KB:4	Demonstrate competence in the principles of software development
KB:5	Demonstrate competences in the principles of digital logic and systems
KB:6	Demonstrate competence in the principles of signals and communications
KB:7	Demonstrate completence in the principles of electromagnetism
KB:8	Demonstrate competence in the principles of power and machines

GA 2: Problem analysis
PA:1	Formulate problem statements
PA:2	Analyze and solve engineering problems
[...]
```

To summarize all of the assessment tools that have been mapped to all of the indicators,
use the `indicator map` command:

```
$ gad indicator map ENEL-curriculum.xlsx
GA 1: A knowledge base for engineering
KB:1	Demonstrate competence in mathematics
 I: MATH 1001 Course grade
 I: MATH 2050 Course grade
 D: ECE 5100 Course grade
 D: ENGI 4430 Course grade
 A: No assessment tools

KB:2	Demonstrate competence in natural sciences
 I: CHEM 1050 Course grade
 [...]
```

To obtain statistics about these indicators, add the `--stat` flag:

```
$ gad indicator map --stat ENEL-curriculum.xlsx
GA 1: A knowledge base for engineering
KB:1         2       2       0
KB:2         3       0       0
KB:3         1       3       0
KB:4         1       1       0
KB:5         1       1       0
KB:6         1       2       0
KB:7         1       1       0
KB:8         1       1       0

GA 2: Problem analysis
PA:1         0       1       0
PA:2         2       7       1

[...]
```


## Plot data

### Per-course assessment tool results

To plot the assessment tool results contained in a directory of result files, use the `plot` command:

```
$ gad plot tools ga-data-dir/ --curiculum-map ENEL-curriculum.xlsx --output-dir plots-ENEL/
```

You can also specify the output format (PDF, PNG, SVG, etc.) using the `-f`/`--format`
argument.


## Interoperate with FEAMS

To convert GA data (in ATsheets, FEAMS or both) into a unified directory ready for
[FEAMS](https://gitlab.com/MemorialU/Engineering/continuousimprovement/feams) ingestion,
use the `feamsify` command:

```
$ gad feamsify ga-data/ --curriculum-map ENEL-map.xlsx --output FEAMS-ENEL/
```

* `ga-data/`: a directory containing ATsheets and/or FEAMS data files
* `ENEL-map.xlsx`: curriculum map for an Engineering program (here, Electrical)
* `FEAMS-ENEL/`: the directory to write FEAMS-formatted files into for FEAMS parsing


## Work on GAD

To hack on GAD, install [Python](https://www.python.org/downloads) and [Poetry](https://python-poetry.org/docs/#installation), check out this repository and then run `poetry install`. By default, this will install GAD in editable mode: make changes to the code and they will be immediately reflected when you next run `gad`.

