Skip to content

Commit c7be956

Browse files
cheavvncheavvn
authored
Create README.md
1 parent 953998d commit c7be956

1 file changed

Lines changed: 207 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# 🌍 Ukraine Conflict Data Dashboard
2+
3+
Project for the **COM-480 Data Visualization** course at EPFL.
4+
5+
## 👨‍👩‍👧‍👦 Students
6+
7+
**Daniele Giuli**
8+
**Chaewon Yoon**
9+
**Ali Shenaskhosh**
10+
11+
## ✅ Live Prototype
12+
13+
The final live prototype can be found here:
14+
15+
👉 **[Go to website](INSERT_WEBSITE_LINK_HERE)**
16+
17+
## 📘 Final Deliverables
18+
19+
* 📄 **Process Book:** [Read the process book](INSERT_PROCESS_BOOK_LINK_HERE)
20+
* 🎥 **Screencast:** [Watch the screencast](INSERT_SCREENCAST_LINK_HERE)
21+
* 🌐 **Website:** [Go to website](INSERT_WEBSITE_LINK_HERE)
22+
23+
## 🔴 Abstract
24+
25+
The Ukraine-Russia conflict is a complex crisis involving military activity, humanitarian consequences, and international economic support. This project presents an interactive data visualization dashboard that helps users explore these dimensions through maps, timelines, rankings, and statistical charts.
26+
27+
The dashboard combines conflict event data, regional summaries, international aid commitments, and economic indicators. Users can explore the conflict from multiple perspectives: global aid contributions, regional conflict intensity, battlefront activity over time, and detailed country or oblast profiles.
28+
29+
## 🎯 Target Audience
30+
31+
This project is intended for users interested in understanding the Ukraine-Russia conflict through visual and interactive data exploration, including students, researchers, journalists, analysts, and general users.
32+
33+
No technical background is required to use the website.
34+
35+
## 🌟 Website Overview
36+
37+
The website consists of four main pages:
38+
39+
```text
40+
index.html # Interactive map, timeline, and battlefront view
41+
statistics.html # Overall conflict and aid statistics
42+
country.html # Country-level aid profile
43+
oblast.html # Oblast-level conflict profile
44+
```
45+
46+
### Main Map
47+
48+
The main page provides an interactive Leaflet map with three views:
49+
50+
* **States View:** global map of aid pledged to Ukraine by donor country.
51+
* **Oblasts View:** regional map of conflict intensity across Ukrainian and Russian oblasts.
52+
* **Battlefront View:** time-based visualization of conflict events with point, density, comparison, and playback controls.
53+
54+
The page also includes a timeline of key events, hover tooltips, map legends, reset controls, and an export function.
55+
56+
### Overall Statistics
57+
58+
The statistics page summarizes the conflict and international support through:
59+
60+
* casualty and event summary cards;
61+
* event distribution charts;
62+
* aid allocation charts;
63+
* cumulative aid trends;
64+
* aid-to-GDP ranking;
65+
* death and event time-series visualizations.
66+
67+
### Country and Oblast Profiles
68+
69+
The detail pages provide focused views for selected countries and regions:
70+
71+
* **Country profiles** show total aid, aid type distribution, aid-to-GDP ratio, ranking position, and monthly aid trends.
72+
* **Oblast profiles** show total events, fatalities, event types, monthly trends, pictograms, and regional rankings.
73+
74+
## 💿 Dataset
75+
76+
The project uses processed data files stored directly in the repository under the `data/` folder.
77+
78+
The main datasets are derived from:
79+
80+
* **ACLED** — conflict event records and geospatial conflict information;
81+
* **Kiel Institute Ukraine Support Tracker** — international aid commitment data;
82+
* **World Bank** — GDP and country-level economic indicators.
83+
84+
The website expects the following files to be available through the `data/` path:
85+
86+
```text
87+
data/
88+
├── world_countries.geojson
89+
├── ukraine_oblasts.geojson
90+
├── russia_oblasts.geojson
91+
├── acled_by_oblast.json
92+
├── aid_by_country.json
93+
├── events_by_month.json
94+
├── gdp_by_country.json
95+
└── timeline_events.json
96+
```
97+
98+
## 🛠️ Technologies Used
99+
100+
* **HTML5 / CSS3 / JavaScript**
101+
* **D3.js v7**
102+
* **Leaflet.js v1.9.4**
103+
* **Leaflet.heat**
104+
* **Turf.js**
105+
* **html2canvas**
106+
* **R / Python** for exploratory data analysis and preprocessing
107+
108+
## 🚀 Project Structure
109+
110+
```text
111+
project-root/
112+
├── .github/workflows/ # GitHub workflow files
113+
├── data/ # Data files used by the website
114+
├── docs/ # Website files for deployment
115+
├── figures/ # Figures used in reports or milestones
116+
├── EDA.R # Exploratory data analysis script
117+
├── Milestone1.md # Milestone 1 report
118+
├── Milestone2.md # Milestone 2 report
119+
├── guidebook.md # Additional documentation
120+
├── plan.docx # Project planning document
121+
├── preprocess.py # Data preprocessing script
122+
└── README.md # Project documentation
123+
```
124+
125+
## 🧑‍💻 Running the Website Locally
126+
127+
Because the website loads local `.json` and `.geojson` files, it should be run through a local web server rather than opened directly with `file://`.
128+
129+
### Option 1: VS Code Live Server
130+
131+
1. Clone the repository.
132+
2. Open the project folder in VS Code.
133+
3. Install the **Live Server** extension.
134+
4. Open the website entry file, usually `index.html`.
135+
5. Right-click and select **Open with Live Server**.
136+
137+
### Option 2: Python Local Server
138+
139+
From the repository root, run:
140+
141+
```bash
142+
python -m http.server 5500
143+
```
144+
145+
Then open:
146+
147+
```text
148+
http://127.0.0.1:5500/
149+
```
150+
151+
If the website is located inside the `docs/` folder, open:
152+
153+
```text
154+
http://127.0.0.1:5500/docs/
155+
```
156+
157+
### Option 3: Node.js Local Server
158+
159+
If Node.js is installed, run:
160+
161+
```bash
162+
npx http-server -p 5500
163+
```
164+
165+
Then open the corresponding local URL in your browser.
166+
167+
## 🔄 Data Preprocessing
168+
169+
The repository includes preprocessing and exploratory analysis scripts used to transform raw datasets into website-ready files.
170+
171+
* `EDA.R` contains exploratory data analysis work.
172+
* `preprocess.py` contains preprocessing logic for generating structured data files.
173+
* Processed outputs are stored in the `data/` folder and loaded directly by the website.
174+
175+
If the data is updated, the processed files in the `data/` folder should be regenerated or replaced while preserving the filenames expected by the website.
176+
177+
## 📍 Milestones
178+
179+
### Milestone 1: Proposal
180+
181+
👉 **[View Milestone 1](./Milestone1.md)**
182+
183+
### Milestone 2: Prototype
184+
185+
👉 **[View Milestone 2](./Milestone2.md)**
186+
187+
### Milestone 3: Final Project
188+
189+
* 🌐 **Website:** [Go to website](INSERT_WEBSITE_LINK_HERE)
190+
* 📄 **Process Book:** [Read the process book](INSERT_PROCESS_BOOK_LINK_HERE)
191+
* 🎥 **Screencast:** [Watch the screencast](INSERT_SCREENCAST_LINK_HERE)
192+
193+
## 🤝 Authors
194+
195+
* **Chaewon Yoon**
196+
* **Daniele**
197+
* **Ali**
198+
199+
## 📌 Notes
200+
201+
Before running or deploying the project, make sure that:
202+
203+
1. the `data/` folder is included in the repository;
204+
2. all required `.json` and `.geojson` files are available;
205+
3. the website is served through a local or hosted web server;
206+
4. relative paths between the website files and the `data/` folder are consistent;
207+
5. placeholder links in this README are replaced with the final website, process book, and screencast links.

0 commit comments

Comments
 (0)