How mobeen-dev/ml-algorithms-testing works
1. This repository is a small machine-learning project organized around a “from scratch” implementation boundary: all model logic lives under src/, while top-level scripts handle dataset generation, experiments, visualization, and report building.
2. The core algorithms are split into three independent model modules:
- src/kmeans.py for k-Means clustering
- src/gnb.py for Gaussian Naive Bayes
- src/c45_tree.py for a Decision Tree using C4.5-style gain ratio with binary splits
This makes the src/ directory the main algorithm layer of the repo.
3. src/utils.py is the shared support layer. It likely contains reusable helpers for preprocessing, metrics, split logic, or array/dataframe utilities used by multiple models, keeping the model modules thinner and avoiding duplicated logic.
4. src/viz.py is the presentation/analysis layer for plots. The README says plots are saved to report_assets/, so the visualization module is the bridge from experiment outputs to report-ready figures.
5. dataset_generator.py is the data-production entrypoint. The README states datasets are generated programmatically with seed 050, so the project is not depending on an external dataset file; instead, the data pipeline begins with reproducible synthetic generation.
6. experiments.py is the orchestration layer. It appears to run the full benchmark suite (python experiments.py --all), invoking dataset generation, training/evaluating the three models, and producing outputs for the report and plot assets.
7. build_report_pdf.py is the report compilation step. The presence of report.md, report_template.md, and report.pdf suggests a markdown-to-PDF workflow, with the build script converting the authored report into the final PDF artifact.
8. report.md is the human-readable experiment writeup, while report_template.md is the source template used to generate or format that report. report_assets/ holds generated figures referenced by the report.
9. requirements.txt shows the runtime dependency boundary: the implementation is constrained to NumPy, Pandas, and Matplotlib, with no sklearn model APIs. That constraint is central to the architecture because it forces all learning logic into the repository’s own src/ modules.
10. The repo also contains packaged deliverables under submission_bundle/ and submission_bundle_065/, plus corresponding zip archives. These are duplicate frozen snapshots of the code/report used for submission or grading, separate from the main working copy.
11. From an architecture diagram perspective, the main data flow is: synthetic dataset generation → model training/evaluation in experiments.py using the src/ implementations → plots in report_assets/ via src/viz.py → narrative/report assembly in report.md/report.pdf.
12. The main boundary to preserve in a diagram is between “orchestration/reporting scripts” and “pure model implementations.” The top-level scripts coordinate the workflow, but the actual ML behavior is encapsulated in the three algorithm modules under src/.
Main entry points: experiments.py Experiments · __init__.py src package · requirements.txt Deps · report.md Report
Components 18
Workflow
Top-level scripts that generate data, run experiments, and build the final report.
- Dataset gen · Reproducible synthetic dataset creation entrypoint.
dataset_generator.py - Experiments · Runs the benchmark suite and coordinates model evaluation.
experiments.py - Build PDF · Converts the authored report into the final PDF artifact.
build_report_pdf.py
Models
Core from-scratch algorithm implementations under src/.
- Utils · Reusable support code shared across model modules.
src/utils.py - k-Means · From-scratch k-Means implementation.
src/kmeans.py - Naive Bayes · Gaussian Naive Bayes implementation.
src/gnb.py - C4.5 tree · Decision tree with gain ratio and binary splits.
src/c45_tree.py - Visuals · Produces report-ready figures from experiment outputs.
src/viz.py - src package · Package boundary for the model implementation layer.
src/__init__.py
Deliverables
Report files and generated assets consumed by the writeup pipeline.
- Report · Human-readable experiment narrative and results.
report.md - Template · Markdown template used to format or generate the report.
report_template.md - PDF · Compiled final report deliverable.
report.pdf - Assets · Generated plots and images referenced by the report.
report_assets - Deps · Dependency boundary for the project runtime.
requirements.txt
Snapshots
Frozen submission bundles and archive artifacts.
- Bundle · Frozen submission copy of the project.
submission_bundle - Bundle 065 · Second frozen submission copy of the project.
submission_bundle_065 - Zip 050 · Packaged submission archive for seed 050.
submission_bundle_seed050.zip - Zip 065 · Packaged submission archive for seed 065.
submission_bundle_seed065.zip
Connections 25
- Experiments → Dataset gen: generate data · Experiments begin by producing the synthetic dataset.
- Experiments → k-Means: run · Benchmark orchestration invokes k-Means.
- Experiments → Naive Bayes: run · Benchmark orchestration invokes Gaussian Naive Bayes.
- Experiments → C4.5 tree: run · Benchmark orchestration invokes the decision tree.
- Experiments → Utils: share helpers · Models reuse common utilities during evaluation.
- Experiments → Visuals: plot results · Experiment outputs are turned into figures.
- Visuals → Assets: save figures · Plots are written into the report assets directory.
- Experiments → Report: feed results · Experiment outputs populate the narrative report.
- Template → Report: format · Template provides the report structure.
- Report → Build PDF: compile · The authored markdown is compiled into PDF.
- Build PDF → PDF: emit · Build step produces the final PDF artifact.
- Report → Assets: reference · The report includes generated figures from the assets folder.
- src package → k-Means: package · Package boundary includes the clustering module.
- src package → Naive Bayes: package · Package boundary includes the Naive Bayes module.
- src package → C4.5 tree: package · Package boundary includes the decision tree module.
- src package → Utils: package · Package boundary includes shared utilities.
- src package → Visuals: package · Package boundary includes plotting support.
- Deps → Experiments: constrain · Runtime dependencies constrain the orchestration layer.
- Deps → k-Means: constrain · Runtime dependencies constrain the algorithm implementation.
- Deps → Naive Bayes: constrain · Runtime dependencies constrain the algorithm implementation.
- Deps → C4.5 tree: constrain · Runtime dependencies constrain the algorithm implementation.
- Bundle → Zip 050: package · Submission bundle is mirrored by the archived zip.
- Bundle 065 → Zip 065: package · Second bundle is mirrored by its archived zip.
- Bundle → PDF: contains · Frozen bundle carries the report deliverable.
- Bundle 065 → PDF: contains · Frozen bundle carries the report deliverable.