# EAAI-2026-model-assignment

## Submitted abstract 

Dimensionality Reduction Adventures with Animal Faces introduces students to Principal Component Analysis (PCA) through conceptual reasoning, algorithmic implementation, and applied experimentation. Students begin by examining PCA notation and the relationships between the original data, principal components, and reconstructed data, building a clear understanding of dimensional transformations. They then implement PCA using Singular Value Decomposition (SVD), writing core methods for transformation and reconstruction, and validating their results against scikit-learn's implementation.

Next, students apply PCA to a subset of the real-world Animal Faces dataset. They investigate how varying the number of components affects explained variance and reconstruction quality, using visualizations to reason about the trade-off between compression and information loss. Students also interpret the learned components, connecting mathematical abstractions to recognizable image features and reflecting on the strengths and limitations of linear dimensionality reduction.

The assignment concludes with a challenging, low-stake extension where adventurous students implement convolutional autoencoders on the same dataset. By experimenting with design and training choices, they compare reconstructions with PCA and reason about when nonlinear methods may be advantageous.

Designed for an introductory machine learning audience, the assignment is self-contained, includes starter code and utility functions, and highlights both conceptual understanding and critical reasoning in dimensionality reduction.

## Audience and context

This assignment is part of the Unsupervised Machine Learning course in our [Master of Data Science program](https://masterdatascience.ubc.ca/) (MDS) at the University of British Columbia. MDS is an intensive 10-month professional program designed for a diverse audience, including learners transitioning into data science. The program intentionally has minimal prerequisites: one course in programming, one in statistics and probability, and one in either introductory calculus or linear algebra.

The curriculum follows a block structure, where students complete short 1-credit modules in each block. This course takes place in Block 5, at a point when students are already familiar with deep learning and Convolutional Neural Networks. You can find the courses offered in each block, along with their descriptions, [here](https://ubc-mds.github.io/descriptions/). 

We maintain our lecture notes and teaching materials for the course on GitHub Enterprise. While those internal materials are not publicly accessible, here are publicly available versions of the notes from the 2024–25 offering:

- [PCA introduction](https://ubc-mds.github.io/DSCI_563_unsup-learn/lectures/notes/03_PCA-intro.html)
- [More PCA](https://ubc-mds.github.io/DSCI_563_unsup-learn/lectures/notes/04_More-PCA-LSA-NMF.html)
- [PCA class demo](https://ubc-mds.github.io/DSCI_563_unsup-learn/lectures/002-regressors-Varada-lectures/03_class-demo.html)


## Learning objectives

By completing this assignment, your students will be able to:

- **Explain PCA fundamentals** by identifying the roles and dimensions of the matrices $X$, $W$, $Z$, and $\hat{X}$ in dimensionality reduction.  
- **Analyze reconstruction error** for both typical examples and outliers, reasoning about information retention and loss.  
- **Implement PCA from scratch** using Singular Value Decomposition (SVD), including methods for transformation and reconstruction, and validate results against `scikit-learn`.  
- **Apply PCA to real data** (Animal Faces), select an appropriate number of components, and interpret the meaning of the learned components.  
- **(Stretch goal)** Develop and train a convolutional autoencoder on the same dataset, experiment with architectural and training choices, and compare its performance with PCA.

## Dataset 
- The assignment begins with a **toy dataset** for warm-up exercises, helping students practice PCA mechanics before scaling up.  
- The main dataset is a **subset of the [Animal Faces](https://www.kaggle.com/datasets/andrewmvd/animal-faces) dataset** (1,500 grayscale face images of cats, dogs, and wild animals).  
- Grayscale images are used to keep computation light and feasible on student laptops.  
- **Size ~70 MB**. The dataset is not included in this submission but will be made available in the camera-ready version.

## Files in the assignment folder
```
├── environment.yml # conda environment with required packages
├── index.html # Table with summary information about the assignment
├── README.md # This file
├── LICENSE.md # The license file
├── solutions # Instructor version with solutions
│   ├── data
│   │   └── animal_faces.pkl # Download from https://github.com/kvarada/EAAI26-PCA-assignment-data/blob/main/animal_faces.pkl.zip
│   ├── img/
│   ├── model_assignment_PCA.html
│   ├── model_assignment_PCA.ipynb
│   └── utils.py # Helper functions
└── student # Student version (no solutions)
    ├── data
    │   └── animal_faces.pkl # Download from https://github.com/kvarada/EAAI26-PCA-assignment-data/blob/main/animal_faces.pkl.zip
    ├── img/
    ├── model_assignment_PCA.ipynb
    └── utils.py # Helper functions
```

- **Autograder support**: Warm-up exercises include autograder tests to provide immediate feedback and ease grading.
- A license file will be added for the camera-ready version. 

## Usage instructions

### Viewing the assignment
- **Instructor version with solutions:** Open `solutions/model_assignment_PCA.html`.  
- **Student version without solutions:** Open `student/model_assignment_PCA.html`.  

*(The HTML files provide a static view of the notebooks without needing to run code.)*

### Set up 
1. Make sure you have `anaconda` or `miniconda` or `miniforge` installed.  
2. Create the assignment environment:  
   ```conda env create -f environment.yml```

### Working with modifying the assignment 

1. Open the instructor or student notebook in either [`Jupyter Lab`](https://jupyter.org/) or [`VS Code`](https://code.visualstudio.com/) using the appropriate file: 
    - Instructor version: `solutions/model_assignment_PCA.ipynb`
    - Student version: `student/model_assignment_PCA.ipynb`

2. Select the `pca-assignment` environment as the notebook kernel.
3. Ensure the dataset file `animal_faces.pkl` is located in the `data/` directory.
4. Run the notebook cells sequentially to complete the assignment.

### Creating a student version without solutions 
If you modify the assignment and want to create a student version with your modifications follow the instructions below: 

1. On command line, navigate to the assignment directory.
2. Make sure to activate the assignment environment with `conda activate pca-assignment`
3. Create a student version without solutions with the following Otter Grader command. 

```otter assign solutions/model_assignment_PCA.ipynb .```

4. This will create two new folders: `autograder` and `student`. You can use the files created in the `autograder` folder with [`Gradescope`](https://www.gradescope.com/) for autograding. 

## Acknowledgment  

I would like to thank our Master of Data Science students from previous years for their valuable feedback. I am also grateful to instructors Mike Gelbart and Rodolfo Lourenzutti for their involvement and for contributing ideas to this assignment.