mlarray 0.0.54__tar.gz → 1.0.0__tar.gz

{mlarray-0.0.54 → mlarray-1.0.0}/.github/workflows/workflow.yml

@@ -18,7 +18,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -35,7 +35,13 @@ jobs:
 
       - name: Run tests
         run: |
-          pytest || if [ $? -eq 5 ]; then echo "No tests collected; skipping."; exit 0; else exit $?; fi
+          status=0
+          pytest || status=$?
+          if [ "$status" -eq 5 ]; then
+            echo "No tests collected; skipping."
+            exit 0
+          fi
+          exit "$status"
 
   publish:
     needs: tests
@@ -61,10 +67,8 @@ jobs:
       - name: Check metadata
         run: python -m twine check dist/*
 
-      - name: Publish to PyPI
+      - name: Publish to PyPI (trusted publishing)
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
 
   docs:
     needs: tests

{mlarray-0.0.54 → mlarray-1.0.0}/PKG-INFO

@@ -1,25 +1,29 @@
 Metadata-Version: 2.4
 Name: mlarray
-Version: 0.0.54
+Version: 1.0.0
 Summary: Array format specialized for Machine Learning with Blosc2 backend and standardized metadata.
 Author-email: Karol Gotkowski <karol.gotkowski@dkfz.de>
 License: MIT
 Project-URL: Homepage, https://github.com/MIC-DKFZ/mlarray
 Project-URL: Source, https://github.com/MIC-DKFZ/mlarray
 Project-URL: Issues, https://github.com/MIC-DKFZ/mlarray/issues
-Keywords: copier,template,python
+Keywords: machine learning,medical imaging,blosc2,array,file format
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Operating System :: OS Independent
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: blosc2>=3
 Requires-Dist: numpy>=2
+Requires-Dist: msgpack>=1.0
+Requires-Dist: xxhash>=3.0
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.18; extra == "dev"
 Requires-Dist: pytest>=7.0; extra == "dev"
 Requires-Dist: twine>=4.0; extra == "dev"
 Requires-Dist: setuptools_scm[toml]>=8.0; extra == "dev"
@@ -29,7 +33,7 @@ Requires-Dist: mkdocs-include-markdown-plugin>=6.0; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
 Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
 Provides-Extra: all
-Requires-Dist: medvol; extra == "all"
+Requires-Dist: medvol>=1.0.0; extra == "all"
 Dynamic: license-file
 
 <p align="center">
@@ -55,7 +59,7 @@ You can install mlarray via [pip](https://pypi.org/project/mlarray/):
 pip install mlarray
 ```
 
-To enable the `mlarray_convert` CLI command, install MLArray with the necessary extra dependencies:
+To enable the `mlarray_convert` CLI command (conversion with MedVol 1.0 or newer), install MLArray with the extra dependencies:
 ```bash
 pip install mlarray[all]
 ```
@@ -101,7 +105,15 @@ image = MLArray.create("sample.mla", shape=array.shape, dtype=array.dtype, mmap_
 image[...] = array  # Modify image in memory and disk
 ```
 
-### Metadata inspection and manipulation
+### Fast reading
+
+`MLArray.open` reads lazily: `image[...]` decompresses only the chunks a patch touches. The first open in a process also turns on blosc2's read-ahead (4 threads), which fetches those chunks in parallel and makes reads of data not in the page cache several times faster, especially on network storage. Change it with `mlarray.set_read_ahead(n)` (`0` turns it off) or the `BLOSC_PREFETCH` environment variable. Files are written with nnU-Net's layout and compression settings; see [ML Optimization](docs/optimization.md) for details.
+
+### Metadata
+
+Metadata is explicit and domain-neutral: what each axis is, where the array sits in physical space, what
+its values mean, optional domain profiles, and your own metadata. Geometry is never implied: spacing,
+origin and direction always refer to a declared space.
 
 ```python
 import numpy as np
@@ -110,63 +122,44 @@ from mlarray import MLArray
 array = np.random.random((64, 128, 128))
 image = MLArray(
     array,
-    spacing=(1.0, 1.0, 1.5),
-    origin=(10.0, 10.0, 30.0),
-    direction=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
-    meta={"patient_id": "123", "modality": "CT"},  # Any metadata from the original image source (for example raw DICOM metadata)
+    axes=["z", "y", "x"],
+    spacing=(1.5, 1.0, 1.0),          # per array axis, in array order
+    origin=(10.0, 10.0, 30.0),        # centre of index (0, 0, 0)
+    direction=[[0, 0, 1], [0, 1, 0], [1, 0, 0]],  # column c: unit vector of array axis c
+    space="patient",                  # DICOM patient frame (LPS)
+    values={"kind": "measurement", "unit": "hounsfield_unit"},
+    user={"patient_id": "123"},       # any metadata of your own
 )
 
-print(image.spacing)  # [1.0, 1.0, 1.5]
-print(image.origin)  # [10.0, 10.0, 30.0]
-print(image.meta.source)  # {"patient_id": "123", "modality": "CT"}
-
-image.spacing[1] = 5.3
-image.meta.source["study_id"] = "study-001"
+print(image.spacing)         # (1.5, 1.0, 1.0)
+print(image.letter_codes())  # ('S', 'P', 'L')
+image.set_geometry(spacing=(1.5, 5.3, 1.0))
+image.user["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray.open("with-metadata.mla", mmap_mode='r+')  
-image.meta.source["study_id"] = "new-study"  # Modify metadata
+image = MLArray.open("with-metadata.mla", mmap_mode='r+')
+image.user["study_id"] = "new-study"  # Modify metadata
 image.close()  # Close and save metadata, only necessary to save modified metadata
 ```
 
-### Copy metadata with overrides
+Segmentations, ML profiles and derived images:
 
 ```python
 import numpy as np
 from mlarray import MLArray
 
-base = MLArray("sample.mla")
-array = np.random.random(base.shape)
-
-image = MLArray(
-    array,
-    spacing=(0.8, 0.8, 1.0),
-    copy=base,  # Copies all non-explicitly set arguments from base
+base = MLArray("with-metadata.mla")
+seg = MLArray(
+    np.zeros(base.shape, dtype=np.uint8),
+    copy=base,  # geometry, values, profiles and user metadata of base (never its source)
+    values={"kind": "label", "labels": {"0": {"name": "background"}, "1": {"name": "liver"}}},
+    profiles={"ml": {"split": "train"}},
 )
-
-image.save("copied-metadata.mla")
+seg.save("seg.mla")
 ```
 
-### Standardized metadata usage
-
-```python
-import numpy as np
-from mlarray import MLArray, Meta
-
-array = np.random.random((64, 128, 128))
-image = MLArray(
-    array,
-    meta=Meta(source={"patient_id": "123", "modality": "CT"}, is_seg=True),  # Add metadata in a pre-defined format
-)
-
-print(image.meta.source)  # {"patient_id": "123", "modality": "CT"}
-print(image.meta.is_seg)  # True
-
-image.meta.source["study_id"] = "study-001"
-image.meta.is_seg = False
-image.save("with-metadata.mla")
-```
+See [Usage](docs/usage.md) and [Schema](docs/schema.md) for the full metadata model.
 
 ### Patch size variants
 
@@ -228,7 +221,8 @@ image.save("blosc2-auto.mla")
 
 ### mlarray_header
 
-Print the metadata header from a `.mla` file.
+Print the metadata of a `.mla` file as JSON (`--source` and `--user` add the original metadata of
+converted files and the user metadata).
 
 ```bash
 mlarray_header sample.mla
@@ -236,34 +230,21 @@ mlarray_header sample.mla
 
 ### mlarray_convert
 
-Convert between MLArray and NIfTI/NRRD files.
-
-When converting from NIfTI/NRRD to MLArray, source metadata is copied into
-`meta.source`.
-
-When converting from MLArray to NIfTI/NRRD, only `meta.source` is copied into
-the output header. Spatial metadata (`spacing`, `origin`, `direction`) is set
-explicitly from `meta.spatial`.
-
-`meta.spatial.coord_system` is propagated conservatively. For NRRD input, the
-CLI reads explicit NRRD space metadata when available and maps
-`right-anterior-superior` to `RAS` and `left-posterior-superior` to `LPS`,
-while preserving other explicit NRRD space strings verbatim. For NIfTI input,
-the CLI sets `coord_system` to `LPS` based on the current
-`MedVol -> SimpleITK/ITK` import path, where the imported geometry is
-represented in the ITK physical-space convention. MedVol's reindexing to NumPy
-layout does not change that world-space convention. On NRRD output, `RAS` and
-`LPS` are written back as NRRD `space` metadata when possible; arbitrary custom
-`coord_system` strings are not emitted as NRRD `space` declarations unless they
-already match a supported explicit NRRD space string. NIfTI output preserves
-geometry, but does not export `coord_system` as an explicit NIfTI metadata
-field.
+Convert between MLArray and NIfTI, NRRD, MetaImage, MGH/MGZ and DICOM with
+[MedVol](https://github.com/MIC-DKFZ/MedVol) 1.0 or newer (`pip install "mlarray[all]"`). Nothing is reoriented, rescaled or
+dropped silently: the array keeps its stored order and dtype, the geometry is taken from the file's own fields,
+the original header is kept in `source` so the file can be written back faithfully, and every choice is reported.
 
 ```bash
-mlarray_convert sample.nii.gz output.mla
-mlarray_convert sample.mla output.nii.gz
+mlarray_convert sample.nii.gz sample.mla
+mlarray_convert sample.mla roundtrip.nii.gz
+mlarray_convert dicom_dir/ ct.mla --dicom-tilt exact
+mlarray_convert ct.mla out_dir/ --target-format dicom      # re-emits the original DICOM series
 ```
 
+Ambiguities are resolved by explicit MedVol policies, e.g. `--nifti-form sform` when a NIfTI's qform and sform
+disagree, or `--world-frame ras` to store the patient space in RAS instead of DICOM's LPS.
+
 ## Contributing
 
 Contributions are welcome! Please open a pull request with clear changes and add tests when appropriate.

{mlarray-0.0.54 → mlarray-1.0.0}/README.md

@@ -21,7 +21,7 @@ You can install mlarray via [pip](https://pypi.org/project/mlarray/):
 pip install mlarray
 ```
 
-To enable the `mlarray_convert` CLI command, install MLArray with the necessary extra dependencies:
+To enable the `mlarray_convert` CLI command (conversion with MedVol 1.0 or newer), install MLArray with the extra dependencies:
 ```bash
 pip install mlarray[all]
 ```
@@ -67,7 +67,15 @@ image = MLArray.create("sample.mla", shape=array.shape, dtype=array.dtype, mmap_
 image[...] = array  # Modify image in memory and disk
 ```
 
-### Metadata inspection and manipulation
+### Fast reading
+
+`MLArray.open` reads lazily: `image[...]` decompresses only the chunks a patch touches. The first open in a process also turns on blosc2's read-ahead (4 threads), which fetches those chunks in parallel and makes reads of data not in the page cache several times faster, especially on network storage. Change it with `mlarray.set_read_ahead(n)` (`0` turns it off) or the `BLOSC_PREFETCH` environment variable. Files are written with nnU-Net's layout and compression settings; see [ML Optimization](docs/optimization.md) for details.
+
+### Metadata
+
+Metadata is explicit and domain-neutral: what each axis is, where the array sits in physical space, what
+its values mean, optional domain profiles, and your own metadata. Geometry is never implied: spacing,
+origin and direction always refer to a declared space.
 
 ```python
 import numpy as np
@@ -76,63 +84,44 @@ from mlarray import MLArray
 array = np.random.random((64, 128, 128))
 image = MLArray(
     array,
-    spacing=(1.0, 1.0, 1.5),
-    origin=(10.0, 10.0, 30.0),
-    direction=[[1, 0, 0], [0, 1, 0], [0, 0, 1]],
-    meta={"patient_id": "123", "modality": "CT"},  # Any metadata from the original image source (for example raw DICOM metadata)
+    axes=["z", "y", "x"],
+    spacing=(1.5, 1.0, 1.0),          # per array axis, in array order
+    origin=(10.0, 10.0, 30.0),        # centre of index (0, 0, 0)
+    direction=[[0, 0, 1], [0, 1, 0], [1, 0, 0]],  # column c: unit vector of array axis c
+    space="patient",                  # DICOM patient frame (LPS)
+    values={"kind": "measurement", "unit": "hounsfield_unit"},
+    user={"patient_id": "123"},       # any metadata of your own
 )
 
-print(image.spacing)  # [1.0, 1.0, 1.5]
-print(image.origin)  # [10.0, 10.0, 30.0]
-print(image.meta.source)  # {"patient_id": "123", "modality": "CT"}
-
-image.spacing[1] = 5.3
-image.meta.source["study_id"] = "study-001"
+print(image.spacing)         # (1.5, 1.0, 1.0)
+print(image.letter_codes())  # ('S', 'P', 'L')
+image.set_geometry(spacing=(1.5, 5.3, 1.0))
+image.user["study_id"] = "study-001"
 image.save("with-metadata.mla")
 
 # Open memory-mapped
-image = MLArray.open("with-metadata.mla", mmap_mode='r+')  
-image.meta.source["study_id"] = "new-study"  # Modify metadata
+image = MLArray.open("with-metadata.mla", mmap_mode='r+')
+image.user["study_id"] = "new-study"  # Modify metadata
 image.close()  # Close and save metadata, only necessary to save modified metadata
 ```
 
-### Copy metadata with overrides
+Segmentations, ML profiles and derived images:
 
 ```python
 import numpy as np
 from mlarray import MLArray
 
-base = MLArray("sample.mla")
-array = np.random.random(base.shape)
-
-image = MLArray(
-    array,
-    spacing=(0.8, 0.8, 1.0),
-    copy=base,  # Copies all non-explicitly set arguments from base
+base = MLArray("with-metadata.mla")
+seg = MLArray(
+    np.zeros(base.shape, dtype=np.uint8),
+    copy=base,  # geometry, values, profiles and user metadata of base (never its source)
+    values={"kind": "label", "labels": {"0": {"name": "background"}, "1": {"name": "liver"}}},
+    profiles={"ml": {"split": "train"}},
 )
-
-image.save("copied-metadata.mla")
+seg.save("seg.mla")
 ```
 
-### Standardized metadata usage
-
-```python
-import numpy as np
-from mlarray import MLArray, Meta
-
-array = np.random.random((64, 128, 128))
-image = MLArray(
-    array,
-    meta=Meta(source={"patient_id": "123", "modality": "CT"}, is_seg=True),  # Add metadata in a pre-defined format
-)
-
-print(image.meta.source)  # {"patient_id": "123", "modality": "CT"}
-print(image.meta.is_seg)  # True
-
-image.meta.source["study_id"] = "study-001"
-image.meta.is_seg = False
-image.save("with-metadata.mla")
-```
+See [Usage](docs/usage.md) and [Schema](docs/schema.md) for the full metadata model.
 
 ### Patch size variants
 
@@ -194,7 +183,8 @@ image.save("blosc2-auto.mla")
 
 ### mlarray_header
 
-Print the metadata header from a `.mla` file.
+Print the metadata of a `.mla` file as JSON (`--source` and `--user` add the original metadata of
+converted files and the user metadata).
 
 ```bash
 mlarray_header sample.mla
@@ -202,34 +192,21 @@ mlarray_header sample.mla
 
 ### mlarray_convert
 
-Convert between MLArray and NIfTI/NRRD files.
-
-When converting from NIfTI/NRRD to MLArray, source metadata is copied into
-`meta.source`.
-
-When converting from MLArray to NIfTI/NRRD, only `meta.source` is copied into
-the output header. Spatial metadata (`spacing`, `origin`, `direction`) is set
-explicitly from `meta.spatial`.
-
-`meta.spatial.coord_system` is propagated conservatively. For NRRD input, the
-CLI reads explicit NRRD space metadata when available and maps
-`right-anterior-superior` to `RAS` and `left-posterior-superior` to `LPS`,
-while preserving other explicit NRRD space strings verbatim. For NIfTI input,
-the CLI sets `coord_system` to `LPS` based on the current
-`MedVol -> SimpleITK/ITK` import path, where the imported geometry is
-represented in the ITK physical-space convention. MedVol's reindexing to NumPy
-layout does not change that world-space convention. On NRRD output, `RAS` and
-`LPS` are written back as NRRD `space` metadata when possible; arbitrary custom
-`coord_system` strings are not emitted as NRRD `space` declarations unless they
-already match a supported explicit NRRD space string. NIfTI output preserves
-geometry, but does not export `coord_system` as an explicit NIfTI metadata
-field.
+Convert between MLArray and NIfTI, NRRD, MetaImage, MGH/MGZ and DICOM with
+[MedVol](https://github.com/MIC-DKFZ/MedVol) 1.0 or newer (`pip install "mlarray[all]"`). Nothing is reoriented, rescaled or
+dropped silently: the array keeps its stored order and dtype, the geometry is taken from the file's own fields,
+the original header is kept in `source` so the file can be written back faithfully, and every choice is reported.
 
 ```bash
-mlarray_convert sample.nii.gz output.mla
-mlarray_convert sample.mla output.nii.gz
+mlarray_convert sample.nii.gz sample.mla
+mlarray_convert sample.mla roundtrip.nii.gz
+mlarray_convert dicom_dir/ ct.mla --dicom-tilt exact
+mlarray_convert ct.mla out_dir/ --target-format dicom      # re-emits the original DICOM series
 ```
 
+Ambiguities are resolved by explicit MedVol policies, e.g. `--nifti-form sform` when a NIfTI's qform and sform
+disagree, or `--world-frame ras` to store the patient space in RAS instead of DICOM's LPS.
+
 ## Contributing
 
 Contributions are welcome! Please open a pull request with clear changes and add tests when appropriate.

mlarray-1.0.0/bench/README.md

@@ -0,0 +1,8 @@
+# Benchmark Scripts
+
+- `benchmark_formats.py`: compares MLArray with other image file formats.
+
+The benchmark behind MLArray's storage defaults (layout, codec, read mode and
+read-ahead, measured on a compute cluster with nnU-Net-style loading) lives on
+the `feat/bench-suite` branch under `bench/`; `docs/optimization.md` summarizes
+its results.

{mlarray-0.0.54 → mlarray-1.0.0}/bench/benchmark_formats.py

@@ -24,7 +24,6 @@ Usage:
 
 import argparse
 import json
-import math
 import os
 import random
 import shutil
@@ -148,11 +147,11 @@ def convert_blosc2(arr: np.ndarray, out_path: Path) -> None:
     blosc2.asarray(arr, urlpath=str(out_path), mode="w")
 
 
-def convert_mlarray(arr: np.ndarray, out_path: Path) -> None:
-    """MLArray with patch-size optimized chunk/block sizes via comp_blosc2_params."""
+def convert_mlarray(arr: np.ndarray, out_path: Path, patch_size: tuple) -> None:
+    """MLArray with chunk/block sizes optimized for the benchmark patch size via comp_blosc2_params."""
     if out_path.exists():
         out_path.unlink()
-    mla = MLArray.asarray(arr)
+    mla = MLArray.asarray(arr, patch_size=list(patch_size))
     mla.save(out_path)
 
 
@@ -166,7 +165,7 @@ CONVERTERS = {
 }
 
 
-def _convert_one(src: Path, output_dir: Path, source_dir: Path, formats: list[str]) -> None:
+def _convert_one(src: Path, output_dir: Path, source_dir: Path, formats: list[str], patch_size: tuple) -> None:
     """Convert a single source file to all requested formats. Top-level for pickling."""
     arr = load_source_array(src)
     stem = flat_stem(src, source_dir)
@@ -175,7 +174,10 @@ def _convert_one(src: Path, output_dir: Path, source_dir: Path, formats: list[st
         out_path = output_dir / fmt / (stem + suffix)
         if out_path.exists():
             continue
-        converter(arr, out_path)
+        if fmt == "mlarray":
+            converter(arr, out_path, patch_size)
+        else:
+            converter(arr, out_path)
 
 
 def run_conversion(
@@ -184,11 +186,12 @@ def run_conversion(
     output_dir: Path,
     formats: list[str],
     num_workers: int,
+    patch_size: tuple,
 ) -> None:
     for fmt in formats:
         (output_dir / fmt).mkdir(parents=True, exist_ok=True)
 
-    fn = partial(_convert_one, output_dir=output_dir, source_dir=source_dir, formats=formats)
+    fn = partial(_convert_one, output_dir=output_dir, source_dir=source_dir, formats=formats, patch_size=patch_size)
     tqdmp(fn, source_files, num_workers, desc="  Converting")
 
 
@@ -257,10 +260,11 @@ READERS = {
 }
 
 
-def collect_files(output_dir: Path, fmt: str) -> list[Path]:
+def collect_files(output_dir: Path, fmt: str, stems: list[str]) -> list[Path]:
+    """Converted files of the selected source stems that exist on disk."""
     _, suffix = CONVERTERS[fmt]
     fmt_dir = output_dir / fmt
-    return sorted(fmt_dir.glob(f"*{suffix}"))
+    return [p for p in (fmt_dir / (stem + suffix) for stem in sorted(stems)) if p.exists()]
 
 
 def get_shape(filepath: Path, fmt: str) -> tuple:
@@ -295,9 +299,8 @@ def disk_size_mb(path: Path) -> float:
     return path.stat().st_size / 1e6
 
 
-def total_disk_mb(output_dir: Path, fmt: str) -> float:
-    fmt_dir = output_dir / fmt
-    return sum(disk_size_mb(p) for p in fmt_dir.iterdir())
+def total_disk_mb(files: list[Path]) -> float:
+    return sum(disk_size_mb(p) for p in files)
 
 
 def run_benchmark(
@@ -305,13 +308,14 @@ def run_benchmark(
     formats: list[str],
     n_reads: int,
     patch_size: tuple,
-    rng: random.Random,
+    stems: list[str],
+    seed: int,
 ) -> dict:
     results = {}
 
     for fmt in formats:
         reader = READERS[fmt]
-        files = collect_files(output_dir, fmt)
+        files = collect_files(output_dir, fmt, stems)
         if not files:
             print(f"  [{fmt}] No converted files found, skipping.")
             continue
@@ -320,8 +324,10 @@ def run_benchmark(
         file_shapes = [(f, get_shape(f, fmt)) for f in files]
         print("done")
 
+        # Fresh RNG per format so every format reads the same files/patches.
+        rng = random.Random(seed)
         times_ms = []
-        patch_bytes = None
+        bytes_read = 0
 
         with tqdm(total=n_reads, desc=f"  [{fmt}]", unit="read", leave=True, file=sys.stdout) as pbar:
             for _ in range(n_reads):
@@ -330,22 +336,20 @@ def run_benchmark(
                 starts = random_starts(shape, ep, rng)
                 sl = slices_for(starts, ep)
 
-                if patch_bytes is None:
-                    patch_bytes = math.prod(ep) * 4  # float32
-
                 t0 = time.perf_counter()
-                _ = reader(filepath, sl)
+                patch = reader(filepath, sl)
                 t1 = time.perf_counter()
                 times_ms.append((t1 - t0) * 1000.0)
+                bytes_read += patch.nbytes
                 pbar.update(1)
 
         times_arr = np.array(times_ms)
-        throughput_mbs = (patch_bytes / 1e6) / (np.mean(times_arr) / 1000.0)
+        throughput_mbs = (bytes_read / 1e6) / (np.sum(times_arr) / 1000.0)
 
         results[fmt] = {
             "n_reads": n_reads,
-            "patch_bytes": patch_bytes,
-            "disk_mb": round(total_disk_mb(output_dir, fmt), 2),
+            "patch_bytes": round(bytes_read / n_reads),  # mean bytes per read
+            "disk_mb": round(total_disk_mb(files), 2),
             "mean_ms": round(float(np.mean(times_arr)), 3),
             "median_ms": round(float(np.median(times_arr)), 3),
             "std_ms": round(float(np.std(times_arr)), 3),
@@ -446,7 +450,7 @@ def parse_args() -> argparse.Namespace:
     )
     parser.add_argument("--max_images", type=int, default=None, help="Maximum number of images to use. The full list is shuffled then sliced. Default: all images.")
     parser.add_argument("--skip_convert", action="store_true", help="Skip Stage 1 (conversion).")
-    parser.add_argument("--num_workers", type=int, default=12, help="Parallel workers for Stage 1 conversion. Default: all CPU cores.")
+    parser.add_argument("--num_workers", type=int, default=12, help="Parallel workers for Stage 1 conversion. Default: 12.")
     parser.add_argument("--seed", type=int, default=42, help="Random seed. Default: 42.")
     return parser.parse_args()
 
@@ -488,7 +492,7 @@ def main() -> None:
     # ------------------------------------------------------------------
     if not args.skip_convert:
         print("\n=== Stage 1: Converting ===")
-        run_conversion(source_files, source_dir, output_dir, args.formats, args.num_workers)
+        run_conversion(source_files, source_dir, output_dir, args.formats, args.num_workers, patch_size)
         print("Conversion complete.")
     else:
         print("\nStage 1 skipped (--skip_convert).")
@@ -500,7 +504,8 @@ def main() -> None:
     print(
         "Note: results reflect OS page cache state. Files will warm in cache during the run."
     )
-    results = run_benchmark(output_dir, args.formats, args.n_reads, patch_size, rng)
+    stems = [flat_stem(f, source_dir) for f in source_files]
+    results = run_benchmark(output_dir, args.formats, args.n_reads, patch_size, stems, args.seed)
 
     # ------------------------------------------------------------------
     # Results

mlarray-1.0.0/docs/api.md

@@ -0,0 +1,47 @@
+# API Reference
+
+## MLArray Module
+
+::: mlarray.mlarray.MLArray
+    options:
+      inherited_members: true
+
+::: mlarray.mlarray.set_read_ahead
+
+## Layout Module
+
+::: mlarray.blosc2_layout_strategies.comp_blosc2_params
+
+::: mlarray.blosc2_layout_strategies.select_blosc2_filter
+
+## Metadata Module
+
+::: mlarray.metadata.Meta
+
+::: mlarray.metadata.Axis
+
+::: mlarray.metadata.Space
+
+::: mlarray.metadata.SpaceAxis
+
+::: mlarray.metadata.FromArray
+
+::: mlarray.metadata.Values
+
+::: mlarray.metadata.Storage
+
+::: mlarray.metadata.SourceEntry
+
+::: mlarray.metadata.space_from_geometry
+
+::: mlarray.metadata.MetadataError
+
+## Fingerprint Module
+
+::: mlarray.fingerprint.compute
+
+::: mlarray.fingerprint.matches
+
+## Units Module
+
+::: mlarray.units.unit_code