Final commit

Author: BasirS

README.md

@@ -22,15 +22,15 @@ ClearLane is a student led analysis and product concept that studies NYC bus lan
 
 ## The central idea and narrative
 
-Buses act like educational infrastructure for CUNY students, the commute is a rolling study hall that should be protected, violations are not random, they cluster at a small set of locations and they peak during school commute hours, a targeted approach called ClearLane focuses enforcement on those locations during those hours, which is expected to raise speeds and give students back study time, the numbers you see below are tied to the specific sources where they appear in code and results so a reader can follow the trail
+Buses act like educational infrastructure for CUNY students, the commute is a rolling study hall that should be protected, violations are not random, they cluster at a small set of locations and they peak during school commute hours, a targeted approach called ClearLane focuses enforcement on those locations during those hours, which is expected to raise speeds and give students back study time, the numbers you see below are tied to the specific sources where they appear in code and results so a reader can follow the trail.
 
 - Scale of violations, 3,778,568 violation records across 2019 to Aug 2025 used in feature engineering, source results/txt/02_feature_engineering.txt, some pages mention 2.4M plus which refers to an earlier slice used for writing, the modeling work uses 3.78M
 - Enforcement performance headline, results/txt/03_continued_predictive_story.txt opens with a 97.5 percent failure claim drawn from earlier work, the validation section inside the same text calculates an 85.6 percent failure rate over 557 routes using speed change percent, both appear because they refer to different inputs, the computed figure for that specific route set is 85.6 percent
 - Hotspot focus, site content speaks about roughly 90 priority locations as a working number for deployment, dashboard material sometimes shows the top 100 hotspots for exploration
 
 ## How to read this repository
 
-Start with the dashboards to build intuition about the problem, read the results texts to learn how features and scores are built, use the site pages to communicate the story to leaders and the public, and when it is time to build models or run experiments load the modeling parquet and work from there, the sections below walk through every folder and file and explain how they fit into that path
+Start with the dashboards to build intuition about the problem, read the results texts to learn how features and scores are built, use the site pages to communicate the story to leaders and the public, and when it is time to build models or run experiments load the modeling parquet and work from there, the sections below walk through every folder and file and explain how they fit into that path.
 
 ## Root level files
 
@@ -45,7 +45,7 @@ Start with the dashboards to build intuition about the problem, read the results
 
 ### `dashboard/` the interactive analysis space in Streamlit
 
-This folder holds a self contained Streamlit experience that mirrors the narrative, a reader can click through a human story, a problem statement grounded in data, an interactive 3D map when generated, and a target list, this is where someone starts when they want to touch the data quickly without reading code
+This folder holds a self contained Streamlit experience that mirrors the narrative, a reader can click through a human story, a problem statement grounded in data, an interactive 3D map when generated, and a target list, this is where someone starts when they want to touch the data quickly without reading code.
 
 - `dashboard/app.py`, a single page Streamlit app with a left sidebar that lets a person navigate between sections, the page called The Rolling Study Hall introduces the student centric frame, the page called The Problem is Local and Predictable shows a hotspot map and time charts, the page called Interactive 3D Bus Route Map embeds a Kepler based map after it is generated by a script, the page called The ClearLane Solution displays the target list table if the CSV is present, a sidebar button triggers the 3D map generator script in the notebooks folder using a subprocess
 - `dashboard/run_dashboard.py`, a small launcher that sets up and runs the dashboard with dependency checks, run `python dashboard/run_dashboard.py` from the repository root to start quickly
@@ -93,7 +93,7 @@ Subdirectories inside `dashboard/` are as follows
 
 ### `deployment/` and `launch/` and `monitoring/`
 
-These folders contain short guides for taking the work public, setting a domain, shipping the site, and thinking about performance monitoring, they are plain language writeups meant to help during the last mile when the site goes live
+These folders contain short guides for taking the work public, setting a domain, shipping the site, and thinking about performance monitoring, they are plain language writeups meant to help during the last mile when the site goes live.
 
 - `deployment/domain-setup.md`, notes for wiring the domain name to the web host, includes DNS configuration and SSL certificate setup instructions
 - `launch/deployment-guide.md`, a checklist style guide for pushing the site and dashboards, covers both technical deployment and content preparation
@@ -102,15 +102,15 @@ These folders contain short guides for taking the work public, setting a domain,
 
 ### `marketing/`
 
-This folder contains public facing documents that help communicate the work to non technical audiences
+This folder contains public facing documents that help communicate the work to non technical audiences.
 
 - `marketing/policy-stakeholder-outreach.md`, suggested outreach steps and materials when talking to policy folks, includes key talking points and data highlights
 - `marketing/press-kit.md`, a press kit outline that lists sources, visuals, and key talking points, designed for media outreach and public communication
 - `marketing/social-media-kit.md`, post templates and a short guide for sharing results in plain words, includes hashtag suggestions and visual assets
 
 ### `notebooks/`
 
-The notebooks show the entire pipeline in a clear order, the results directory holds their exported text and PDFs, a reader can open these to see the analysis code and derivations
+The notebooks show the entire pipeline in a clear order, the results directory holds their exported text and PDFs, a reader can open these to see the analysis code and derivations.
 
 - `notebooks/01_understanding_the_pipeline.ipynb`, a step by step walkthrough that shows how raw violation data becomes route hour metrics, it builds an enforcement intensity score and a paradox score, it shows CUNY proximity checks with a 500 meter buffer using Haversine distance, the text export is in `results/txt/01_understanding_the_pipeline.txt`
 - `notebooks/02_feature_engineering.ipynb`, a full feature build on 3,778,568 violations from Oct 2019 to Aug 2025, it builds temporal blocks including rush periods and class change windows, spatial clusters with DBSCAN and local density, CUNY proximity and campus interaction flags, adaptation features like repeat offender patterns and entropy based predictability, multiple targets including next hour, next day, severity flags, speed impact, and composite risk, it exports `data/processed/modeling_dataset.parquet` plus a 10k row CSV, metadata, and a feature list, the text export is `results/txt/02_feature_engineering.txt`
@@ -122,7 +122,7 @@ The notebooks show the entire pipeline in a clear order, the results directory h
 
 ### `plots/` the visualization outputs
 
-A folder of static outputs created by notebooks, including PNGs and HTML maps, these are referenced in results and used during review and communication, they are read only and illustrate the findings without recomputation
+A folder of static outputs created by notebooks, including PNGs and HTML maps, these are referenced in results and used during review and communication, they are read only and illustrate the findings without recomputation.
 
 - `plots/actual_vs_predicted_ridership.png`, a scatter plot showing actual vs predicted ridership values from the Random Forest model in notebook 07, with a perfect prediction line, demonstrates model performance with R² of 0.963
 - `plots/cbd_congestion_pricing_analysis.png`, analysis of how congestion pricing affects violation patterns in the Central Business District
@@ -141,7 +141,7 @@ A folder of static outputs created by notebooks, including PNGs and HTML maps, t
 
 ### `public/`
 
-Public assets for the Astro site, including `site.webmanifest` which provides metadata to browsers for install and appearance
+Public assets for the Astro site, including `site.webmanifest` which provides metadata to browsers for install and appearance.
 
 - `public/site.webmanifest`, a web app manifest file that provides metadata about the web application, including name, description, icons, and display properties for when the site is installed on a device
 
@@ -160,7 +160,7 @@ Public assets for the Astro site, including `site.webmanifest` which provides me
 
 ### `src/` the Astro site
 
-This is the narrative layer, it takes the analysis and turns it into a clean story that a visitor can understand quickly, it includes a home page with a personal hook, a methods page written for a general audience, a solution page with a phased plan, and a policy brief layout for print, components under `src/components/` provide charts, cards, hero sections, and layout scaffolding
+This is the narrative layer, it takes the analysis and turns it into a clean story that a visitor can understand quickly, it includes a home page with a personal hook, a methods page written for a general audience, a solution page with a phased plan, and a policy brief layout for print, components under `src/components/` provide charts, cards, hero sections, and layout scaffolding.
 
 - `src/pages/index.astro`, the home page, it opens with the student story and statistics, it previews temporal and geographic patterns through chart components, it invites a reader to run a personal route analyzer, and it links to methodology and solution pages
 - `src/pages/methodology.astro`, the research methodology written clearly, it lists data sources, shows each analysis step in simple language with small technical callouts, and contains a section on the paradox score, it also links to code locations so a reader can verify the work
@@ -222,7 +222,7 @@ Supporting folders under `src/` include
 
 ## Notes on figures and scope
 
-Because code paths and reports cover different time ranges and subsets, numbers appear with different scopes in different places, this README quotes the number and the file where the number came from so a reader can match it to the exact context, the modeling dataset count of 3.78M records is from results/txt/02_feature_engineering.txt, the 85.6 percent failure rate over 557 routes is from results/txt/03_continued_predictive_story.txt, hotspots are discussed as roughly 90 priority locations in site content while some dashboards list the top 100 for exploration
+Because code paths and reports cover different time ranges and subsets, numbers appear with different scopes in different places, this README quotes the number and the file where the number came from so a reader can match it to the exact context, the modeling dataset count of 3.78M records is from results/txt/02_feature_engineering.txt, the 85.6 percent failure rate over 557 routes is from results/txt/03_continued_predictive_story.txt, hotspots are discussed as roughly 90 priority locations in site content while some dashboards list the top 100 for exploration.
 
 ## How to run things quickly
 
@@ -231,4 +231,6 @@ Because code paths and reports cover different time ranges and subsets, numbers
 - Launch the multi page dashboards, change directory into `dashboard/dashboards/` and run `streamlit run app.py`
 - Build or preview the Astro site with your usual Astro workflow, `astro.config.mjs` governs the build
 
-This project is part of the 2025 MTA Datathon at Macaulay Honors College and the MTA, for questions or collaboration, please contact Jujutsu Query
+This project is part of the 2025 MTA Datathon at Macaulay Honors College and the MTA. 
+
+Thank you for reading all the way till here :)