NumPy vs Git & GitHub — Comparison for Beginners

# numpy_basics.py — the operations beginners actually need
# Run this after `pip install numpy`.

import numpy as np

# 1. Create arrays
a = np.array([1, 2, 3, 4, 5])
b = np.arange(0, 10, 2)          # [0 2 4 6 8]
grid = np.zeros((3, 4))          # 3x4 of zeros
random = np.random.default_rng(42).normal(0, 1, size=1000)

# 2. Vectorised arithmetic — no Python loops
sales = np.array([1200, 950, 1800, 2100, 1600])
tax = sales * 0.18
total = sales + tax

print("Sales: ", sales)
print("Total: ", total)

# 3. Broadcasting — a scalar applies to every element
discounted = sales * 0.90
print("10% off: ", discounted)

# 4. Aggregations
print(f"Mean: {sales.mean():.2f}")
print(f"Std:  {sales.std():.2f}")
print(f"Max:  {sales.max()}")

# 5. Boolean masks — filtering without loops
above_1500 = sales[sales > 1500]
print("Above 1500:", above_1500)

# 6. Reshaping
matrix = np.arange(12).reshape(3, 4)
print("Matrix shape:", matrix.shape)

# 7. Linear algebra — matrix multiplication
weights = np.array([0.2, 0.3, 0.5])
row_scores = matrix @ weights   # same as np.matmul
print("Row scores:", row_scores)

# Why this matters:
# - These seven operations are ~80% of day-to-day NumPy
# - Every one of them replaces a slower Python loop
# - Pandas, scikit-learn, and PyTorch build on exactly this interface
# - You do not need to memorise the entire NumPy API

# A complete Git workflow beginners should know
# Run these in your terminal inside a project folder.

# 1. One-time setup (per machine)
git config --global user.name "Your Name"
git config --global user.email "you@example.com"

# 2. Start a project
mkdir sales-analysis && cd sales-analysis
git init

# 3. Create a file, then check status
echo "import numpy as np" > analysis.py
git status

# 4. Stage and commit
git add analysis.py
git commit -m "Add initial NumPy analysis script"

# 5. Work on a branch for a new feature
git checkout -b add-mean-calculation

# ... edit analysis.py ...
git add analysis.py
git commit -m "Add mean sales calculation"

# 6. Switch back to main and merge
git checkout main
git merge add-mean-calculation

# 7. Connect to GitHub and push
git remote add origin https://github.com/yourname/sales-analysis.git
git push -u origin main

# 8. Everyday commands you will use constantly
git status          # what changed?
git diff            # exactly what changed?
git log --oneline   # history of commits
git pull            # get latest from remote

# Why this matters:
# - These 8 steps cover 95% of real Git usage
# - `git status` and `git diff` prevent 90% of mistakes
# - Branches let you experiment without breaking working code
# - Pushing to GitHub backs up your work AND builds your portfolio

# project structure — how NumPy and Git work together in a real repo
#
# sales-analysis/
# ├── .gitignore
# ├── README.md
# ├── requirements.txt
# └── analysis.py

# .gitignore — keep junk and secrets out of Git
# NEVER commit data files, virtual environments, or API keys.
.venv/
__pycache__/
*.pyc
data/raw/
.env

# requirements.txt — so anyone can reproduce your environment
numpy==2.1.0
pandas==2.2.0

# README.md — the first thing a recruiter reads
# """
# # Sales Analysis
#
# Computes monthly revenue trends using NumPy.
#
# ## Setup
#     pip install -r requirements.txt
#
# ## Run
#     python analysis.py
#
# ## What it does
# - Loads raw sales data from data/raw/sales.csv
# - Computes monthly totals, averages, and growth rates
# - Outputs results to the terminal
# """

# analysis.py — the actual NumPy work, now version-controlled
import numpy as np

def monthly_growth(revenue: np.ndarray) -> np.ndarray:
    """Return month-over-month percentage growth."""
    return np.diff(revenue) / revenue[:-1] * 100

if __name__ == "__main__":
    revenue = np.array([120_000, 132_000, 128_000, 145_000, 161_000])
    growth = monthly_growth(revenue)
    print("Monthly growth %:", np.round(growth, 2))

# Why this combination matters:
# - The NumPy code computes something real
# - The Git repo makes the work reproducible and shareable
# - The README turns code into a portfolio piece
# - This is exactly what a recruiter opens when they click your GitHub link
#
# A student with NumPy but no Git has nothing to show.
# A student with Git but no real code has an empty repo.
# You need both.