PDB_Query

This is my first bioinformatics python miniproject

PDBTools

A beginner-friendly Python tool for exploring protein structures from the Protein Data Bank (PDB). No programming experience required to use it.

---

What is a PDB File?

A PDB (Protein Data Bank) file is a text file that describes the 3D structure of a biological molecule — usually a protein. It contains information such as:

• The protein's name, source organism, and experimental method
• The sequence of amino acids that make up the protein
• The 3D coordinates of every atom in the structure
• Ligands and small molecules bound to the protein (e.g. drug molecules)

PDB files are downloaded from the RCSB Protein Data Bank, the world's largest repository of protein structure data. Every structure has a unique 4-character ID called a PDB ID (e.g. 1HIV, 1A3N, 3RY2).

---

What Does PDBTools Do?

PDBTools is an interactive command-line tool that lets you:

• Download any protein structure from the RCSB database using its PDB ID
• Read the file and extract key information
• Query specific data such as the protein title, authors, resolution, amino acid sequence, atom records, and ligands
• Export sequences in FASTA format for use in other bioinformatics tools
• Visualise the temperature factor (flexibility) of a protein chain
• Modify chain IDs and save the altered structure

You do not need to write any code. The tool runs interactively — it asks you questions and you type your answers.

---

What You Need Before Starting

1. A Computer Running Linux, macOS, or Windows (with WSL)

PDBTools is designed to run on a Unix-based terminal. On Windows, use Windows Subsystem for Linux (WSL).

2. An Internet Connection

Required the first time you download a PDB file. Once downloaded, the file is stored locally and does not need to be downloaded again.

3. Miniconda or Anaconda

Conda is a tool that manages Python environments. It ensures PDBTools runs with the correct version of Python and all required packages.

To check if you already have conda installed, open your terminal and type:

conda --version

If you see a version number (e.g. conda 23.5.0), you are good to go.

If not, install Miniconda by following the instructions at: https://docs.conda.io/en/latest/miniconda.html

---

Step-by-Step Installation

Step 1 — Download PDBTools

Download or clone the PDBTools package to your computer. If you have git installed:

git clone https://github.com/yourusername/PDBTools.git

Or download and extract the ZIP file manually. You should end up with a folder called PDBTools containing these files:

PDBTools/
├── pdblib.py
├── checkPDB.py
├── __init__.py
├── data/
└── README.md

Step 2 — Open Your Terminal

On Linux or macOS, open the Terminal application. On Windows, open WSL or Anaconda Prompt.

Step 3 — Navigate to the PDBTools Folder

Use the cd command to move into the PDBTools directory. For example:

cd ~/PDBTools

If you downloaded it to your Downloads folder:

cd ~/Downloads/PDBTools

To confirm you are in the right place, type:

ls

You should see pdblib.py, checkPDB.py, and the other files listed above.

Step 4 — Create the Conda Environment

This sets up a clean Python 3.11 environment with all required packages. Copy and run each command one at a time:

conda create -n py311 python=3.11

When asked Proceed ([y]/n)? type y and press Enter.

conda activate py311

Your terminal prompt should now show (pdbtools) at the start, confirming the environment is active.

conda install -c conda-forge requests matplotlib

This installs the two external packages PDBTools needs:

• requests — for downloading PDB files from the internet
• matplotlib — for generating plots

Step 5 — You Are Ready

Every time you want to use PDBTools in the future, you only need to:

conda activate py311
cd ~/PDBTools
python checkPDB.py

You do not need to repeat Steps 1–4 again.

---

How to Run PDBTools

Make sure your conda environment is active (you should see (py311) in your terminal prompt). Then run:

python checkPDB.py

You will see a welcome message:

===Welcome to the PDB arena===

Please enter the PDB ID:

Type a 4-character PDB ID (e.g. 1HIV) and press Enter.

The program will check if you already have that file saved locally. If not, it will download it automatically from the RCSB and confirm:

Successfully downloaded your file!

You will then see the full options menu:

Please select an option from this

1  for header
2  for title
3  for authors
4  for journal title
5  for source
6  for resolution
7  for keywords
8  to get hetatm lines
9  to get atom lines
10 to get unique chain IDs
11 to filter by chain ID
12 to print single letter residues for a chain
13 to write a FASTA file
14 to print or write lines by chain and record type
15 to alter chain ID and save
16 to plot temperature factor

Type Quit or Q or q to quit

Enter an option to proceed:

Type a number and press Enter to select an option.

---

Menu Options Explained

Options 1–7 — Basic Protein Information

These options display text information extracted from the PDB file header. Simply type the number and press Enter — no extra input needed.

Option	What It Shows	Example Output
1	Header — molecule type, date, PDB ID	HYDROLASE/HYDROLASE INHIBITOR 12-FEB-92 1HIV
2	Title — full descriptive title	CRYSTAL STRUCTURE OF HIV-1 PROTEASE...
3	Authors — researchers who solved the structure	N.THANKI, A.WLODAWER...
4	Journal title — publication this structure came from	PROTEIN SCI.
5	Source — organism the protein came from	ORGANISM_SCIENTIFIC: HUMAN IMMUNODEFICIENCY VIRUS 1
6	Resolution — quality of the structure in Angstroms	2.50
7	Keywords — biological classification terms	ACID PROTEINASE, HYDROLASE-HYDROLASE INHIBITOR COMPLEX

---

Options 8–9 — Atom Records

Option 8 — HETATM lines Displays all HETATM records. These are non-standard atoms — ligands, drug molecules, water molecules, and cofactors bound to the protein. Particularly useful for pharmacology applications where you want to see what small molecules are present in the structure.

Option 9 — ATOM lines Displays all ATOM records. These are the standard protein atoms — every atom in every amino acid of the protein chain.

Note: These options produce a lot of output for large proteins. It is recommended to use Option 14 to filter by chain ID instead.

---

Option 10 — Unique Chain IDs

Proteins can have multiple chains (subunits). This option shows you all the chain IDs present in the structure.

Enter an option to proceed: 10
{'A', 'B'}

This means the structure has two chains — chain A and chain B. You will need to know the chain IDs before using Options 11–16.

---

Option 11 — Filter Atom Lines by Chain ID

Shows all ATOM lines belonging to a specific chain.

Enter an option to proceed: 11
Enter your chain ID: A

Returns all atom records for chain A only.

---

Option 12 — Single Letter Residue Sequence

Prints the amino acid sequence of a chain as a single continuous string using the standard single-letter amino acid code (e.g. A for Alanine, G for Glycine).

Enter an option to proceed: 12
Enter chain ID: A
PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMNLPGRWKPKMIGGIGGFIKVRQYDQ...

This sequence can be used directly in other bioinformatics tools such as BLAST for sequence similarity searches or multiple sequence alignment tools.

---

Option 13 — Write FASTA File

Saves the protein sequence in FASTA format — a standard file format used across bioinformatics tools.

Enter an option to proceed: 13
Enter chain ID (or press Enter for all chains): A
Enter output filename: my_protein

This creates a file called my_protein.fasta in your current directory.

If you press Enter without typing a chain ID, the program saves all chains as separate entries in one FASTA file.

Example FASTA output:

>HYDROLASE/HYDROLASE INHIBITOR_A
PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMNLPGRWKPKMIGGIGGFIKVRQYDQ...
>HYDROLASE/HYDROLASE INHIBITOR_B
PQITLWQRPLVTIKIGGQLKEALLDTGADDTVLEEMNLPGRWKPKMIGGIGGFIKVRQYDQ...

---

Option 14 — Print or Write Lines by Chain and Record Type

Filters atom lines by chain ID and record type, then either displays them on screen or saves them to a file.

Enter an option to proceed: 14
Enter chain ID: A
Enter a record type: ATOM
Enter preferred action: PRINT

Record type options:

• ATOM — standard protein atoms only
• HETATM — ligands and small molecules only
• Press Enter without typing — returns both ATOM and HETATM

Action options:

• PRINT — displays lines on screen
• WRITE — saves to a file (you will be asked for a filename)

---

Option 15 — Alter Chain ID and Save

Changes all occurrences of one chain ID to another and saves the modified structure as a new PDB file.

Enter an option to proceed: 15
Enter current ID: A
Enter new ID: C
Enter filename: modified_structure

This creates modified_structure.pdb where all chain A atoms are now labelled as chain C. The original file is not changed.

---

Option 16 — Plot Temperature Factor

Generates a plot of the temperature factor (B-factor) against residue number for a specified chain and saves it as a PNG image.

Enter an option to proceed: 16
Enter chain ID: A
Enter width: 10
Enter height: 6
Enter filename: my_plot

This creates my_plot.png in your current directory.

What does the temperature factor mean? The B-factor measures how much each atom moves or vibrates in the crystal. High B-factor values indicate flexible or disordered regions. Low values indicate rigid, well-defined regions. This is useful for identifying flexible loops or stable structural elements in a protein.

---

Exiting the Program

To exit PDBTools at any time, type any of the following and press Enter:

quit
q
Q

You will see:

You have exited successfully

---

Error Handling

PDBTools is designed to handle invalid input gracefully:

• If you enter a chain ID that does not exist, the program will tell you and remind you to use Option 10 to check available chains
• If you enter an invalid menu option, the program prints Invalid option and shows the menu again
• If a download fails, the program will notify you
• The program will never crash with a technical error traceback — all errors produce readable messages

---

Test PDB Files

The data/ folder contains three test structures used during development. These are compressed in .tar.gz format.

To decompress them:

tar -xzf data/pdb_files.tar.gz -C data/

PDB ID	Protein	Relevance
1HIV	HIV-1 Protease	Drug target — Hydrolase/Inhibitor complex
1A3N	Haemoglobin	Oxygen transport protein
3RY2	CYP2D6	Human cytochrome P450 — drug metabolism enzyme

---

Troubleshooting

conda: command not found Conda is not installed or not on your PATH. Install Miniconda from https://docs.conda.io/en/latest/miniconda.html and restart your terminal.

ModuleNotFoundError: No module named 'requests' Your conda environment is not active. Run conda activate py311 first.

(pdbtools) not showing in terminal Run conda activate py311 before running the script.

FileNotFoundError Make sure you are running the script from inside the PDBTools directory. Run cd ~/PDBTools first.

Download fails or times out Check your internet connection. The RCSB server may also be temporarily unavailable — try again after a few minutes.

---

Dependencies

Package	Version	Purpose
Python	3.11	Core language
requests	latest	Downloading PDB files from RCSB
matplotlib	latest	Plotting temperature factor graphs

All other functionality uses Python built-in libraries only.

---

PDB Format Reference

PDBTools parses files according to the official PDB format specification: https://www.cgl.ucsf.edu/chimera/docs/UsersGuide/tutorials/pdbintro.html

---

Author

Sylvesters — MSc Bioinformatics