BBB-Nuke CLI Tutorial

A step-by-step guide for scientists · Version 0.9.4 · Attention Labs

Before You Start

This tutorial assumes you have a terminal (also called "command line") open on your computer. If you have never used a terminal before, here is how to open one:

• Mac — Open Terminal from Applications > Utilities, or press Cmd + Space and type "Terminal".
• Windows — Open PowerShell from the Start menu, or press Win + R and type powershell.
• Linux — Press Ctrl + Alt + T.

Once your terminal is open, you will see a blinking cursor. This is where you type commands. Press Enter after each command to run it.

1. Installing BBB-Nuke

Copy and paste the following command into your terminal and press Enter:

pip install bbnuke

If you also want visualization features (heatmaps and report cards), install with:

pip install "bbnuke[viz]"

To verify the installation worked:

bbnuke --help

You should see something like:

BBB-Nuke: Blood-brain barrier penetration screening pipeline

usage: bbnuke [-h] {run,screen,heatmap,report,tutorial,score-single} ...

2. Scoring a Single Compound

This is the simplest way to use BBB-Nuke. You provide one molecule as a SMILES string and get a full report back.

What is a SMILES string?

SMILES is a way to represent chemical structures as text. For example:

You can find SMILES strings for your compounds on PubChem — search for any drug name and look for the "Canonical SMILES" field.

Running the command

bbnuke score-single --smiles "CC(=O)Oc1ccccc1C(=O)O" --name aspirin

Breaking this down:

Reading the output

The command prints a JSON block to your screen. Here are the key fields:

"p_bbb": 0.914       ← Final BBB penetration probability (0 to 1)
"cns_mpo score": 6.0  ← CNS-MPO desirability score (0 to 6)
"clogd": 1.31         ← Calculated LogD at pH 7.4
"veto": false          ← Whether an efflux transporter blocked this compound

Interpreting P_BBB:

Saving the output to a file

By default, the result is printed to your screen. To save it to a file instead:

bbnuke score-single --smiles "CC(=O)Oc1ccccc1C(=O)O" --name aspirin > aspirin_result.json

The > symbol tells the terminal to write the output to a file called aspirin_result.json instead of displaying it.

3. Screening Multiple Compounds (Batch Mode)

When you have more than one compound to test, use the batch run command. This is the most common workflow.

Step 1: Prepare your input file

Create a CSV file (you can use Excel, Google Sheets, or any text editor) with two columns: compound_id and smiles.

Save it as compounds.csv:

compound_id,smiles
serotonin,C1=CC2=C(C=C1O)C(=CN2)CCN
dopamine,NCCc1ccc(O)c(O)c1
caffeine,Cn1c(=O)c2c(ncn2C)n(C)c1=O
aspirin,CC(=O)Oc1ccccc1C(=O)O
risperidone,CC1=C(C(=O)N2CCCCC2)ON=C1C3=CC=C(F)C=C3

Step 2: Run the screening

Navigate to the folder where your CSV is located. For example, if it is on your Desktop:

cd ~/Desktop

Then run:

bbnuke run --input compounds.csv --output results.json

BBB-Nuke will process each compound and print a summary:

[OK] Processed 5 compounds, 4 passed MPO filter
[OK] Results written to results.json

Step 3: View the results

Open results.json in a text editor to see the detailed output for each compound.

4. Getting Results as a Spreadsheet (CSV Output)

If you prefer to work with results in Excel or Google Sheets:

bbnuke run --input compounds.csv --output results.csv --format csv

The only change is --format csv at the end.

What the CSV columns mean

5. Generating an Interactive Heatmap

The heatmap gives you a bird's-eye view of your entire screening. Each compound is a row, each property is a column, and cells are color-coded.

# From JSON results
bbnuke heatmap --input results.json

# From CSV results
bbnuke heatmap --input results.csv

# Custom output path, don't auto-open browser
bbnuke heatmap --input results.json --output my_heatmap.html --no-open

How to read the heatmap

The heatmap is divided into four sections:

 Properties        | CNS-MPO | Efflux Transporters (9)    | P_BBB
 MW LogP TPSA      |   MPO   | MDR1 ABCG2 MRP1 MRP2 ...  | P_BBB
 HBD HBA cLogD     |         |                             |

• Green = low value, Purple = high value (for most columns)
• P_BBB is inverted: Green = high penetration (good)
• Gray cells = missing data (compound didn't pass CNS-MPO filter)

Interacting with the heatmap:

• Hover over any cell to see the exact value
• Zoom by clicking and dragging a box around an area
• Pan by holding Shift and dragging
• Reset by double-clicking anywhere

6. Generating Compound Report Cards

Report cards give you a detailed visual summary for each compound — including a 2D structure drawing, a radar chart of CNS-MPO subscores, and a bar chart of efflux transporter binding.

# All compounds
bbnuke report --input results.json

# From CSV (re-runs pipeline for full data)
bbnuke report --input results.csv

# Single compound only
bbnuke report --input results.json --compound-id caffeine

# Custom output, don't open browser
bbnuke report --input results.json --output my_report.html --no-open

What each report card shows

1. Header — compound name, SMILES, and a color-coded P_BBB badge:

• High P_BBB above 0.7
• Moderate P_BBB 0.4 to 0.7
• Low P_BBB below 0.4

2. Molecule structure — a 2D drawing generated from the SMILES string.

3. CNS-MPO radar chart — a spider plot with 6 axes (MW, LogP, TPSA, HBD, pKa, cLogD). Bigger coverage = better drug-likeness for the brain.

4. Efflux bar chart — horizontal bars for 9 efflux transporters. A dashed red line at 0.7 marks the veto threshold.

5. Properties table — all physicochemical data in one place.

Sorting and searching

For large screens, the toolbar at the top of the report lets you:

• Sort by P_BBB or CNS-MPO (ascending/descending)
• Search by compound name or SMILES substring in real time

Light and dark mode

Click the moon/sun icon in the top-right corner to toggle themes. Chart labels update automatically.

7. Complete Workflow Example

Say you have 20 candidate compounds and want to screen them for BBB penetration.

Step 1: Create your input file

compound_id,smiles
compound_01,CCO
compound_02,c1ccccc1
compound_03,CC(=O)Oc1ccccc1C(=O)O
...

Save as my_compounds.csv.

Step 2: Run the batch screen

bbnuke run --input my_compounds.csv --output my_results.json

Step 3: Also save as CSV (for Excel)

bbnuke run --input my_compounds.csv --output my_results.csv --format csv

Step 4: Generate a heatmap

bbnuke heatmap --input my_results.json --output screening_heatmap.html

Open the HTML file in your browser. Hover over cells to see values. Look for compounds that are green in the P_BBB column.

Step 5: Generate report cards

bbnuke report --input my_results.json --output screening_report.html

Use the sort buttons to rank compounds by P_BBB. Click a compound in the sidebar to jump to its card.

Step 6: Dive into a specific compound

bbnuke report --input my_results.json --compound-id compound_03 --output compound_03_report.html

8. Tips and Common Questions

My CSV has different column names

If your CSV uses name instead of compound_id, and SMILES instead of smiles:

bbnuke run --input my_data.csv --output results.json --id-col name --smiles-col SMILES

Score one molecule without creating a CSV

bbnuke score-single --smiles "Cn1c(=O)c2c(ncn2C)n(C)c1=O" --name caffeine

What does "passed MPO filter" mean?

The CNS-MPO score ranges from 0 to 6. Compounds scoring below 3.0 are flagged as unlikely to penetrate the BBB. They still get a P_BBB score, but skip efflux transporter screening.

What does "vetoed" mean?

If any of the 9 efflux transporter proteins has a binding probability above 0.7, the compound is vetoed — efflux pumps would actively transport it back out of the brain. A vetoed compound gets a P_BBB near 0.

What are the 9 efflux proteins?

How long does it take?

To use a GPU for large batches:

export BBNUKE_PSICHIC_DEVICE=cuda
bbnuke run --input large_library.csv --output results.json

Where do I get SMILES strings?

• PubChem — search by drug name, find "Canonical SMILES"
• ChEMBL — search by compound name or target
• DrugBank — search by drug name
• ChemDraw, Marvin, and similar tools can export SMILES from drawn structures

The command says "command not found"

pip install bbnuke

If using conda, activate the right environment first:

conda activate my_environment
pip install bbnuke

The heatmap or report won't open in my browser

Use --no-open and open the file manually:

bbnuke heatmap --input results.json --no-open
open bbnuke_heatmap.html        # Mac
xdg-open bbnuke_heatmap.html    # Linux
start bbnuke_heatmap.html       # Windows

9. Quick Reference Card