# ACTS Data Aggregation Tool

## Overview

The ACTS Data Aggregation Tool is a standalone application that processes institutional data from ACTS Excel templates and generates aggregated reports for publication. This tool validates your data, performs complex aggregations, and outputs publication-ready CSV files and institutional review reports.

## Features

- **Data Validation**: Comprehensive validation of your ACTS Excel template including schema and business rule checks
- **Automated Aggregation**: Advanced data aggregation with quantile calculations
- **Institutional Reports**: Generated institutional review (IR) reports in Excel format
- **Cross-Platform**: Available for Windows, macOS, and Linux
- **Interactive & Non-Interactive Modes**: Flexible execution options for different use cases

## System Requirements

### All Platforms
- No Python installation required (standalone executable)
- Minimum 4GB RAM recommended
- 200MB free disk space

### Windows
- Windows 10 or later
- 64-bit architecture

### macOS
- macOS 10.14 (Mojave) or later
- Apple Silicon processor

### Linux
- Ubuntu 18.04+ / CentOS 7+ / Fedora 30+ (or equivalent)
- glibc 2.17 or later

## Download & Installation

1. Download the appropriate executable for your operating system:
   - **Windows**: `acts_aggregator.exe`
   - **macOS/Linux**: `acts_aggregator`

2. **Windows**: No additional setup required
3. **macOS/Linux**: Make the file executable:
   ```bash
   chmod +x acts_aggregator
   ```

## Quick Start

### Prepare Your Data
Ensure you have your ACTS Excel template file ready (e.g., `example_2019_20.xlsx`). The file should contain all required worksheets with properly formatted data according to ACTS specifications.

### Run the Application

#### Windows
```cmd
# Interactive mode 
acts_aggregator.exe

# Command-line mode
acts_aggregator.exe --unitid 123456 --year 2019-20 --input "example_2019_20.xlsx" --output-folder "./results" --non-interactive
```

#### macOS/Linux
```bash
# Interactive mode 
./acts_aggregator

# Command-line mode
./acts_aggregator --unitid 123456 --year 2019-20 --input "example_2019_20.xlsx" --output-folder "./results" --non-interactive
```

## Usage Examples

### Example 1: Interactive Mode 
This mode will prompt you for all required information step by step.

**Windows:**
```cmd
acts_aggregator.exe
```

**macOS/Linux:**
```bash
./acts_aggregator
```

You'll be prompted for:
- Institution's IPEDS UNITID
- Academic year (e.g., 2019-20)
- Full path to your ACTS Excel template file
- Output folder location
- Confirmation to continue after validation checks

### Example 2: Command-Line Mode with example_2019_20.xlsx
For automated processing or when you know all required parameters.

**Windows:**
```cmd
# Process the example file with UNITID 999999
acts_aggregator.exe --unitid 999999 --year 2019-20 --input "example_2019_20.xlsx" --output-folder "C:\ACTS_Results" --non-interactive

# Process with different institution ID
acts_aggregator.exe --unitid 123456 --year 2019-20 --input "C:\Data\example_2019_20.xlsx" --output-folder "C:\Output" --non-interactive
```

**macOS/Linux:**
```bash
# Process the example file with UNITID 999999
./acts_aggregator --unitid 999999 --year 2019-20 --input "example_2019_20.xlsx" --output-folder "./results" --non-interactive

# Process with different institution ID
./acts_aggregator --unitid 123456 --year 2019-20 --input "/path/to/example_2019_20.xlsx" --output-folder "/path/to/output" --non-interactive
```

### Example 3: Processing Multiple Years
```bash
# Process 2019-20 data
./acts_aggregator --unitid 123456 --year 2019-20 --input "example_2019_20.xlsx" --output-folder "./results_2019_20" --non-interactive

# Process 2020-21 data
./acts_aggregator --unitid 123456 --year 2020-21 --input "template_2020_21.xlsx" --output-folder "./results_2020_21" --non-interactive
```

## Command-Line Options

| Option | Description | Default | Required |
|--------|-------------|---------|----------|
| `--unitid` | Institution's IPEDS UNITID | 999999 | No |
| `--year` | Academic year (format: YYYY-YY) | 2019-20 | No |
| `--input` | Path to ACTS Excel template file | `./testing/ACTS_Template_AY{year}_test_version_full.xlsx` | No |
| `--output-folder` | Output directory for generated files | `./output` | No |
| `--non-interactive` | Run without user prompts | False | No |

## Input File Requirements

### ACTS Excel Template Structure
Your Excel file must contain the required worksheets for your academic year:

- **Metadata sheets**: Instructions and configuration
- **Data sheets**: Student data, enrollment, financial aid, etc.
- **Proper formatting**: Column headers and data types as specified in ACTS guidelines
- **Complete data**: All required fields populated

### Supported File Formats
- Excel files (.xlsx, .xls)
- Files must follow ACTS template structure

## Output Files

The application generates the following files in your specified output folder:

1. **`ACTS_{UNITID}_{YEAR}_data_aggregation.csv`**
   - Main aggregated data file for publication
   - Contains processed and aggregated institutional data

2. **`ACTS_{UNITID}_{YEAR}_ir_report.xlsx`**
   - Institutional Review (IR) report
   - Multiple worksheets with analysis and summaries

3. **`workbook.json`** (if validation fails)
   - Detailed validation error report

4. **`review_file.json`**
   - Review summary of input data

5. **`business.json`**
   - Business rules validation results

## Troubleshooting

### Common Issues

#### File Not Found Error
```
ERROR: Input file not found: example_2019_20.xlsx
```
**Solution**: 
- Ensure the file path is correct
- Use absolute paths if the file is not in the current directory
- Check file permissions

#### Validation Errors
```
ERROR: Workbook validation failed.
```
**Solution**:
- Check the generated `workbook.json` file for detailed error information
- Ensure your Excel file follows ACTS template structure
- Verify all required worksheets are present

#### Permission Denied (macOS/Linux)
```
Permission denied: ./acts_aggregator
```
**Solution**:
```bash
chmod +x acts_aggregator
```

### Platform-Specific Notes

#### Windows
- Use backslashes (`\`) or forward slashes (`/`) in file paths
- File paths with spaces should be enclosed in quotes: `"C:\My Files\template.xlsx"`

#### macOS
- On first run, you may need to allow the application in System Preferences > Security & Privacy
- Use forward slashes (`/`) in file paths

#### Linux
- Ensure the executable has proper permissions (`chmod +x acts_aggregator`)
- Some distributions may require additional library installations


## Technical Details

### Processing Pipeline
1. **Input Validation**: Schema and format checking
2. **Data Loading**: Excel file parsing and data extraction
3. **Business Rules**: Logic validation
4. **Transformation**: Data preparation for aggregation
5. **Aggregation**: Statistical calculations and groupings
6. **Output Generation**: CSV and Excel report creation

### Performance Notes
- Processing time varies by data size (typically 2-10 minutes)
- Memory usage scales with input data size
- Recommend closing other applications for large datasets
