Nested Containment Lists (NCLS)

0.0.70 verified Fri May 01 auth: no python

A fast interval tree-like implementation in C, wrapped for the Python ecosystem. It provides data structures for nested interval containment queries (e.g., finding all intervals containing a point or overlapping a range). Version 0.0.70 is current; releases are infrequent and versioned 0.0.x.

pip install ncls

Common errors

error ValueError: cannot convert to numpy array ↓

cause Input arguments to NCLS() are lists or tuples instead of numpy arrays.

fix

Pass numpy arrays: starts = np.array([...]), ends = np.array([...]), ids = np.array([...]).

error TypeError: 'ncls.NCLS' object is not iterable ↓

cause Attempting to iterate over the NCLS object directly. The object does not support iteration; use find_overlap or other query methods.

fix

Use ncls.find_overlap(start, end) which returns an array of indices.

error ImportError: No module named 'ncls' ↓

cause The ncls package is not installed or installed in a different Python environment.

fix

Install via pip: pip install ncls. Ensure you are using the correct Python interpreter.

Warnings

gotcha All input arrays must be numpy arrays; Python lists are not accepted. ↓

fix Convert inputs using np.array() before passing to NCLS constructor.

gotcha starts and ends must be sorted ascending. The constructor does not sort them; passing unsorted arrays may produce incorrect results or errors. ↓

fix Sort input arrays before constructing NCLS, e.g., sort via numpy or pandas.

deprecated The 'find' method has been deprecated in favor of 'find_overlap'. Using 'find' may produce warnings or be removed in future versions. ↓

fix Use ncls.find_overlap(start, end) instead of ncls.find(start, end).

Imports

NCLS
wrong
```
import ncls
```
correct
```
from ncls import NCLS
```
The class is NCLS, not the package name; import ncls alone gives you the module object, not the class.

Quickstart

Create an NCLS object from numpy arrays and query overlap with a range.

from ncls import NCLS
import numpy as np

starts = np.array([10, 20, 30])
ends = np.array([15, 25, 35])
ids = np.array([1, 2, 3])

ncls = NCLS(starts, ends, ids)

# Find intervals overlapping [12, 22]
overlap_indices = ncls.find_overlap(12, 22)
print(overlap_indices)