King County Housing EDA Project Template

This is the starter template for the Exploratory Data Analysis (EDA) project. You will work with the King County housing dataset (home sales in and around Seattle, USA), uncover what drives house prices, and turn your findings into insights and recommendations for a client you choose.

Learning Objectives

By the end of this repository, you should be able to:

• Connect to a PostgreSQL database from Python and load query results into a pandas DataFrame.
• Frame an exploratory data analysis around clear research questions and hypotheses.
• Clean and wrangle a real-world dataset by handling missing values, outliers, and feature transformations.
• Explore distributions and the relationships between features and the target variable (price).
• Translate your analysis into at least three insights and three client-specific recommendations.
• Present your work to a non-technical audience.

Learning Path

Work through the files in order. Start with the assignment to understand the goal, follow the workflow as your guide, fetch the data, then run your analysis in the EDA notebook.

Tip

The data lives in the eda schema of the database and is split across two tables. Before fetching anything in code, connect with DBeaver and explore that schema: inspect both tables, check Column Names for what each field means, and work out how to join them. Once you have a working JOIN, use it as the query in 03 - Fetching the Data to load the combined dataset into pandas.

File / Folder	Description
01 - Assignment	The project brief: the dataset, your tasks, deliverables, and the list of clients to choose from.
02 - Workflow	A recommended EDA workflow, from understanding and questioning the data through cleaning, relationships, and presenting.
03 - Fetching the Data	Connect to the PostgreSQL database with psycopg2 and SQLAlchemy, then pull the data into a pandas DataFrame.
04 - EDA	Starter notebook for your exploratory data analysis.
Column Names	Data dictionary describing each column in the King County housing dataset.

Additional Folders and Files

File / Folder	Description
Data	Where you save the dataset CSV. The folder is tracked, but its data files are kept out of git.
.env.example	Template for the database credentials. Copy it to .env and fill in your values.
pyproject.toml	Project configuration and dependencies.
uv.lock	Dependency lock file.

Setup

Note

Throughout these steps, text in angle brackets like <repo-name> is a placeholder. Replace it, including the < > brackets, with your own value. For example, cd <repo-name> becomes cd ds-eda-project-template.

1. Create the Repository from the Template

Click Use this template on GitHub.

When creating the repository:

• Set yourself as the Owner
• Choose a repository name
• Disable Include all branches
• Click Create repository

Important

If you are working in pairs or groups, only one person should complete this step.

---

2. Add Collaborators (Pairs/Groups Only)

If working with teammates:

1. Open the repository on GitHub
2. Go to Settings → Collaborators
3. Add your teammates as collaborators
4. Share the repository link with your team

Teammates should accept the invitation before continuing.

---

3. Clone the Repository

Copy the SSH URL from the Code button on GitHub, then run:

git clone <copied-ssh-url>

The copied SSH URL will look like git@github.com:<your-username>/<repo-name>.git.

---

4. Move into the Project Folder and Install Dependencies

This installs all dependencies and creates a virtual environment in .venv/.

cd <repo-name>
uv sync

Tip

Need a library that is not installed yet (for example a mapping)? Add it with uv add <package-name>. This updates pyproject.toml and uv.lock and installs it into your .venv. Commit both files; teammates then run uv sync after pulling to get the same environment.

---

5. Set up your Database Credentials

The data-fetching notebook reads the database connection details from a .env file. Copy the template and fill in your own values:

cp .env.example .env

Open .env and replace the placeholders with the credentials for the King County housing database (the same ones you use in DBeaver). These values feed 03 - Fetching the Data.

Caution

.env holds secrets and must never be committed. It is already listed in .gitignore. Only .env.example, with placeholder values, belongs in the repository.

---

6. Open the Notebooks

Note

Make sure you open VS Code from the project root so it automatically detects the environment created by uv sync.

Launch VS Code in the project root folder:

code .

Then open a notebook and select the Python environment created by uv sync as the kernel.

References & Further Reading

• House Sales in King County dataset: The source dataset, with column descriptions and community notebooks.
• Pandas user guide: The official guide to data manipulation with pandas.
• Seaborn tutorial: Statistical data visualization in Python.
• SQLAlchemy documentation: The database toolkit used to query PostgreSQL from Python.
• Hypothesis generation for EDA: How to form research questions and hypotheses before diving into the data.
• EDA Checklist: A phase-by-phase checklist for working through an exploratory analysis.
• Detailed EDA with Python: A worked example of a thorough EDA notebook on real data.
• Tips for data science presentations: Storytelling techniques for presenting results to a non-technical audience.