Most beginner pain is not about Python at all. It is about which Python is running, and where. So we fix that first, once, properly.

1. Install VS Code

Download it from code.visualstudio.com and run the installer. VS Code is a text editor that grows into an IDE when you add extensions. It will be where you write scripts, run notebooks, browse files, and use a terminal, all in one window.

2. Install Miniconda from the command line

conda is a program that creates environments: separate folders, each with its own Python and its own set of libraries. Project A can use pandas 2 while project B uses pandas 3, and neither can break the other. Miniconda is the small installer: just conda and Python. We install it entirely from the terminal. Open a terminal first: Terminal on macOS or Linux, PowerShell on Windows (Start menu, type PowerShell).

Pick your system. On a Mac, check which chip you have with uname -m: arm64 means Apple silicon, x86_64 means Intel.

uname -m

# macOS, Apple silicon (arm64):
URL=https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
# macOS, Intel (x86_64): use this line instead
# URL=https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
# Linux (x86_64): use this line instead
# URL=https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

mkdir -p ~/miniconda3
curl -L $URL -o ~/miniconda3/miniconda.sh
bash ~/miniconda3/miniconda.sh -b -u -p ~/miniconda3
rm ~/miniconda3/miniconda.sh

~/miniconda3/bin/conda init bash zsh

Invoke-WebRequest -Uri "https://repo.anaconda.com/miniconda/Miniconda3-latest-Windows-x86_64.exe" -OutFile ".\miniconda.exe"
Start-Process -FilePath ".\miniconda.exe" -ArgumentList "/InstallationType=JustMe","/RegisterPython=0","/S","/D=$env:USERPROFILE\miniconda3" -Wait
Remove-Item ".\miniconda.exe"

& "$env:USERPROFILE\miniconda3\Scripts\conda.exe" init powershell

The last line connects conda to your shell. Close the terminal completely and open a new one. The prompt should now start with (base). Then check:

conda --version
which python    # Windows: Get-Command python

Optional but pleasant: stop conda from activating base in every new terminal.

conda config --set auto_activate_base false

3. Create the environment

One command makes a fresh environment called pandas-quest with everything this guide needs:

conda create -n pandas-quest -c conda-forge python=3.12 pandas numpy matplotlib seaborn scipy ipykernel -y

Then step inside it. You will do this every time you open a new terminal:

conda activate pandas-quest

Your prompt now starts with (pandas-quest). That prefix is your seatbelt light: if it is missing, you are not in the environment.

4. Make a project folder and open it

mkdir pandas-quest
cd pandas-quest
code .

mkdir pandas-quest
cd pandas-quest
code .

VS Code opens with that folder. Always open the folder, not single files. It is what lets VS Code find your data, scripts and environment.

5. Add extensions

An extension is an add-on that teaches VS Code new skills. You install them from inside VS Code, and you will use the same few clicks every time you want a new one.

1. Click the Extensions icon in the vertical bar on the far left of the window. It looks like four squares with one flying off. No icon bar? Use the menu: View, then Extensions. Keyboard shortcut: Ctrl+Shift+X (Windows, Linux) or Cmd+Shift+X (Mac).
2. Click the search box at the top of the panel. It says Search Extensions in Marketplace. The Marketplace is VS Code's app store, and everything in it is free to install.
3. Type the name from the table below, for example Python. Results appear underneath, most popular first.
4. Pick the right result: check the publisher name under the title, and the download count (the good ones have millions or hundreds of thousands). Click the result to read its description on the right.
5. Click the blue Install button. Wait a few seconds until it changes to a gear icon. That means it worked. If a Reload or Restart Extensions button appears, click it.
6. Repeat for each extension in the table.

To confirm everything is installed, type @installed in the search box. You should see all five in the list. The same box shows other useful filters: @recommended for suggestions, and the clock icon for recently updated extensions.

6. Tell VS Code which Python to use

Press Ctrl/Cmd+Shift+P, type Python: Select Interpreter, and choose the one named pandas-quest. Its path contains envs/pandas-quest. A notebook has its own picker, which you will use in the next stage.

7. Run the check script

In VS Code create a new file named check_setup.py (File, New File), paste this in, save, and run it from the terminal with python check_setup.py.

import sys
import platform

print("python    ", platform.python_version())
for name in ["pandas", "numpy", "matplotlib", "seaborn", "scipy"]:
    module = __import__(name)
    print(f"{name:<10}", module.__version__)
print("env       ", sys.prefix.replace("\\", "/").split("/")[-1])

You should see something shaped like this (your version numbers will differ):

python     3.12.8
pandas     3.0.1
numpy      2.3.5
matplotlib 3.10.7
seaborn    0.13.2
scipy      1.16.3
env        pandas-quest

A Jupyter notebook (.ipynb) mixes code, results and notes in one document. It is made of cells. Code cells run Python and show what they produce underneath. Markdown cells hold text, headings and reminders to future you.

Create notebooks/01_python_basics.ipynb in your project (make the notebooks folder if it does not exist), select the pandas-quest kernel, and follow along cell by cell.

The kernel is a running program with a memory

Behind the notebook is a kernel: a Python process that executes your cells and remembers every variable you have created. The notebook shows the code; the kernel holds the state. They can disagree. Try it:

x = 10

print(x * 2)

Run both: you get 20. Now edit cell 1 to x = 100 but do not run it, then re-run cell 2. Still 20. The page says 100; the kernel still thinks 10.

Printing, and what shows up on its own

The last expression in a cell is displayed automatically. print() is for everything else: checking an assumption, logging progress inside a loop, leaving yourself a trail of what happened. F-strings make labels painless:

n_reads = 1250
print(f"reads counted: {n_reads}")
print(f"as thousands: {n_reads / 1000:.2f}k")

Data types, in five lines

count = 24             # int
score = 3.49           # float
name = "p.Trp18Ter"    # str
is_low = score < 2     # bool
variants = ["a", "b"]  # list
print(type(count), type(score), type(name), type(is_low), type(variants))

type(x) is the first thing to check when something behaves strangely. It is the notebook equivalent of looking at the label on the jar.

Strings, and slicing them

A slice text[start:stop] takes characters from start up to, but not including, stop. Counting starts at 0, and negative numbers count from the end.

v = "p.Trp18Ter"
#    index: 0123456789...
print(v[2:5])    # Trp
print(v[5:-3])   # 18
print(v[-3:])    # Ter
print(int(v[5:-3]) + 1)   # 19
print(v.startswith("p."), v.endswith("Ter"), v.upper(), v.replace("p.", ""))

Math, conditions, loops

print(7 + 2, 7 - 2, 7 * 2, 7 / 2, 7 // 2, 7 % 2, 7 ** 2)   # 9 5 14 3.5 3 1 49
print(round(3.4902, 2))

score = 1.4
if score < 0.5:
    label = "low"
elif score < 1.0:
    label = "in between"
else:
    label = "wild-type-like"
print(label)

names = ["WT", "p.Trp18Ter", "p.Leu25Pro"]
for i, name in enumerate(names):
    print(i, name, len(name))

# the same idea in one line, called a list comprehension
lengths = [len(name) for name in names]

Python reads close to English: for each name in names, print it. Indentation (four spaces) is how Python knows what is inside the loop or the if, so it is part of the grammar, not decoration.

Here is the list you will use for the puzzles. Every entry follows the pattern p. + three-letter reference + position + three-letter alternate. (Ter means the sequence stops there; the same three letters twice means nothing changed.)

variants = ["p.Gly12Gly", "p.Trp18Ter", "p.Leu25Pro", "p.Val30Asp",
            "p.Gln36Ter", "p.Ile40Asn", "p.Ser45Thr", "p.Gly46Arg"]

An error message is the computer telling you, as precisely as it can, where it got stuck and why. It is more helpful than most feedback you will ever get. Here is a real one from a notebook:

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Cell In[4], line 2
      1 df = pd.read_csv("data/raw/toy.csv")
----> 2 print(df["Score"].mean())

File ~/miniconda3/envs/pandas-quest/lib/python3.12/site-packages/pandas/core/frame.py:4102, in DataFrame.__getitem__(self, key)
   ... (about thirty lines of pandas internals) ...

KeyError: 'Score'

1. Start at the bottom. KeyError: 'Score' says: you asked for something by name and it is not there. The type tells you the category; the message tells you the specifics.
2. Find your line. The arrow ----> 2 points at your code. Ignore the middle section about library internals; those are the pandas authors' lines, and the bug is almost never theirs.
3. Ask what you would expect. Which column names really exist? print(df.columns). You will see score, lowercase. Keys are case-sensitive.

The usual suspects

A routine that works

1. Read the last line of the traceback out loud, slowly.
2. Go to the line the arrow points at. Is it what you expected to run?
3. Check what you assumed: print(type(x)), df.shape, df.columns, df.head().
4. Shrink the problem. Reproduce it on three rows, or in a fresh cell with two lines.
5. Suspect the kernel. Restart and Run All. A surprising number of bugs vanish.
6. Search the message with your own names removed: KeyError pandas column beats KeyError 'Score'. Read the answer for why it happens, not just a line to copy.
7. Still stuck? Write a question someone can answer: what you wanted, what you ran, the full error, what you already tried. That is also the best prompt for an AI assistant, which is a fine tool as long as you understand the fix before pasting it in.

Warm-up: four quick questions about reading errors. Then a broken script to fix on your own machine.

A library is code someone else wrote that you borrow with import. The one that matters most here is pandas, which gives Python a table type called a DataFrame: rows are observations, columns are named measurements, and every column has a type.

Our first table is a tiny made-up experiment. No biology needed: each row is one named item measured once, and four columns (bin1_count to bin4_count) say how many reads fell into each of four buckets, from the lowest signal (bin 1) to the highest (bin 4).

Make a new notebook, notebooks/02_pandas_one.ipynb, and read the CSV straight from its web address (the file is hosted on this site):

import pandas as pd

URL = "https://atharva-bhagwat.github.io/assets/data/toy_vampseq_bin_counts.csv"
df = pd.read_csv(URL)
df

Look before you touch

Before any analysis, find out what you actually have. Run each of these in its own cell:

df.head()                      # first 5 rows (df.tail() for the last 5)
df.shape                       # (rows, columns)
df.columns                     # the column names
df.dtypes                      # type of each column
df.info()                      # types + missing values in one view
df.describe()                  # count, mean, min, max... of numeric columns
df["variant_type"].value_counts()   # how many rows per category
df["variant"].nunique()        # how many different variants

Pick columns

df["variant"]                       # one column -> a Series
df[["variant", "replicate"]]         # several columns -> a DataFrame (note the double brackets)

Pick rows by condition

A comparison on a column produces a column of True/False. Using that to index the DataFrame keeps only the True rows. This is called a boolean mask, and it is the pandas move you will use most.

is_nonsense = df["variant_type"] == "nonsense"
df[is_nonsense]

# combine conditions with & (and), | (or), ~ (not) and wrap each one in parentheses
df[(df["variant_type"] == "missense") & (df["replicate"] == 1)]

# membership and text tests
df[df["variant_type"].isin(["nonsense", "synonymous"])]
df[df["variant"].str.endswith("Arg")]

# the same filter, written as a readable string
df.query("variant_type == 'missense' and replicate == 1")

Select by position or label

df.loc[0:2, ["variant", "bin1_count"]]   # by label: rows 0 to 2 (inclusive!), named columns
df.iloc[0:2, 0:2]                         # by position: rows 0 and 1 (stop excluded), first two columns

Raw counts are hard to compare: one row has 20 reads, another has 700. A common fix is a weighted average of the bins. Give bin 1 weight 1, bin 2 weight 2, and so on. A row with all its reads in bin 1 scores 1, all in bin 4 scores 4, and anything between lands in between.

score = (1*bin1 + 2*bin2 + 3*bin3 + 4*bin4) / total_reads

Make new columns without loops

pandas works on whole columns at once. That is called vectorised code. It is shorter, easier to read, and much faster than looping over rows.

bins = ["bin1_count", "bin2_count", "bin3_count", "bin4_count"]

df["total_reads"] = df[bins].sum(axis=1)                   # axis=1: add across the columns of each row
df["score"] = (df[bins] * [1, 2, 3, 4]).sum(axis=1) / df["total_reads"]
df[["variant", "replicate", "total_reads", "score"]].round(3)

Sort and rename

df.sort_values("score")                       # smallest first
df.sort_values("score", ascending=False)
df.rename(columns={"score": "bin_score"})

Summarise by group

groupby splits the table by a column, applies a summary to each piece, and glues the answers back together: split, apply, combine.

df.groupby("variant_type")["score"].mean()

# several summaries at once, with names you choose
per_variant = df.groupby("variant").agg(
    mean_score=("score", "mean"),
    reads=("total_reads", "sum"),
    n_rows=("score", "size"),
).reset_index()
per_variant.sort_values("mean_score")

Pivot: one row per variant, one column per replicate

wide = df.pivot(index="variant", columns="replicate", values="score")
wide                       # columns are named 1 and 2
wide[1].corr(wide[2])      # how well do the replicates agree?

wide["diff"] = (wide[1] - wide[2]).abs()
wide.sort_values("diff", ascending=False)

In Stage 4 you computed scores for the whole table. Now imagine a collaborator wants a different weighting, or you want to ignore rows with too few reads, or you need the same calculation for next month's dataset. Copy and paste works exactly once. The second time you paste, the two copies start to differ, and you forget which one you trust.

Anatomy of a function

BINS = ["bin1_count", "bin2_count", "bin3_count", "bin4_count"]


def add_scores(df, weights=(1, 2, 3, 4), min_reads=0):
    """Add total_reads and a weighted-average bin score.

    score = sum(weight_i * count_i) / total_reads, so 1 means every read
    is in bin 1 (lowest signal) and 4 means every read is in bin 4.

    Rows with fewer than `min_reads` total reads get score = NaN, because
    a number built from 20 reads is not one we should trust.

    Returns a new DataFrame; the input is left unchanged.
    """
    out = df.copy()
    out["total_reads"] = out[BINS].sum(axis=1)
    out["score"] = (out[BINS] * list(weights)).sum(axis=1) / out["total_reads"]
    out.loc[out["total_reads"] < min_reads, "score"] = float("nan")
    return out

• def name(parameters): starts the recipe. Parameters with = have defaults, so callers only mention what they want to change.
• The triple-quoted text right under def is the docstring. It is what help(add_scores) and Shift+Tab show.
• return hands the result back. A function with no return gives back None, a classic cause of "why is my variable empty?".
• df.copy() means the function works on its own copy and never changes the caller's table behind their back.

Use it

scored = add_scores(df)                    # defaults
strict = add_scores(df, min_reads=50)      # same recipe, one dial changed
flat = add_scores(df, weights=(1, 1, 1, 1))

scored[["variant", "replicate", "total_reads", "score"]].head()

Check it, so you can stop worrying about it

An assert silently passes when true and shouts when false. A few of them under a function are tiny, permanent tests:

assert len(scored) == len(df)                          # no rows lost
assert scored["score"].between(1, 4).all()              # scores live in 1-4
assert strict["score"].isna().sum() == 2                # exactly the 2 low-read rows were blanked

before = df.columns.tolist()
add_scores(df)
assert df.columns.tolist() == before                     # the input was not modified

Documentation is a kindness to future you

• Name things for what they are. add_scores beats func2. Verbs for actions, nouns for data.
• Docstrings say what and why; comments explain the why of a non-obvious line, not what the code already says.
• Markdown cells are your lab notebook. Before each section write one sentence: what question this answers and what you decided.
• Keep functions small and single-purpose. If the docstring needs the word "and" three times, split it.
• Show an example in the docstring or the next cell. Examples are the documentation people actually read.

The next stage moves this function out of the notebook into its own file so every notebook can import it.

Analyses that survive are organised. Not fancy, just predictable. When someone (including you in six months) opens the folder, they should know where the raw data is, what is code, and what is output.

pandas-quest/
├── README.md              what this is and how to run it
├── environment.yml        the exact recipe for the conda environment
├── data/
│   ├── raw/               downloads exactly as received. Never edited.
│   └── derived/           tables your code produces
├── notebooks/             exploration, in numbered order
├── src/                   functions you reuse (plain .py files)
└── results/
    └── figures/           plots saved by code, not screenshots

1. Build the skeleton

From your project folder, in the terminal where (pandas-quest) is active (this one-liner works on every operating system):

python -c "from pathlib import Path; [Path(p).mkdir(parents=True, exist_ok=True) for p in ['data/raw', 'data/derived', 'notebooks', 'src', 'results/figures']]"

2. Get the data

Three files power the rest of the guide. You can click to download them by hand, but the script below is better because it is a record of where each file came from.

Save this as download_data.py in the project root and run python download_data.py.

"""Download the data files into data/raw/. Safe to re-run."""
from pathlib import Path
from urllib.request import urlretrieve

BASE = "https://atharva-bhagwat.github.io/assets/data/"
FILES = {
    "toy_vampseq_bin_counts.csv": BASE + "toy_vampseq_bin_counts.csv",
    "pten-variant-abundance.csv": BASE + "pten-variant-abundance.csv",
    "pten-region-annotations.csv": BASE + "pten-region-annotations.csv",
}

out_dir = Path("data/raw")
out_dir.mkdir(parents=True, exist_ok=True)

for name, url in FILES.items():
    target = out_dir / name
    if target.exists():
        print(f"skip   {name} (already there)")
        continue
    urlretrieve(url, target)
    print(f"saved  {name}  ({target.stat().st_size:,} bytes)")

3. Check the file is the file

A truncated or edited download looks fine until it quietly ruins your results. A SHA-256 hash is a fingerprint of a file's exact bytes; change one character and it changes completely. The guide knows the fingerprint of the original file. Compute yours:

import hashlib
from pathlib import Path

path = Path("data/raw/pten-variant-abundance.csv")
print(hashlib.sha256(path.read_bytes()).hexdigest())

4. Move your function into src/

Create src/vampseq_tools.py and paste in the function from Stage 5, with the BINS list it needs:

"""Reusable helpers for the variant-abundance analysis."""

BINS = ["bin1_count", "bin2_count", "bin3_count", "bin4_count"]


def add_scores(df, weights=(1, 2, 3, 4), min_reads=0):
    """Add total_reads and a weighted-average bin score.

    score = sum(weight_i * count_i) / total_reads. Rows with fewer than
    `min_reads` total reads get score = NaN. Returns a new DataFrame.
    """
    out = df.copy()
    out["total_reads"] = out[BINS].sum(axis=1)
    out["score"] = (out[BINS] * list(weights)).sum(axis=1) / out["total_reads"]
    out.loc[out["total_reads"] < min_reads, "score"] = float("nan")
    return out

Now any notebook can import it. Put this in the first cell of each notebook:

import sys
from pathlib import Path

# Make the project's src/ folder importable, wherever the notebook runs from
ROOT = Path.cwd().parent if Path.cwd().name == "notebooks" else Path.cwd()
sys.path.insert(0, str(ROOT / "src"))
RAW = ROOT / "data" / "raw"

%load_ext autoreload
%autoreload 2

import pandas as pd
from vampseq_tools import add_scores

• Why the sys.path line? Python only imports from certain folders. This adds yours.
• Why %autoreload 2? The kernel remembers imported code (Stage 1!). Without autoreload, editing vampseq_tools.py changes nothing until you restart the kernel. With it, edits are picked up on the next run.

5. Write it down: README and environment

# PTEN variant abundance, a pandas practice project

Explores a published dataset of protein variant abundance scores.

## Run it
    conda env create -f environment.yml
    conda activate pandas-quest
    python download_data.py
    python src/make_figures.py

## Layout
data/raw (never edited), data/derived, notebooks/, src/, results/figures/

## Decisions
- Score = weighted average of the four bins (weights 1-4).
- Variants with fewer than 50 reads are excluded from scores.

Freeze the environment so someone else (or a new laptop) can rebuild it:

conda env export --from-history > environment.yml

--from-history records only the packages you asked for, not every dependency, so the file stays portable between operating systems. To rebuild: conda env create -f environment.yml.

6. Optional but wise: version control

git init
printf "data/raw/\n__pycache__/\n.ipynb_checkpoints/\n.DS_Store\n" > .gitignore
git add .
git commit -m "Project skeleton"

Commit whenever something works. A commit is a save point you can always return to, and the message is a one-line diary entry. (On Windows, create .gitignore in VS Code and paste those four lines instead.)

7. Check your skeleton

Save this as check_project.py in the project root, and run it with python check_project.py:

from pathlib import Path

expected = [
    "data/raw", "data/derived", "notebooks", "src",
    "results/figures", "README.md", "environment.yml",
]

found = 0
for item in expected:
    ok = Path(item).exists()
    found += ok
    print(("[x] " if ok else "[ ] ") + item)

print(f"project check: {found}/{len(expected)}")

Real data arrives with quirks. The habit that separates careful analysts from unlucky ones is a data audit: a short, boring, systematic look at the table before any conclusions. Make notebooks/03_data_audit.ipynb, paste in the first-cell block from Stage 6, then load the real table:

df = pd.read_csv(RAW / "pten-variant-abundance.csv")
df.head()

What the columns hold, in plain terms (score is the one that matters most):

The audit checklist

df.shape                                    # rows, columns
df.dtypes                                   # anything numeric stored as text?
df.isna().sum()                             # missing values per column
df["hgvs_pro"].is_unique                    # one row per variant?
df.duplicated(subset="hgvs_pro").sum()      # how many repeats
df["record_type"].value_counts()            # counts per type
df["abundance_class_label"].value_counts(dropna=False)
pd.crosstab(df["abundance_class"], df["abundance_class_label"])   # do number and label agree?
df[["score", "sd", "se", "expts"]].describe()

Turn text into columns

The variant name packs three facts into one string. To summarise by position later, you need them as separate columns. A regular expression (regex) describes a text pattern; .str.extract pulls out the parts:

pattern = r"^p\.(?P<ref>[A-Za-z]{3})(?P<position>\d+)(?P<alt>[A-Za-z]{3}|=)$"
parts = df["hgvs_pro"].str.extract(pattern)
parts.head()

Build your pattern interactively at regex101.com: paste a few variant names and watch the pieces highlight.

df["ref"] = parts["ref"]
df["position"] = pd.to_numeric(parts["position"]).astype("Int64")   # nullable integer
df["alt"] = parts["alt"]

df[df["position"].isna()]       # which rows did not match, and why?

The Int64 (capital I) type is a nullable integer, so rows without a position can hold a proper missing value instead of forcing every number to a decimal. Rows that did not match the pattern (the wild-type reference row, for instance) simply get blanks. That is your cue to look at them, not to ignore them.

Last, test that the labels agree with the contents. If they do not, you have a problem worth knowing about now:

assert (df.loc[df["record_type"] == "nonsense", "alt"] == "Ter").all()
assert (df.loc[df["record_type"] == "synonymous", "alt"] == "=").all()
assert df.loc[df["record_type"] == "missense", "alt"].notna().all()
print("labels and names agree")

Put the parser in your module

You will need this in every notebook from now on, so add it to src/vampseq_tools.py (it needs import pandas as pd at the top of that file):

def parse_hgvs(df, column="hgvs_pro"):
    """Split names like 'p.Asn12Ile' into ref, position and alt columns.

    ref = 'Asn', position = 12 (nullable integer), alt = 'Ile'.
    Synonymous names like 'p.Asn12=' get alt = '='. Anything that does not
    match (for example the wild-type row '_wt') gets missing values.
    """
    pattern = r"^p\.(?P<ref>[A-Za-z]{3})(?P<position>\d+)(?P<alt>[A-Za-z]{3}|=)$"
    parts = df[column].str.extract(pattern)
    out = df.copy()
    out["ref"] = parts["ref"]
    out["position"] = pd.to_numeric(parts["position"]).astype("Int64")
    out["alt"] = parts["alt"]
    return out

Then in notebooks: from vampseq_tools import parse_hgvs and df = parse_hgvs(df).

Stage 7 gave you one row per variant. Questions usually live at a coarser level: per position, per region, per category. The second table lists named stretches of the sequence with start and end positions:

regions = pd.read_csv(RAW / "pten-region-annotations.csv")
regions

Label each row with its region

Write a small function that answers "which region contains this position?" for one position, then apply it to the whole column with .map:

def find_region(position, regions):
    if pd.isna(position):
        return "no_position"
    for r in regions.itertuples():
        if r.start <= position <= r.end:
            return r.region
    return "other"

df["region"] = df["position"].map(lambda pos: find_region(pos, regions))
df["region"].value_counts()

That logic is reusable, so it joins your module, next to parse_hgvs:

def label_regions(df, regions, position_column="position"):
    """Add a 'region' column from a table with region, start and end columns.

    Positions outside every region are labelled 'other'; rows without a
    position are labelled 'no_position'.
    """
    def find(position):
        if pd.isna(position):
            return "no_position"
        for r in regions.itertuples():
            if r.start <= position <= r.end:
                return r.region
        return "other"

    out = df.copy()
    out["region"] = out[position_column].map(find)
    return out

Focus the question

Different record types answer different questions. For "how do single-letter changes affect abundance?" keep only missense rows and give that table a name:

miss = df[df["record_type"] == "missense"]
len(miss)

Summarise by region, with counts

by_region = (
    miss.groupby("region")["score"]
        .agg(n="size", mean="mean", median="median")
        .round(3)
)
by_region

Summarise by position, then merge back

by_position = (
    miss.groupby("position")["score"]
        .agg(n_subs="size", mean_score="mean")
        .reset_index()
)
by_position.sort_values("mean_score").head(10)       # the most affected positions

merged = df.merge(by_position, on="position", how="left")   # adds n_subs and mean_score to every row
assert len(merged) == len(df), "a merge changed the number of rows!"
merged[["hgvs_pro", "score", "n_subs", "mean_score"]].head()

how="left" keeps every row of the left table and fills blanks where there is no match. The assert after a merge is cheap insurance: if the key is not unique on the right side, a merge silently multiplies rows.

Make notebooks/04_distributions.ipynb, paste the first-cell block from Stage 6, then load, parse and label the table (your module does the work):

from vampseq_tools import parse_hgvs, label_regions

df = pd.read_csv(RAW / "pten-variant-abundance.csv")
regions = pd.read_csv(RAW / "pten-region-annotations.csv")
df = label_regions(parse_hgvs(df), regions)

import matplotlib.pyplot as plt
import seaborn as sns

sns.set_theme(style="whitegrid", context="notebook", palette="colorblind")
TYPES = ["synonymous", "missense", "nonsense"]
data = df[df["record_type"].isin(TYPES)]

Two libraries, one mental model

matplotlib is the foundation: a figure is the canvas and an axes is one chart on it. seaborn sits on top and draws statistical plots from a DataFrame in one line. The pattern you will repeat all stage:

fig, ax = plt.subplots(figsize=(6, 4))        # make a canvas with one chart
sns.<something>(data=..., x=..., y=..., ax=ax)    # draw onto that chart
ax.set(xlabel="...", ylabel="...", title="...")   # label it

Which plot answers which question?

The gallery

Each cell below is a complete plot. Run them, change one thing, run again.

fig, ax = plt.subplots(figsize=(6, 4))
sns.histplot(data=data[data["record_type"] == "missense"], x="score", bins=40, ax=ax)
ax.set(xlabel="abundance score", ylabel="number of variants", title="Histogram: missense variants")

fig, ax = plt.subplots(figsize=(6, 4))
sns.kdeplot(data=data, x="score", hue="record_type", hue_order=TYPES,
            common_norm=False, fill=True, alpha=0.3, ax=ax)
ax.set(xlabel="abundance score", title="KDE: one curve per record type")

fig, ax = plt.subplots(figsize=(6, 4))
sns.ecdfplot(data=data, x="score", hue="record_type", hue_order=TYPES, ax=ax)
ax.set(xlabel="abundance score", ylabel="fraction of variants at or below", title="ECDF")

fig, ax = plt.subplots(figsize=(6, 4))
sns.boxplot(data=data, x="record_type", y="score", order=TYPES, ax=ax)
ax.set(xlabel="", ylabel="abundance score", title="Box plot")

fig, ax = plt.subplots(figsize=(6, 4))
sns.violinplot(data=data, x="record_type", y="score", order=TYPES, inner="quart", cut=0, ax=ax)
ax.set(xlabel="", ylabel="abundance score", title="Violin plot")

fig, ax = plt.subplots(figsize=(6, 4))
sns.stripplot(data=data, x="record_type", y="score", order=TYPES, size=2, alpha=0.4, jitter=0.25, ax=ax)
ax.set(xlabel="", ylabel="abundance score", title="Strip plot: every variant is a dot")

fig, ax = plt.subplots(figsize=(6, 4))
sns.countplot(data=data, x="record_type", order=TYPES, ax=ax)
ax.set(xlabel="", ylabel="number of variants", title="Count plot")

Assemble a multi-panel figure and save it

fig, axes = plt.subplots(1, 3, figsize=(14, 4))

sns.histplot(data=data[data["record_type"] == "missense"], x="score", bins=40, ax=axes[0])
sns.ecdfplot(data=data, x="score", hue="record_type", hue_order=TYPES, ax=axes[1])
sns.boxplot(data=data, x="record_type", y="score", order=TYPES, ax=axes[2])

for ax, letter in zip(axes, "abc"):
    ax.set_title(letter, loc="left", fontweight="bold")
axes[0].set(xlabel="abundance score", ylabel="number of variants")
axes[1].set(xlabel="abundance score", ylabel="cumulative fraction")
axes[2].set(xlabel="", ylabel="abundance score")

fig.tight_layout()

FIGS = ROOT / "results" / "figures"
FIGS.mkdir(parents=True, exist_ok=True)
fig.savefig(FIGS / "score_distributions.png", dpi=300, bbox_inches="tight")
fig.savefig(FIGS / "score_distributions.pdf", bbox_inches="tight")

• PNG at 300 dpi for slides and documents; PDF or SVG (vector, infinitely sharp) for papers and posters.
• bbox_inches="tight" trims the white border so labels are not clipped.
• Use one palette and keep each category the same colour in every figure. Readers learn your colours.
• The colorblind palette is a safe default; avoid red/green as the only distinction.