ncls

library0.0.70pypypi✓ verified 83d ago

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.

data

pip install ncls

github ↗package ↗

INSTALL

IMPORT

SIG · NCLS

ncls

datapythonv0.0.70

Install

3.7s avg

Import

323ms

Disk

102MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.0.70 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 3.5s

py 3.11

✓ —

✓ 3.5s

py 3.12

✓ —

✓ 3.5s

py 3.13

✕ build_error

py 3.9

✓ —

✓ 4.4s

102MB installed

● package 102MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NCLS

✓ from ncls import NCLS

✗ import ncls

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

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)

Debug

Known issues

gotchaAll input arrays must be numpy arrays; Python lists are not accepted.

fix

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

affects: all

gotchastarts 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.

affects: all

deprecatedThe '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).

affects: >=0.0.57

Errors

Common errors & fixes

ValueError: cannot convert to numpy array

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([...]).

TypeError: 'ncls.NCLS' object is not iterable

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.

ImportError: No module named 'ncls'

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.

Upgrade

Version history

0.0.70latest on PyPI · released Jul 4, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttp://github.com/pyranges/ncls ↗

packagehttps://pypi.org/project/ncls/ ↗