Metadata-Version: 2.5
Name: damicore-distance
Version: 0.2.0
Summary: Normalized Compression Distance (NCD) matrix computation for the DAMICORE pipeline.
Project-URL: Homepage, https://github.com/Delbem-Research-and-Innovation/damicore
Project-URL: Repository, https://github.com/Delbem-Research-and-Innovation/damicore
Project-URL: Issues, https://github.com/Delbem-Research-and-Innovation/damicore/issues
Project-URL: Documentation, https://github.com/Delbem-Research-and-Innovation/damicore/blob/main/docs/quickstart.md
Project-URL: Changelog, https://github.com/Delbem-Research-and-Innovation/damicore/blob/main/CHANGELOG.md
Author-email: Ennio Politi Lopes <enniolopes@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: compression,compression-distance,damicore,distance-matrix,ncd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pydantic<3,>=2.10
Provides-Extra: pandas
Requires-Dist: pandas<4,>=2.2; extra == 'pandas'
Description-Content-Type: text/markdown

# damicore-distance

damicore-distance computes an exact, unclamped, `float64` Normalized Compression
Distance (NCD) matrix from a normalization manifest. It is the second stage of
the DAMICORE pipeline; most users install the aggregate `damicore` distribution,
which runs all four stages end to end. Install this package alone to compute NCD
matrices without the rest of the pipeline.

```bash
pip install damicore-distance
```

## Python

```python
from damicore_distance import DistanceConfig, compute_distance_matrix

# `workers="auto"` opens a process pool whose workers re-import the calling module, so in a
# `.py` script this call must sit under the guard below. A notebook or REPL satisfies it too.
if __name__ == "__main__":
    result = compute_distance_matrix(
        "normalization/manifest.json",
        "run",
        config=DistanceConfig(compressor="zlib", workers="auto"),
    )
```

The manifest is produced by the sibling `damicore-normalizer` distribution; the
call writes `distance.npy` and `labels.json`, the inputs the sibling
`damicore-tree-builder` distribution consumes. Compression is incremental, pairs
are lexicographically sharded, only the coordinator writes the memory map, and
compatible completed shards can resume.

`DistanceMatrixView` reads the matrix through NumPy slicing and `shape` with no
extra dependency. Its two pandas conveniences, `head()` and `to_pandas()`, raise
a `DistanceError` (`missing_dependency_error`) unless pandas is present; install
it with `pip install "damicore-distance[pandas]"`.

## Links

- Repository: <https://github.com/Delbem-Research-and-Innovation/damicore>
- Issues: <https://github.com/Delbem-Research-and-Innovation/damicore/issues>
- Documentation:
  <https://github.com/Delbem-Research-and-Innovation/damicore/blob/main/docs/quickstart.md>

Licensed under Apache-2.0.
