Quick Start

This guide walks you through running your first genomic neighborhood analysis using Hoodini Colab in Google Colab.

Prerequisites

All you need is:

A Google account (for Google Colab)
A web browser
NCBI protein or nucleotide IDs to analyze

No local installation required! Everything runs in the cloud.

Your First Analysis

Open Google Colab

Click the badge below to open the pre-configured notebook:

Install the Package

Run the first cell to install hoodini-colab:


!pip install -q hoodini-colab

This takes about 10-15 seconds.

Run the second cell to display the interactive launcher:


from hoodini_colab import create_launcher
 
launcher = create_launcher()
display(launcher)

You’ll see the Hoodini Colab interface with collapsible configuration sections.

Configure Your Input

In the Input section:

Select your input mode:
- Single Input — Enter a single NCBI protein ID (e.g., WP_012345678.1)
- Input List — Paste multiple IDs, one per line
- Input Sheet — Provide a table with coordinates and assembly info
Enter your protein or nucleotide ID(s)
Set the output directory (default: hoodini_output)

Choose Annotation Tools (Optional)

Expand the Annotations section and toggle the tools you want:

PADLOC — Antiphage defense systems
DefenseFinder — Defense system detection
CCtyper — CRISPR-Cas systems
geNomad — Mobile genetic elements
eggNOG — Functional annotations

Each annotation tool requires downloading its database on first use. Enable only the tools you need to minimize setup time.

Run the Analysis

Click “Run Hoodini Analysis” at the bottom of the widget.

The widget will:

Install Hoodini via pixi (first run only, ~3-5 min)
Download required databases (first run only, ~2-5 min per tool)
Execute your analysis
Show progress in real-time

Download Results

When complete, your results will be in the output directory. You can:

Browse files in the Colab file panel (left sidebar)
Download the entire folder as a ZIP
Open the interactive HTML visualization directly

Understanding the Output

After a successful run, you’ll find:

File	Description
`hoodini_viz.html`	Interactive visualization (open in browser)
`neighborhoods.tsv`	Neighborhood data in tabular format
`proteins.faa`	Extracted protein sequences
`tree.nwk`	Phylogenetic tree (if tree-mode enabled)
`annotations/`	Results from annotation tools

Example: Analyzing a Defense System

Let’s analyze the genomic neighborhoods around a DUF4297-containing protein:

In Input Mode, select “Single Input”
Enter: WP_011712265.1
Enable PADLOC and DefenseFinder in Annotations
Set Tree Mode to taxonomy_tree
Click Run Hoodini Analysis

This will:

Find homologs via remote BLAST
Extract their genomic neighborhoods
Detect defense systems in each neighborhood
Build a taxonomy-based tree
Generate an interactive visualization

Tips for Better Performance

Add an NCBI API key to increase rate limits and speed up data downloads. Get one free at NCBI .

Start small: Test with a few sequences before running large analyses
Limit annotation tools: Each tool adds database download time
Use taxonomy trees: Faster than AAI/ANI-based trees for large datasets
Reuse sessions: Keep the Colab session open to avoid re-installing Hoodini

Next Steps

Use Cases — Common analysis scenarios
API Reference — Programmatic access
Hoodini CLI — Full CLI documentation