Skip to content

fix(docs): align published statistics with pipeline data and remove em dashes #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aleattene merged 4 commits into from
Aug 31, 2026
Merged

fix(docs): align published statistics with pipeline data and remove em dashes #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4d874e8
fix(report): align published statistics with pipeline CSV data
aleattene Aug 31, 2026
4be99d5
fix(readme): correct students vs enrollments and BQ2 ranking
aleattene Aug 31, 2026
0e96575
style(docs): remove em dashes and arrows from public documents
aleattene Aug 31, 2026
7f24bb3
chore: add md-files to ignore list
aleattene Aug 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,6 +225,8 @@ CLAUDE*.md
PROJECT_SPEC.md
TODO*.md
SKILLS*.md
HANDOFF_PROMPT.md
ROADMAP.md
ADR*.md
docs/
*.parquet
23 changes: 12 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,11 @@

A **product analytics case study** that analyzes student retention and
drop-out in online education using the
[Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset),
~32,000 students, 7 courses, complete behavioral clickstream.
[Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset):
32,593 enrollments by 28,785 distinct students, 7 courses, complete
behavioral clickstream.

The project follows a **SQL - driven analytical pipeline**: DuckDB as a
The project follows a **SQL-driven analytical pipeline**: DuckDB as a
local-first analytical database, descriptive and inferential statistics,
and a Looker Studio dashboard.

Expand Down Expand Up @@ -75,7 +76,7 @@ Every analytical pattern in this project is portable to other domains:

```
project_root/
├── run_pipeline.py # Entrypoint — orchestrates ETL
├── run_pipeline.py # Entrypoint: orchestrates ETL
├── src/
│ ├── config.py # Paths, constants, env vars
│ ├── db/connection.py # DB abstraction (DuckDB now, BQ later)
Expand Down Expand Up @@ -159,8 +160,8 @@ pytest tests/test_smoke.py -v
## Dataset

The [Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset)
contains data about ~32,000 students across 7 course presentations at
The Open University (UK).
contains 32,593 course enrollments by 28,785 distinct students across
7 modules (22 presentations) at The Open University (UK).

| Table | Description | Key columns |
|-------|-------------|-------------|
Expand All @@ -172,8 +173,8 @@ The Open University (UK).
| vle | VLE resource metadata | activity_type |
| courses | Course metadata | module_presentation_length |

**Target variable**: `final_result` ∈ {Pass, Distinction, Fail, Withdrawn}
— binarized as Completed (Pass + Distinction) vs Not completed (Fail + Withdrawn).
**Target variable**: `final_result` ∈ {Pass, Distinction, Fail, Withdrawn},
binarized as Completed (Pass + Distinction) vs Not completed (Fail + Withdrawn).

> **Citation**: Kuzilek, J., Hlosta, M., & Zdrahal, Z. (2017).
> Open University Learning Analytics dataset.
Expand All @@ -190,8 +191,8 @@ In summary:
- **BQ1**: roughly 1 in 3 enrollments ends in explicit withdrawal; dropout
clusters around assessment deadlines and grade releases
- **BQ2**: all 8 early behavioral signals (first 28 days) are significantly
associated with dropout; active days and total clicks dominate the effect
size ranking
associated with dropout; engagement volume (engagement decile, active days,
total clicks) dominates the effect size ranking
- **BQ3**: behavior predicts outcome far more strongly than demographics;
within every education level, high engagement beats low engagement
- **BQ4**: completion rates range from 37% to 71% across the 7 modules;
Expand All @@ -209,7 +210,7 @@ In summary:
| [Executive Report](reports/REPORT.md) | Full BQ1–BQ5 analysis with figures and numbers |
| [Methodology](docs/METHODOLOGY.md) | Statistical approach, design choices, trade-offs |
| [Transferability](docs/TRANSFERABILITY.md) | Pattern portability to SaaS, subscriptions, fitness |
| [Cloud Migration](docs/MIGRATION.md) | DuckDB → BigQuery path, gaps and checklist |
| [Cloud Migration](docs/MIGRATION.md) | DuckDB to BigQuery path, gaps and checklist |
| [ADR](docs/ADR.md) | 7 architectural decisions with rationale |
| [Testing](docs/TESTING.md) | Test architecture, strategy, and decisions |

Expand Down
23 changes: 12 additions & 11 deletions README_IT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@

Un **case study di product analytics** che analizza la retention e
l'abbandono degli studenti nella formazione online, utilizzando
l'[Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset),
~32.000 studenti, 7 corsi, clickstream comportamentale completo.
l'[Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset):
32.593 iscrizioni di 28.785 studenti distinti, 7 corsi, clickstream
comportamentale completo.

Il progetto segue una **pipeline analitica SQL-driven**: DuckDB come
database analitico locale, statistica descrittiva e inferenziale, e una
Expand Down Expand Up @@ -61,7 +62,7 @@ Ogni pattern analitico di questo progetto è portabile ad altri domini:
| Livello | Tecnologia | Motivazione |
|---------|------------|-------------|
| DB analitico | **DuckDB** (local-first) | Costo zero, SQL-first, percorso di migrazione a BigQuery |
| Dialetto SQL | Solo **ANSI SQL** | Nessuna sintassi DuckDB-specifica — portabile su cloud |
| Dialetto SQL | Solo **ANSI SQL** | Nessuna sintassi DuckDB-specifica, portabile su cloud |
| Linguaggio | **Python 3.13+** | Orchestrazione pipeline, statistica, visualizzazione |
| Statistica | **SciPy + statsmodels** | t-test, chi-quadrato, intervalli di confidenza, effect size |
| Visualizzazione | **Matplotlib + Seaborn** | Grafici di qualità pubblicabile |
Expand All @@ -75,7 +76,7 @@ Ogni pattern analitico di questo progetto è portabile ad altri domini:

```
project_root/
├── run_pipeline.py # Entrypoint — orchestra l'ETL
├── run_pipeline.py # Entrypoint: orchestra l'ETL
├── src/
│ ├── config.py # Path, costanti, variabili d'ambiente
│ ├── db/connection.py # Astrazione DB (DuckDB ora, BQ in futuro)
Expand Down Expand Up @@ -159,8 +160,8 @@ pytest tests/test_smoke.py -v
## Dataset

L'[Open University Learning Analytics Dataset (OULAD)](https://analyse.kmi.open.ac.uk/open_dataset)
contiene dati su ~32.000 studenti distribuiti su 7 presentazioni di corsi
presso la Open University (UK).
contiene 32.593 iscrizioni ai corsi di 28.785 studenti distinti, distribuite
su 7 moduli (22 presentazioni) presso la Open University (UK).

| Tabella | Descrizione | Colonne chiave |
|---------|-------------|----------------|
Expand All @@ -172,8 +173,8 @@ presso la Open University (UK).
| vle | Metadati risorse VLE | activity_type |
| courses | Metadati dei corsi | module_presentation_length |

**Variabile target**: `final_result` ∈ {Pass, Distinction, Fail, Withdrawn}
— binarizzata come Completato (Pass + Distinction) vs Non completato (Fail + Withdrawn).
**Variabile target**: `final_result` ∈ {Pass, Distinction, Fail, Withdrawn},
binarizzata come Completato (Pass + Distinction) vs Non completato (Fail + Withdrawn).

> **Citazione**: Kuzilek, J., Hlosta, M., & Zdrahal, Z. (2017).
> Open University Learning Analytics dataset.
Expand All @@ -190,8 +191,8 @@ In sintesi:
- **BQ1**: circa 1 iscrizione su 3 termina con il ritiro esplicito; il dropout
si concentra intorno a scadenze di valutazione e rilascio voti
- **BQ2**: tutti gli 8 segnali comportamentali precoci (primi 28 giorni) sono
significativamente associati all'abbandono; giorni attivi e click totali
dominano il ranking per effect size
significativamente associati all'abbandono; il volume di engagement (decile
di engagement, giorni attivi, click totali) domina il ranking per effect size
- **BQ3**: il comportamento è un predittore molto più forte della demografia;
in ogni livello di istruzione, l'engagement alto batte l'engagement basso
- **BQ4**: i tassi di completamento variano dal 37% al 71% tra i 7 moduli;
Expand All @@ -210,7 +211,7 @@ In sintesi:
| [Report Esecutivo](reports/REPORT_IT.md) | Analisi completa BQ1–BQ5 con figure e numeri |
| [Metodologia](docs/METHODOLOGY_IT.md) | Approccio statistico, scelte progettuali, trade-off |
| [Trasferibilità](docs/TRANSFERABILITY_IT.md) | Portabilità dei pattern a SaaS, abbonamenti, fitness |
| [Migrazione Cloud](docs/MIGRATION_IT.md) | Percorso DuckDB → BigQuery, gap e checklist |
| [Migrazione Cloud](docs/MIGRATION_IT.md) | Percorso da DuckDB a BigQuery, gap e checklist |
| [ADR](docs/ADR_IT.md) | 7 decisioni architetturali con razionale |
| [Testing](docs/TESTING_IT.md) | Architettura di test, strategia e decisioni |

Expand Down
Loading
Loading