https://github.com/plcoster/fcc_datavis_project4
FreeCodeCamp Data Visualisation Project 4: Choropleth Map
https://github.com/plcoster/fcc_datavis_project4
create-react-app d3-visualization react
Last synced: about 2 months ago
JSON representation
FreeCodeCamp Data Visualisation Project 4: Choropleth Map
- Host: GitHub
- URL: https://github.com/plcoster/fcc_datavis_project4
- Owner: PLCoster
- License: mit
- Created: 2022-08-08T19:06:34.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-08-19T18:27:41.000Z (almost 4 years ago)
- Last Synced: 2026-04-29T06:38:48.768Z (about 2 months ago)
- Topics: create-react-app, d3-visualization, react
- Language: JavaScript
- Homepage: https://plcoster.github.io/fcc_datavis_project4/
- Size: 4 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Free Code Camp: Data Visualisation Project 4 - Choropleth Map
## Interactive U.S. Educational Attainment Choropleth
The aim of this project was to build a small web app and data visualisation with functionality similar to: https://codepen.io/freeCodeCamp/full/EZKqza
The project was built using the following technologies:
- **HTML**
- **JavaScript** with **[Node.js](https://nodejs.org/en/) / [NPM](https://www.npmjs.com/)** for package management
- **[React](https://reactjs.org/)** for application view with React Hooks to handle the application state
- **[D3](https://d3js.org/)** to generate the SVG Choropleth from the data
- **[Bootstrap](https://getbootstrap.com/)** for styling with some custom **CSS**
- **[FontAwesome](https://fontawesome.com/)** for icons
- **[Create-React-App](https://create-react-app.dev/)** for initial app template with bundling
- **[TopoJSON](https://github.com/topojson/topojson)** to convert the supplied U.S. State/County TopoJSON data into GeoJSON format, for rendering with `d3.geoPath`
U.S. Educational Data sourced from [USDA Economic Research Service](https://www.ers.usda.gov/)
Up-to-date data can be found [here](https://www.ers.usda.gov/data-products/county-level-data-sets/download-data.aspx)
### Project Requirements
- **User Story #1:** My choropleth should have a title with a corresponding `id="title"`.
- **User Story #2:** My choropleth should have a description element with a corresponding `id="description"`.
- **User Story #3:** My choropleth should have counties with a corresponding `class="county"` that represent the data.
- **User Story #4:** There should be at least 4 different fill colors used for the counties.
- **User Story #5:** My counties should each have `data-fips` and `data-education` properties containing their corresponding `fips` and `education` values.
- **User Story #6:** My choropleth should have a county for each provided data point.
- **User Story #7:** The counties should have `data-fips` and `data-education` values that match the sample data.
- **User Story #8:** My choropleth should have a legend with a corresponding `id="legend"`.
- **User Story #9:** There should be at least 4 different fill colors used for the legend.
- **User Story #10:** I can mouse over an area and see a tooltip with a corresponding `id="tooltip"` which displays more information about the area.
- **User Story #11:** My tooltip should have a `data-education` property that corresponds to the `data-education` of the active area.
### Project Writeup:
For the fourth Free Code Camp: Data Visualisation Project, I decided to incorporate the Choropleth Map inside a small React app, bundled using Create-React-App. The application state is controlled using React Hooks (`useState`, `useEffect`).
After the relevant data for the chart has been fetched (using `Promise.all` to wait for all fetch requests to resolve before proceeding), the Choropleth is built using D3.
Going beyond the required User Stories outlined above, the plot generated by the app is responsive to changes in the browser window size. A `window.onresize` event listener is added using a `useEffect` hook inside the `ChoroplethContainer` component. When the window size changes, the graph container width is passed as props to the `Choropleth` component, which causes the D3 SVG to be re-rendered according to the available size.
In addition, the displayed tool-tip when the cursor is placed on a data bar in the graph adjusts its positioning to ensure it is always contained inside the graph area, and not hidden off screen.
### Project Files:
- `/public` - this folder contains all public content for the app, including favicon images, the web manifest, and the basic index.html template onto which the React component tree is rendered.
- `/src/index.js` - this is the entry point to the React application, it renders the react component tree on the DOM, as well as importing Bootstrap styles for the application.
- `/src/components/helpers/choroplethBuilder.js` - contains a set of functions that build the Choropleth and append it to a desired DOM element. Rendering the U.S. State and County map is done using `` elements and D3's `geoPath()` functionality. Counties are color coded according to educational attainment using D3's `scaleQuantize()` API.
An `on:hover` tooltip is also added to the graph - it is a small div element which has its position, visibility and contents adjusted dynamically based on the current mouse position, using the `mouseover` event on Choropleth county paths.
- `/docs` - contains a copy of the built app files for deployment via github-pages
### Components:
- `App.js` - is the top level component of the application, a simple container component that renders the `NavBar` and `ChoroplethContainer` components.
- `NavBar.js` is a presentational navbar component, providing links to other projects / sites.
- `ChoroplethContainer.js` - after mounting, this component uses two `useEffect` hooks. One of these hooks fetches both the U.S. topological data (needed to render the image of the U.S. and its states and counties) and the U.S. Educational Attainment Data (used to color-scale the Choropleth). The other hook sets up the `window.onresize` event listener, listening for window resize events and then passing the current width of the `` element to the `Choropleth` component so it knows the size of plot to create.
- `Choropleth.js` - this component uses a `useEffect` hook to render the Choropleth SVG after the component mounts, and also whenever the `containerWidth` prop passed to it by `ChoroplethContainer` changes. The Choropleth is built and mounted to the `#choropleth-container` element by the functions in `helpers/choroplethBuilder.js`. After building the graph, the opacity of the `main` element is set to 1 using the `setContainerOpacity` dispatch function, making the graph visible.
### Usage
Requires Node.js / NPM in order to install required packages. After downloading the repo, install required dependencies with:
`npm install`
The CRA development server can then be started with:
`npm start`
The development can then be viewed at `http://localhost:3000/` in the browser.
A production build can be created in the `dist/` folder by running:
`npm run build`
The build can be easily served by installing `serve`:
`npm install -g serve`
`serve -s build`