Automaaval/README.md

# <div align="center">AvalCal – Automatic Evaluation & Presentation Generator</div>

---

## <div align="center">Overview</div>

AvalCal is a Python-based automation tool designed to process student evaluation spreadsheets and automatically generate formatted PowerPoint presentations with performance summaries and student imagery.

The system was developed to simplify the preparation of evaluation reports and visual presentations by automating:

- Excel data processing
- Evaluation classification
- Student ranking
- PowerPoint slide editing
- Automatic image insertion
- Presentation generation

The application combines spreadsheet manipulation with automated PowerPoint editing to accelerate academic and institutional reporting workflows. :contentReference[oaicite:0]{index=0}

---

# <div align="center">Main Features</div>

## Automatic Excel Processing

- Import `.xlsx` evaluation files
- Automatic data cleanup
- Column normalization
- Quantitative score processing
- Qualitative classification analysis

---

## Student Classification

The system automatically categorizes students into:

- MUITO BOM
- SUFICIENTE
- MEDIOCRE
- MAU

---

## PowerPoint Automation

- Automatic PowerPoint generation
- Dynamic text replacement
- Student number insertion
- Automatic photograph placement
- Slide customization

---

## Image Integration

- Automatic student image loading
- Dynamic image positioning
- PowerPoint image rendering

---

# <div align="center">Technologies Used</div>

| Technology | Purpose |
|:---:|:---:|
| Python | Main programming language |
| Pandas | Excel data processing |
| python-pptx | PowerPoint automation |
| Tkinter | File selection interface |
| OpenPyXL | Excel compatibility |
| OS Library | File management |

---

# <div align="center">Project Structure</div>

```txt
.
├── AvalCal.ipynb
├── Apresentação Comportamentos.pptx
├── Fotos/
├── README.md
```

---

# <div align="center">Requirements</div>

## Python Version

```txt
Python 3.10+
```

---

# <div align="center">Required Libraries</div>

Install dependencies:

```bash
pip install pandas python-pptx openpyxl
```

---

# <div align="center">Running the Application</div>

Execute the notebook:

```bash
jupyter notebook
```

Open:

```txt
AvalCal.ipynb
```

---

# <div align="center">Input Files</div>

## Excel File

The application expects an evaluation spreadsheet in:

```txt
.xlsx
```

format.

The Excel file is selected dynamically through a file dialog interface.

---

## PowerPoint Template

Required template:

```txt
Apresentação Comportamentos.pptx
```

This presentation is automatically modified by the system.

---

## Student Photographs

Student images must be placed inside:

```txt
/Fotos
```

directory.

---

# <div align="center">Main Functionalities</div>

## Excel Cleaning & Transformation

The notebook automatically:

- Merges rows
- Renames columns
- Removes unnecessary fields
- Formats scores
- Calculates final values
- Cleans missing values

---

## Quantitative & Qualitative Analysis

The system processes:

- Quantitative grades
- Qualitative classifications
- Attendance/suspension indicators
- Behavioral metrics

---

## Automatic Presentation Population

The PowerPoint template is dynamically updated with:

- Student numbers
- Performance rankings
- Student photographs
- Evaluation highlights

---

# <div align="center">Generated Output</div>

The system generates:

- Automated PowerPoint presentations
- Structured evaluation summaries
- Visual student performance reports

---

# <div align="center">Workflow</div>

```txt
Excel Input
     ↓
Data Cleaning
     ↓
Classification Processing
     ↓
Student Ranking
     ↓
PowerPoint Population
     ↓
Final Presentation Export
```

---

# <div align="center">User Interface</div>

The application includes:

- File picker dialog
- Automated processing workflow
- Dynamic PowerPoint editing
- Automatic image handling

---

# <div align="center">Intended Use Cases</div>

- Academic evaluations
- Military training assessments
- Student performance analysis
- Behavioral reporting
- Institutional presentations
- Automated evaluation dashboards

---

# <div align="center">Future Improvements</div>

- GUI application version
- PDF export
- Automatic charts
- Multi-template support
- AI-based evaluation insights
- Database integration
- Web dashboard version

---

# <div align="center">Disclaimer</div>

This project was developed for academic and institutional automation purposes.

Users remain responsible for validating all generated evaluation data before official usage.

---

# <div align="center">Author</div>

José Garcia  
Data Scientist  
PhD Researcher – Digitalization Engineering