3. Setup a Data Science project

Duration2h30 AI Banned

This guide will walk you through setting up a structured data science project for sales analysis, using Git for version control. We’ll focus on implementing the concepts introduced in our basic Git workflow guide.

Prerequisites

Important: Before starting this tutorial, make sure you’ve completed the Environment Setup and Git & GitLab How-to guides, which cover:

  • GitLab account creation
  • Repository initialization
  • SSH key setup
  • Git configuration
  • Repository cloning

This tutorial assumes you have already created and cloned the “sales-analysis” repository as instructed in the previous guide.

Project Structure Overview

A well-organized data science project makes it easier to navigate, understand, and collaborate. For our sales analysis project, we’ll use a modern structure with uv:

sales-analysis/
├── README.md          # Project documentation
├── pyproject.toml     # Modern Python project configuration
├── uv.lock           # Lock file for exact reproducibility
├── data/             # Raw and processed data
└── notebooks/        # Jupyter notebooks
    └── images/       # Visualizations and diagrams

Creating your Project Structure

Let’s start by creating the project with uv:

1
2
3
4
5
6
7
8
9

# Make sure you're in your project directory
cd ~/git/data-science-projects/

# Create the project structure with uv
uv init sales-analysis
cd sales-analysis

# Create additional directories
mkdir -p data notebooks/images

Creating a comprehensive README file

A well-structured README.md is essential for any data science project. It serves as the entry point for anyone wanting to understand your analysis, reproduce your results, or build upon your work.

Your README should tell the complete story of your project, from initial questions to final insights. Here’s how to structure it effectively:

Project Overview: Start with a clear, concise description of what your project does and why it matters.

Dataset Description: Provide key details about your data:

  • Number of records and features
  • Data source and collection period
  • Key variables and their meanings
  • Data quality notes (missing values, cleaning steps)

Research Questions: List the specific questions your analysis addresses. These should be:

  • Clear and specific
  • Answerable with your dataset
  • Relevant to business or research objectives

Key Findings: Summarize your most important discoveries with:

  • Quantified results where possible
  • Visual evidence (charts and graphs)
  • Business implications

Technical Implementation: Document your methodology:

  • Tools and libraries used
  • Analysis workflow steps
  • How to reproduce your results

Create your initial README.md with these basic sections. You’ll enhance it throughout the project as you develop your analysis:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# Sales Analysis Project

## Overview
[Your project description - what you're analyzing and why]

## Dataset Description
[Key details about your sales data]

## Research Questions
[List your specific analytical questions]

## Key Findings
[To be completed after analysis]

## Technical Implementation
[Your tools and methodology]

## Repository Structure
[Explanation of your file organization]

Documentation references:

Committing Your Project Structure

Now that we’ve set up our project structure, let’s record these changes with our first meaningful commit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Check what files have been added or modified
git status

# Stage all the changes we've made (the `.` means every file in the repository)
git add .

# Commit the changes with a descriptive message
git commit -m "Initialize project structure with directories and README"

# Push the changes to the remote repository
git push origin main

Remember that a good commit message should:

  • Be concise but descriptive
  • Use the imperative mood (“Add” not “Added”)
  • Explain the what and why, not the how

Data Management Best Practices

Before adding data to your project, it’s important to follow best practices for data handling in version control systems.

Creating a .gitignore File

Data files should typically not be tracked in Git repositories because they:

  • Can be very large and slow down repository operations
  • May contain sensitive information
  • Can be regenerated from source or downloaded separately

Create a .gitignore file in your project root to exclude the data directory:

1
2

# Create .gitignore file
touch .gitignore

Add the following content to your .gitignore file:

# Python cache
__pycache__/
*.pyc
*.pyo

# uv virtual environment
.venv/

# Jupyter Notebook checkpoints
.ipynb_checkpoints/

# Output files
outputs/

# IDE files
.vscode/
.idea/

# OS files
.DS_Store
Thumbs.db

Adding Your Dataset

For this project, you’ll work with a sales analysis dataset. Instead of committing the data file to Git:

  1. Download the dataset and place it in the data/ directory
  2. Document the data source in your README.md
  3. Include data acquisition instructions for reproducibility

Committing Your Project Setup

1
2
3
4
5
6
7
8

# Stage the .gitignore file
git add .gitignore

# Commit the project configuration
git commit -m "Add .gitignore for data management best practices"

# Push to the remote repository
git push origin main

Creating Your Analysis Notebook

Now let’s create a comprehensive Jupyter notebook for sales data analysis. This notebook will implement a complete data science workflow from data loading to insights generation.

Setting up Dependencies

Download the files below and use uv to sync your local enviromnent as you learned in Environment Setup tutorial:

Creating and Running Your Notebook

1
2
3
4
5

# Launch Jupyter notebook (uv automatically manages the environment)
uv run jupyter notebook

# Or create a new notebook file directly
touch notebooks/sales.ipynb
  1. Launch VS Code and open your project folder
  2. Open the notebook notebooks/sales.ipynb in VS Code
  3. Select the Python interpreter from the uv environment when prompted

Creating Key Visualizations

Data visualization is crucial for communicating your findings effectively. After completing your analysis, you’ll want to create professional visualizations and integrate them into your project documentation.

From your analysis notebook, identify the most impactful visualizations that tell your data story. Focus on charts that:

  • Answer your research questions directly
  • Show clear patterns or trends
  • Support business recommendations
  • Are easy to interpret

Recommended visualizations for sales analysis:

  1. Monthly Sales Performance - Shows seasonal trends and peak periods
  2. Hourly Purchase Distribution - Reveals customer behavior patterns for advertising strategy
  3. Price-Quantity Correlation - Demonstrates purchasing behavior relationships
  4. Category Performance Comparison - Highlights product category insights

Exporting Images from Your Notebook

Use plt.savefig() to save your visualizations as high-quality images:

1
2
3
4

# Save with high quality settings
plt.savefig('images/monthly_sales.png', 
            dpi=300, bbox_inches='tight', facecolor='white')
plt.show()

Image Export Best Practices:

  • Use high DPI (300) for crisp, professional images
  • Set bbox_inches=‘tight’ to remove excess whitespace
  • Specify facecolor=‘white’ for consistent backgrounds
  • Use descriptive filenames that match your analysis sections
  • Maintain consistent sizing across related visualizations

Updating Your README with Results

After generating your key visualizations, enhance your README.md with with Main Findings section as this example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

## Main Findings

### 📈 Seasonal Sales Patterns
- **Peak month**: [Your finding] with $[amount] in sales
- **Growth trend**: [Your observation about trends]
- **Business impact**: [What this means for the business]

![Monthly Sales Performance](notebooks/images/monthly_sales.png)

### ⏰ Customer Behavior Insights
- **Peak shopping hours**: [Your findings]
- **Advertising recommendation**: [Your strategic advice]
- **Customer patterns**: [Your behavioral observations]

![Hourly Distribution](notebooks/images/hourly_distribution.png)

### 💰 Product Performance
- **Top category**: [Your finding]
- **Price insights**: [Your pricing observations]
- **Recommendations**: [Your business advice]

This approach transforms your technical analysis into compelling business insights supported by clear visual evidence.

Committing Your Complete Analysis

Once you’ve completed your analysis notebook and generated your key visualizations, it’s time to commit your work and update your project documentation as you learn previously.

Best Practices

Git Workflow and Version Control

Commit Frequency: Make incremental commits as you develop your analysis:

  • After completing data cleaning
  • After major feature engineering steps
  • After generating each key visualization
  • After updating documentation

Commit Messages: Use descriptive messages that explain:

  • What analysis steps were completed
  • Which insights were discovered
  • What visualizations were created
  • How documentation was updated

File Organization: Ensure your final commit includes:

  • Clean, well-documented notebook
  • High-quality exported visualizations
  • Updated README with findings
  • Proper .gitignore configuration

This systematic approach creates a professional, reproducible data science project that demonstrates both technical skills and business insight generation.

Project Completion Checklist

Before considering your project complete, verify you have:

  • Structured project directory with proper organization
  • Clean, documented notebook with clear analysis workflow
  • Professional visualizations exported as high-quality images
  • Comprehensive README with findings and business insights
  • Proper Git history with meaningful commit messages
  • Data management best practices (.gitignore configuration)
  • Reproducible analysis that others can understand and run

Your sales analysis project now serves as a portfolio piece demonstrating end-to-end data science capabilities from raw data to business insights.