update readme

Author: Patrickstarh

README.md

@@ -1,71 +1,97 @@
-# BRI vs Non-BRI Development Visualization
+# BRI vs Non-BRI Development Dashboard
 
-Website link: https://com-480-data-visualization.github.io/DVX/
+Live demo: https://com-480-data-visualization.github.io/DVX/
 
 ## Overview
 
-This project explores whether countries participating in the Belt and Road Initiative (BRI) show different development trajectories compared to non-BRI countries. Instead of focusing on a single metric, we consider multiple dimensions such as economic growth, infrastructure, technology adoption, trade, and governance.
+This project is an interactive data story about the Belt and Road Initiative (BRI), launched in 2013. It asks whether BRI countries follow development trajectories that differ from non-BRI countries across multiple socio-economic dimensions, rather than relying on a single headline indicator.
 
-## Data
+The dashboard is designed for students, researchers, and general readers who want a spatial and longitudinal view of global development. It combines a global map, time-series comparison, a country-level snapshot view, and a post-2013 change summary into one scrolling narrative.
 
-The main dataset is the World Development Indicators (WDI) from the World Bank, which provides long-term socio-economic data for over 200 countries.
+## Intended Use
 
-We also use external sources to identify BRI countries and regional groupings. Official BRI data was considered, but due to download limitations, it is only used as a supplementary source to fill missing values.
+The site is meant to be explored interactively.
 
-## Method
+You can use it to:
 
-- Countries are grouped into BRI (treatment) and non-BRI (control); they are also grouped by sub-continental groups
-- 2013 is treated as the intervention year and the total range is from 2000 to 2025
-- Small gaps are filled using limited interpolation
+- compare BRI and non-BRI countries across time
+- inspect a country's classification and development profile from the world map
+- examine long-run trends for selected indicators and regions
+- study cross-country variation in a single year with the scatterplot snapshot
+- summarize how regional averages changed after the 2013 BRI announcement
 
-## Variables
+The interface is intentionally descriptive rather than predictive. It supports exploratory analysis, classroom discussion, and process-book style presentation of the final findings.
 
-We rename raw WDI indicators into shorter and more consistent variable names:
+## Technical Setup
 
-- Country Name → `country`  
-- Country Code → `country_code`  
-- Year → `year`  
+The project is a static front-end application built with:
 
-### Infrastructure & Transport
-- Access to electricity (% of population) → `electricity_access`  
-- Air transport, freight → `air_freight`  
-- Air transport, passengers → `air_passengers`  
-- Container port traffic → `container_traffic`  
-- Railways freight → `rail_freight`  
-- Railways passengers → `rail_passengers`  
+- HTML5 for the page structure
+- CSS Grid and responsive CSS for the layout
+- D3.js for all data loading, scales, axes, map rendering, and chart interactions
+- vanilla JavaScript for navigation, filtering, and dashboard logic
 
-### Economy & Trade
-- GDP growth (annual %) → `gdp_growth`  
-- GDP per capita (current US$) → `gdp_pc`  
-- GNI per capita (Atlas method) → `gni_pc_atlas`  
-- Current account balance (% of GDP) → `cab_gdp_pct`  
-- Current account balance (US$) → `cab_usd`  
+The main entry point is [index.html](index.html). The interactive logic is split between [js/script.js](js/script.js), which handles page behavior, and [js/vis.js](js/vis.js), which renders the visualizations.
 
-- Exports growth → `exports_growth`  
-- Exports (US$) → `exports_usd`  
-- Export value index → `export_value_idx`  
-- Export volume index → `export_volume_idx`  
+There is no build step and no package manager configuration in this repository. The site can be deployed directly as static files, which is why it works well with GitHub Pages.
 
-- Imports (% of GDP) → `imports_gdp_pct`  
-- Import value index → `import_value_idx`  
-- Import volume index → `import_volume_idx`  
+## How To Run Locally
 
-### Society & Inequality
-- Gini index → `gini`  
-- Unemployment (ILO) → `unemp_ilo`  
-- Unemployment (national) → `unemp_national`  
-- Internet users (% of population) → `internet_users_pct`  
+Because the dashboard loads CSV and GeoJSON files with D3, it should be served over HTTP rather than opened directly from the file system.
 
-### Governance
-- Control of corruption (estimate) → `corr_control_est`  
-- Control of corruption (rank) → `corr_control_rank`  
-- Government effectiveness (estimate) → `gov_eff_est`  
-- Political stability (estimate) → `pol_stab_est`  
+One simple option is to start a local web server from the project root:
 
-### Trade Policy
-- Tariff rate (applied) → `tariff_applied_pct`  
-- Tariff rate (MFN) → `tariff_mfn_pct`  
+```bash
+python -m http.server 8000
+```
 
-### Metadata
-- Region → `region`  
-- DID group (BRI vs non-BRI) → `did_group`  
+Then open:
+
+```text
+http://localhost:8000/
+```
+
+Any equivalent static server will also work.
+
+## Project Structure
+
+- [index.html](index.html): main landing page and scrolling narrative
+- [css/](css): shared styling, plot styling, and responsive rules
+- [js/script.js](js/script.js): navigation behavior, sticky header, and dashboard controls
+- [js/vis.js](js/vis.js): map, radar chart, line chart, snapshot scatterplot, and change chart logic
+- [data/](data): cleaned and imputed datasets, metadata, and the world map GeoJSON
+- [img/](img): logo and hero imagery
+- [milestone1/](milestone1): exploratory analysis notebook and archived data used during development
+- [milestone2/](milestone2): earlier static version of the website
+
+## Data Pipeline
+
+The main analytical dataset is [data/Final_Imputed_Panel_Data.csv](data/Final_Imputed_Panel_Data.csv). It contains country-year observations from 2000 onward and is used throughout the dashboard for the radar chart, time trends, snapshot scatterplot, and change chart.
+
+Supporting files include:
+
+- [data/bri_country_status.csv](data/bri_country_status.csv) for BRI, non-BRI, and China classification used by the world map
+- [data/world.geojson](data/world.geojson) for country boundaries
+- [data/Mapping_Dictionary.csv](data/Mapping_Dictionary.csv) for indicator name alignment
+- [data/WDI_Dataset.csv](data/WDI_Dataset.csv) and related WDI exports for the original World Bank source data
+
+The data were cleaned and harmonized to make cross-country comparison possible. In the final dashboard, the visual story relies on a common set of normalized or comparable indicators, while preserving the original country-year structure.
+
+## Main Visual Modules
+
+The final page follows a top-to-bottom narrative with four core modules:
+
+1. Geographic Overview: a choropleth world map that classifies countries by BRI participation, with a linked radar profile for the selected country.
+2. Time Trends Across Countries: a line chart comparing aggregated BRI, non-BRI, and China series, with reference markers for 2013 and 2019.
+3. Development Snapshot: a scatterplot showing country-level heterogeneity for a chosen year, with GDP per capita and internet usage as the main axes.
+4. Change Since the BRI Launch: a horizontal bar chart summarizing regional change between 2013 and a selected end year.
+
+## Notes For Maintainers
+
+- Keep the live site structure aligned with [index.html](index.html) and the scripts in [js/](js) if you add or remove sections.
+- If you update the datasets, keep the column names compatible with the parsing code in [js/vis.js](js/vis.js).
+- The map and charts depend on the files in [data/](data), so renaming or moving them requires updating the paths in the JavaScript code.
+
+## License And Attribution
+
+The dashboard is part of the COM-480 data visualization project. The visualization and data processing were created for academic presentation and evaluation purposes. Please retain attribution to the project when reusing the material.