{"id":24106,"library":"ncls","title":"Nested Containment Lists (NCLS)","description":"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.","status":"active","version":"0.0.70","language":"python","source_language":"en","source_url":"https://github.com/pyranges/ncls","tags":["interval-tree","genomics","containment-query","overlap","bioinformatics"],"install":[{"cmd":"pip install ncls","lang":"bash","label":"PyPI"}],"dependencies":[],"imports":[{"note":"The class is NCLS, not the package name; import ncls alone gives you the module object, not the class.","wrong":"import ncls","symbol":"NCLS","correct":"from ncls import NCLS"}],"quickstart":{"code":"from ncls import NCLS\nimport numpy as np\n\nstarts = np.array([10, 20, 30])\nends = np.array([15, 25, 35])\nids = np.array([1, 2, 3])\n\nncls = NCLS(starts, ends, ids)\n\n# Find intervals overlapping [12, 22]\noverlap_indices = ncls.find_overlap(12, 22)\nprint(overlap_indices)","lang":"python","description":"Create an NCLS object from numpy arrays and query overlap with a range."},"warnings":[{"fix":"Convert inputs using np.array() before passing to NCLS constructor.","message":"All input arrays must be numpy arrays; Python lists are not accepted.","severity":"gotcha","affected_versions":"all"},{"fix":"Sort input arrays before constructing NCLS, e.g., sort via numpy or pandas.","message":"starts and ends must be sorted ascending. The constructor does not sort them; passing unsorted arrays may produce incorrect results or errors.","severity":"gotcha","affected_versions":"all"},{"fix":"Use ncls.find_overlap(start, end) instead of ncls.find(start, end).","message":"The 'find' method has been deprecated in favor of 'find_overlap'. Using 'find' may produce warnings or be removed in future versions.","severity":"deprecated","affected_versions":">=0.0.57"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Pass numpy arrays: starts = np.array([...]), ends = np.array([...]), ids = np.array([...]).","cause":"Input arguments to NCLS() are lists or tuples instead of numpy arrays.","error":"ValueError: cannot convert to numpy array"},{"fix":"Use ncls.find_overlap(start, end) which returns an array of indices.","cause":"Attempting to iterate over the NCLS object directly. The object does not support iteration; use find_overlap or other query methods.","error":"TypeError: 'ncls.NCLS' object is not iterable"},{"fix":"Install via pip: pip install ncls. Ensure you are using the correct Python interpreter.","cause":"The ncls package is not installed or installed in a different Python environment.","error":"ImportError: No module named 'ncls'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}