vibframe-anndata 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. vibframe_anndata-0.1.0/.github/workflows/ci.yml +46 -0
  2. vibframe_anndata-0.1.0/.github/workflows/release-candidate.yml +104 -0
  3. vibframe_anndata-0.1.0/.github/workflows/release.yml +115 -0
  4. vibframe_anndata-0.1.0/.gitignore +35 -0
  5. vibframe_anndata-0.1.0/LICENSE +29 -0
  6. vibframe_anndata-0.1.0/PKG-INFO +136 -0
  7. vibframe_anndata-0.1.0/README.md +96 -0
  8. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/README.md +32 -0
  9. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/benchmark/metrics_common.py +33 -0
  10. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/benchmark/platform_utils.py +23 -0
  11. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/results/environment.json +24 -0
  12. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/results/numerical_error_max.csv +7 -0
  13. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/results/performance_summary.csv +13 -0
  14. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/src/metrics.c +35 -0
  15. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/src/metrics.h +13 -0
  16. vibframe_anndata-0.1.0/benchmarks/c_vs_numpy_v1_3/tests/validate_equivalence.py +100 -0
  17. vibframe_anndata-0.1.0/benchmarks/memory_scalability/180d_preflight.md +53 -0
  18. vibframe_anndata-0.1.0/benchmarks/memory_scalability/180d_ragged_preflight_float32.md +50 -0
  19. vibframe_anndata-0.1.0/benchmarks/memory_scalability/180d_streaming_features_float32.md +71 -0
  20. vibframe_anndata-0.1.0/benchmarks/memory_scalability/180d_streaming_float32.md +83 -0
  21. vibframe_anndata-0.1.0/benchmarks/memory_scalability/README.md +130 -0
  22. vibframe_anndata-0.1.0/benchmarks/memory_scalability/benchmark_ragged_vibframe.py +441 -0
  23. vibframe_anndata-0.1.0/benchmarks/memory_scalability/benchmark_streaming_features.py +170 -0
  24. vibframe_anndata-0.1.0/benchmarks/memory_scalability/benchmark_streaming_h5ad.py +185 -0
  25. vibframe_anndata-0.1.0/benchmarks/memory_scalability/benchmark_vibframe.py +622 -0
  26. vibframe_anndata-0.1.0/docs/ARCHITECTURE.md +146 -0
  27. vibframe_anndata-0.1.0/docs/BENCHMARK.md +82 -0
  28. vibframe_anndata-0.1.0/docs/CHANGELOG.md +75 -0
  29. vibframe_anndata-0.1.0/docs/CONFIGURATION.md +88 -0
  30. vibframe_anndata-0.1.0/docs/DATA_MODEL.md +162 -0
  31. vibframe_anndata-0.1.0/docs/DECISIONS.md +45 -0
  32. vibframe_anndata-0.1.0/docs/LIMITATIONS.md +92 -0
  33. vibframe_anndata-0.1.0/docs/METRICS.md +149 -0
  34. vibframe_anndata-0.1.0/docs/RELEASE.md +129 -0
  35. vibframe_anndata-0.1.0/docs/REQUIREMENTS.md +166 -0
  36. vibframe_anndata-0.1.0/docs/ROADMAP.md +38 -0
  37. vibframe_anndata-0.1.0/docs/TESTING.md +170 -0
  38. vibframe_anndata-0.1.0/docs/index.md +36 -0
  39. vibframe_anndata-0.1.0/examples/config.yaml +31 -0
  40. vibframe_anndata-0.1.0/examples/out_of_core_features.yaml +12 -0
  41. vibframe_anndata-0.1.0/examples/staged_workflow.py +11 -0
  42. vibframe_anndata-0.1.0/pyproject.toml +104 -0
  43. vibframe_anndata-0.1.0/src/vibframe_anndata/__init__.py +55 -0
  44. vibframe_anndata-0.1.0/src/vibframe_anndata/_version.py +14 -0
  45. vibframe_anndata-0.1.0/src/vibframe_anndata/adapter/__init__.py +13 -0
  46. vibframe_anndata-0.1.0/src/vibframe_anndata/adapter/base.py +62 -0
  47. vibframe_anndata-0.1.0/src/vibframe_anndata/adapter/catalog.py +38 -0
  48. vibframe_anndata-0.1.0/src/vibframe_anndata/adapter/parquet.py +393 -0
  49. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/__init__.py +26 -0
  50. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/feature_streaming.py +387 -0
  51. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/raw_access.py +154 -0
  52. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/raw_import.py +540 -0
  53. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/schema.py +107 -0
  54. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/serialization.py +65 -0
  55. vibframe_anndata-0.1.0/src/vibframe_anndata/anndata/streaming.py +646 -0
  56. vibframe_anndata-0.1.0/src/vibframe_anndata/api.py +213 -0
  57. vibframe_anndata-0.1.0/src/vibframe_anndata/config.py +203 -0
  58. vibframe_anndata-0.1.0/src/vibframe_anndata/exceptions.py +29 -0
  59. vibframe_anndata-0.1.0/src/vibframe_anndata/features/__init__.py +17 -0
  60. vibframe_anndata-0.1.0/src/vibframe_anndata/features/catalog.py +774 -0
  61. vibframe_anndata-0.1.0/src/vibframe_anndata/features/catalog_compute.py +344 -0
  62. vibframe_anndata-0.1.0/src/vibframe_anndata/features/manager.py +290 -0
  63. vibframe_anndata-0.1.0/src/vibframe_anndata/features/params/__init__.py +3 -0
  64. vibframe_anndata-0.1.0/src/vibframe_anndata/features/params/basic.py +124 -0
  65. vibframe_anndata-0.1.0/src/vibframe_anndata/features/reference.py +378 -0
  66. vibframe_anndata-0.1.0/src/vibframe_anndata/features/registry.py +69 -0
  67. vibframe_anndata-0.1.0/src/vibframe_anndata/features/service.py +161 -0
  68. vibframe_anndata-0.1.0/tests/fixtures/README.md +34 -0
  69. vibframe_anndata-0.1.0/tests/test_catalog_frequency_resolution.py +123 -0
  70. vibframe_anndata-0.1.0/tests/test_feature_lifecycle.py +84 -0
  71. vibframe_anndata-0.1.0/tests/test_feature_streaming.py +194 -0
  72. vibframe_anndata-0.1.0/tests/test_ingestion.py +166 -0
  73. vibframe_anndata-0.1.0/tests/test_reference_kernels.py +29 -0
  74. vibframe_anndata-0.1.0/tests/test_reference_vibframe.py +300 -0
  75. vibframe_anndata-0.1.0/tests/test_streaming_h5ad.py +147 -0
  76. vibframe_anndata-0.1.0/tools/build_ci_reference_fixture.py +422 -0
  77. vibframe_anndata-0.1.0/tools/check_release_tag.py +46 -0
@@ -0,0 +1,46 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ concurrency:
12
+ group: ci-${{ github.workflow }}-${{ github.ref }}
13
+ cancel-in-progress: true
14
+
15
+ jobs:
16
+ quality-and-tests:
17
+ runs-on: [self-hosted, linux, x64, homelab-ci]
18
+ timeout-minutes: 30
19
+ strategy:
20
+ fail-fast: false
21
+ matrix:
22
+ python-version: ["3.10", "3.12"]
23
+
24
+ steps:
25
+ - uses: actions/checkout@v4
26
+
27
+ - uses: astral-sh/setup-uv@v6
28
+ with:
29
+ enable-cache: true
30
+ cache-dependency-glob: pyproject.toml
31
+
32
+ - name: Run quality and tests on Python ${{ matrix.python-version }}
33
+ env:
34
+ PYTHON_VERSION: ${{ matrix.python-version }}
35
+ run: |
36
+ set -euo pipefail
37
+ uv python install "$PYTHON_VERSION"
38
+ rm -rf .venv-ci
39
+ uv venv --python "$PYTHON_VERSION" .venv-ci
40
+ uv pip install --python .venv-ci/bin/python -e ".[dev]"
41
+
42
+ .venv-ci/bin/python tools/build_ci_reference_fixture.py
43
+ .venv-ci/bin/ruff check .
44
+ .venv-ci/bin/pylint src/vibframe_anndata --fail-under=8.0
45
+ .venv-ci/bin/pytest -m "not reference" --cov=vibframe_anndata --cov-report=term-missing
46
+ .venv-ci/bin/pytest tests/test_reference_vibframe.py -m reference -vv
@@ -0,0 +1,104 @@
1
+ name: Release candidate
2
+
3
+ on:
4
+ workflow_dispatch:
5
+ push:
6
+ branches:
7
+ - release/0.1.0
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ concurrency:
13
+ group: release-candidate-${{ github.ref }}
14
+ cancel-in-progress: true
15
+
16
+ jobs:
17
+ validate:
18
+ runs-on: [self-hosted, linux, x64, homelab-ci]
19
+ timeout-minutes: 30
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ python-version: ["3.10", "3.12"]
24
+
25
+ steps:
26
+ - uses: actions/checkout@v4
27
+
28
+ - uses: astral-sh/setup-uv@v6
29
+ with:
30
+ enable-cache: true
31
+ cache-dependency-glob: pyproject.toml
32
+
33
+ - name: Validate candidate on Python ${{ matrix.python-version }}
34
+ env:
35
+ PYTHON_VERSION: ${{ matrix.python-version }}
36
+ run: |
37
+ set -euo pipefail
38
+ uv python install "$PYTHON_VERSION"
39
+ VENV="$RUNNER_TEMP/vfta-rc-${PYTHON_VERSION//./-}"
40
+ rm -rf "$VENV"
41
+ uv venv --python "$PYTHON_VERSION" "$VENV"
42
+ uv pip install --python "$VENV/bin/python" -e ".[dev,release]"
43
+
44
+ "$VENV/bin/python" tools/build_ci_reference_fixture.py
45
+ "$VENV/bin/python" tools/check_release_tag.py v0.1.0
46
+ "$VENV/bin/ruff" check .
47
+ "$VENV/bin/pylint" src/vibframe_anndata --fail-under=8.0
48
+ "$VENV/bin/pytest" -m "not reference" --cov=vibframe_anndata --cov-report=term-missing
49
+ "$VENV/bin/pytest" tests/test_reference_vibframe.py -m reference -vv
50
+
51
+ build:
52
+ needs: validate
53
+ runs-on: [self-hosted, linux, x64, homelab-ci]
54
+ timeout-minutes: 20
55
+
56
+ steps:
57
+ - uses: actions/checkout@v4
58
+
59
+ - uses: astral-sh/setup-uv@v6
60
+ with:
61
+ enable-cache: true
62
+ cache-dependency-glob: pyproject.toml
63
+
64
+ - name: Build and validate distributions
65
+ run: |
66
+ set -euo pipefail
67
+ uv python install 3.12
68
+ VENV="$RUNNER_TEMP/vfta-build"
69
+ rm -rf "$VENV" dist build
70
+ uv venv --python 3.12 "$VENV"
71
+ uv pip install --python "$VENV/bin/python" "build>=1.2,<2" "twine>=7,<8"
72
+ "$VENV/bin/python" tools/check_release_tag.py v0.1.0
73
+ "$VENV/bin/python" -m build
74
+ "$VENV/bin/python" -m twine check dist/*
75
+
76
+ - name: Upload candidate distributions
77
+ uses: actions/upload-artifact@v4
78
+ with:
79
+ name: vibframe-anndata-0.1.0-candidate
80
+ path: dist/
81
+ if-no-files-found: error
82
+
83
+ smoke-install:
84
+ needs: build
85
+ runs-on: [self-hosted, linux, x64, homelab-ci]
86
+ timeout-minutes: 15
87
+
88
+ steps:
89
+ - uses: actions/download-artifact@v4
90
+ with:
91
+ name: vibframe-anndata-0.1.0-candidate
92
+ path: dist/
93
+
94
+ - uses: astral-sh/setup-uv@v6
95
+
96
+ - name: Install wheel and import public API
97
+ run: |
98
+ set -euo pipefail
99
+ uv python install 3.12
100
+ VENV="$RUNNER_TEMP/vfta-smoke"
101
+ rm -rf "$VENV"
102
+ uv venv --python 3.12 "$VENV"
103
+ uv pip install --python "$VENV/bin/python" dist/*.whl
104
+ "$VENV/bin/python" -c "import vibframe_anndata as vfta; assert vfta.__version__ == '0.1.0', vfta.__version__; assert callable(vfta.import_raw); assert callable(vfta.import_raw_to_h5ad); assert callable(vfta.add_features); assert callable(vfta.add_features_to_h5ad); assert callable(vfta.recalculate_features_to_h5ad); assert callable(vfta.remove_features_from_h5ad); print('release-candidate wheel smoke test passed')"
@@ -0,0 +1,115 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*.*.*"
7
+
8
+ permissions:
9
+ contents: read
10
+
11
+ jobs:
12
+ test:
13
+ runs-on: [self-hosted, linux, x64, homelab-ci]
14
+ timeout-minutes: 30
15
+ strategy:
16
+ fail-fast: false
17
+ matrix:
18
+ python-version: ["3.10", "3.12"]
19
+
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+
23
+ - uses: astral-sh/setup-uv@v6
24
+ with:
25
+ enable-cache: true
26
+ cache-dependency-glob: pyproject.toml
27
+
28
+ - name: Test release on Python ${{ matrix.python-version }}
29
+ env:
30
+ PYTHON_VERSION: ${{ matrix.python-version }}
31
+ RELEASE_TAG: ${{ github.ref_name }}
32
+ run: |
33
+ set -euo pipefail
34
+ uv python install "$PYTHON_VERSION"
35
+ VENV="$RUNNER_TEMP/vfta-release-test-${PYTHON_VERSION//./-}"
36
+ rm -rf "$VENV"
37
+ uv venv --python "$PYTHON_VERSION" "$VENV"
38
+ uv pip install --python "$VENV/bin/python" -e ".[dev,release]"
39
+
40
+ "$VENV/bin/python" tools/build_ci_reference_fixture.py
41
+ "$VENV/bin/python" tools/check_release_tag.py "$RELEASE_TAG"
42
+ "$VENV/bin/ruff" check .
43
+ "$VENV/bin/pylint" src/vibframe_anndata --fail-under=8.0
44
+ "$VENV/bin/pytest" -m "not reference" --cov=vibframe_anndata --cov-report=term-missing
45
+ "$VENV/bin/pytest" tests/test_reference_vibframe.py -m reference -vv
46
+
47
+ build:
48
+ needs: test
49
+ runs-on: [self-hosted, linux, x64, homelab-ci]
50
+ timeout-minutes: 20
51
+
52
+ steps:
53
+ - uses: actions/checkout@v4
54
+
55
+ - uses: astral-sh/setup-uv@v6
56
+ with:
57
+ enable-cache: true
58
+ cache-dependency-glob: pyproject.toml
59
+
60
+ - name: Build and validate distributions
61
+ env:
62
+ RELEASE_TAG: ${{ github.ref_name }}
63
+ run: |
64
+ set -euo pipefail
65
+ uv python install 3.12
66
+ VENV="$RUNNER_TEMP/vfta-release-build"
67
+ rm -rf "$VENV" dist build
68
+ uv venv --python 3.12 "$VENV"
69
+ uv pip install --python "$VENV/bin/python" "build>=1.2,<2" "twine>=7,<8"
70
+ "$VENV/bin/python" tools/check_release_tag.py "$RELEASE_TAG"
71
+ "$VENV/bin/python" -m build
72
+ "$VENV/bin/python" -m twine check dist/*
73
+
74
+ - name: Upload distributions
75
+ uses: actions/upload-artifact@v4
76
+ with:
77
+ name: python-distributions
78
+ path: dist/
79
+ if-no-files-found: error
80
+
81
+ publish-pypi:
82
+ needs: build
83
+ runs-on: ubuntu-latest
84
+ environment:
85
+ name: pypi
86
+ url: https://pypi.org/p/vibframe-anndata
87
+ permissions:
88
+ id-token: write
89
+ contents: read
90
+
91
+ steps:
92
+ - name: Download distributions
93
+ uses: actions/download-artifact@v4
94
+ with:
95
+ name: python-distributions
96
+ path: dist/
97
+ - name: Publish to PyPI
98
+ uses: pypa/gh-action-pypi-publish@release/v1
99
+
100
+ github-release:
101
+ needs: publish-pypi
102
+ runs-on: ubuntu-latest
103
+ permissions:
104
+ contents: write
105
+
106
+ steps:
107
+ - name: Download distributions
108
+ uses: actions/download-artifact@v4
109
+ with:
110
+ name: python-distributions
111
+ path: dist/
112
+ - name: Create GitHub release
113
+ env:
114
+ GH_TOKEN: ${{ github.token }}
115
+ run: gh release create "${GITHUB_REF_NAME}" dist/* --generate-notes --verify-tag
@@ -0,0 +1,35 @@
1
+ # Project data: intentionally non-versioned
2
+ /data/
3
+
4
+ # Python
5
+ __pycache__/
6
+ *.py[cod]
7
+ *.egg-info/
8
+ .pytest_cache/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ .coverage
12
+ htmlcov/
13
+ dist/
14
+ build/
15
+ .venv/
16
+ venv/
17
+
18
+ # Generated AnnData / local outputs
19
+ *.h5ad
20
+
21
+ # Benchmark generated/downloaded artefacts
22
+ benchmarks/**/synthetic_data/
23
+ benchmarks/**/third_party/
24
+ benchmarks/**/results.zip
25
+ benchmarks/memory_scalability/results/
26
+
27
+ # IDE / OS
28
+ .DS_Store
29
+ .idea/
30
+ .vscode/
31
+
32
+ # Secrets / local configuration
33
+ .env
34
+ .env.*
35
+ !.env.example
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Alejandro González Zapico
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,136 @@
1
+ Metadata-Version: 2.5
2
+ Name: vibframe-anndata
3
+ Version: 0.1.0
4
+ Summary: Reproducible VibFrame ingestion and incremental AnnData feature engineering.
5
+ Project-URL: Source, https://github.com/413hq/VibFrame_To_Anndata
6
+ Project-URL: Issues, https://github.com/413hq/VibFrame_To_Anndata/issues
7
+ Author: Alejandro González Zapico
8
+ License-Expression: BSD-3-Clause
9
+ License-File: LICENSE
10
+ Keywords: anndata,condition-monitoring,machine-learning,signal-processing,vibration
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: License :: OSI Approved :: BSD License
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Scientific/Engineering
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: anndata<0.13,>=0.10
23
+ Requires-Dist: awkward<3,>=2.5
24
+ Requires-Dist: numpy<3,>=1.26
25
+ Requires-Dist: pandas<3,>=2.0
26
+ Requires-Dist: pyarrow<26,>=14
27
+ Requires-Dist: pyyaml<7,>=6
28
+ Requires-Dist: scipy<2,>=1.11
29
+ Provides-Extra: dev
30
+ Requires-Dist: psutil<8,>=6; extra == 'dev'
31
+ Requires-Dist: pylint<4,>=3.2; extra == 'dev'
32
+ Requires-Dist: pytest-cov<7,>=5; extra == 'dev'
33
+ Requires-Dist: pytest<9,>=8; extra == 'dev'
34
+ Requires-Dist: ruff<1,>=0.6; extra == 'dev'
35
+ Provides-Extra: release
36
+ Requires-Dist: build<2,>=1.2; extra == 'release'
37
+ Requires-Dist: tomli<3,>=2; (python_version < '3.11') and extra == 'release'
38
+ Requires-Dist: twine<8,>=7; extra == 'release'
39
+ Description-Content-Type: text/markdown
40
+
41
+ # VibFrame to AnnData
42
+
43
+ Python package for staged conversion of TWave VibFrame data into reusable `AnnData` datasets.
44
+
45
+ The workflow is intentionally split in two phases:
46
+
47
+ 1. **Ingest raw VibFrame data once** into an AnnData base (`obs`, `obsm`, `uns`).
48
+ 2. **Add, recalculate or remove features** from the raw signals already stored in AnnData, without reopening the original VibFrame.
49
+
50
+ For datasets that fit comfortably in memory:
51
+
52
+ ```python
53
+ from vibframe_anndata import add_features, import_raw, remove_features, write_h5ad
54
+
55
+ adata = import_raw("dataset.vibframe.zip")
56
+ write_h5ad(adata, "dataset_raw.h5ad")
57
+
58
+ adata = add_features(
59
+ adata,
60
+ {
61
+ "version": 1,
62
+ "features": [
63
+ {"name": "rms", "source": "waveform"},
64
+ {"name": "kurtosis", "source": "waveform"},
65
+ ],
66
+ },
67
+ )
68
+
69
+ adata = remove_features(adata, ["kurtosis"])
70
+ write_h5ad(adata, "dataset_features.h5ad")
71
+ ```
72
+
73
+ For datasets larger than RAM, use the blockwise H5AD APIs:
74
+
75
+ ```python
76
+ from vibframe_anndata import import_raw_to_h5ad, add_features_to_h5ad
77
+
78
+ base = import_raw_to_h5ad(
79
+ "dataset.vibframe.zip",
80
+ "dataset_raw.h5ad",
81
+ config={
82
+ "version": 1,
83
+ "raw_import": {"on_missing_signal": "nan"},
84
+ "output": {"dtype": "float32"},
85
+ },
86
+ block_size_mib=8,
87
+ )
88
+
89
+ add_features_to_h5ad(
90
+ base,
91
+ {
92
+ "version": 1,
93
+ "output": {"dtype": "float32"},
94
+ "feature_policy": {"on_error": "nan"},
95
+ "features": [{"name": "rms", "source": "waveform"}],
96
+ },
97
+ output="dataset_features.h5ad",
98
+ block_rows=256,
99
+ )
100
+ ```
101
+
102
+ The large-file path is transactional: raw samples are read in observation blocks and the destination is replaced only after all feature blocks succeed.
103
+
104
+ Install from PyPI after the first release:
105
+
106
+ ```bash
107
+ python -m pip install vibframe-anndata
108
+ ```
109
+
110
+ Install for development:
111
+
112
+ ```bash
113
+ python -m pip install -e ".[dev]"
114
+ ```
115
+
116
+ The repository intentionally does **not** version the project `data/` directory. The mandatory CI fixture is generated deterministically from versioned synthetic source.
117
+
118
+ ## License
119
+
120
+ The software package is released under the **BSD 3-Clause License**, allowing academic and research users to inspect, modify and redistribute the code while retaining the copyright and license notices.
121
+
122
+ The BSD license applies to the software source code distributed by this project. External or reference datasets, VibFrame captures and other third-party material are **not** relicensed by this repository unless explicitly stated. Release archives exclude VibFrame reference binaries and the local `data/` tree.
123
+
124
+ ## Documentation
125
+
126
+ - [Documentation index](docs/index.md)
127
+ - [Architecture](docs/ARCHITECTURE.md)
128
+ - [AnnData data contract](docs/DATA_MODEL.md)
129
+ - [Configuration](docs/CONFIGURATION.md)
130
+ - [Metric support](docs/METRICS.md)
131
+ - [Testing and CI](docs/TESTING.md)
132
+ - [Known limitations](docs/LIMITATIONS.md)
133
+ - [Requirements compliance](docs/REQUIREMENTS.md)
134
+ - [0.1.0 release procedure](docs/RELEASE.md)
135
+ - [Roadmap / 0.2.0 debt](docs/ROADMAP.md)
136
+ - [Changelog](docs/CHANGELOG.md)
@@ -0,0 +1,96 @@
1
+ # VibFrame to AnnData
2
+
3
+ Python package for staged conversion of TWave VibFrame data into reusable `AnnData` datasets.
4
+
5
+ The workflow is intentionally split in two phases:
6
+
7
+ 1. **Ingest raw VibFrame data once** into an AnnData base (`obs`, `obsm`, `uns`).
8
+ 2. **Add, recalculate or remove features** from the raw signals already stored in AnnData, without reopening the original VibFrame.
9
+
10
+ For datasets that fit comfortably in memory:
11
+
12
+ ```python
13
+ from vibframe_anndata import add_features, import_raw, remove_features, write_h5ad
14
+
15
+ adata = import_raw("dataset.vibframe.zip")
16
+ write_h5ad(adata, "dataset_raw.h5ad")
17
+
18
+ adata = add_features(
19
+ adata,
20
+ {
21
+ "version": 1,
22
+ "features": [
23
+ {"name": "rms", "source": "waveform"},
24
+ {"name": "kurtosis", "source": "waveform"},
25
+ ],
26
+ },
27
+ )
28
+
29
+ adata = remove_features(adata, ["kurtosis"])
30
+ write_h5ad(adata, "dataset_features.h5ad")
31
+ ```
32
+
33
+ For datasets larger than RAM, use the blockwise H5AD APIs:
34
+
35
+ ```python
36
+ from vibframe_anndata import import_raw_to_h5ad, add_features_to_h5ad
37
+
38
+ base = import_raw_to_h5ad(
39
+ "dataset.vibframe.zip",
40
+ "dataset_raw.h5ad",
41
+ config={
42
+ "version": 1,
43
+ "raw_import": {"on_missing_signal": "nan"},
44
+ "output": {"dtype": "float32"},
45
+ },
46
+ block_size_mib=8,
47
+ )
48
+
49
+ add_features_to_h5ad(
50
+ base,
51
+ {
52
+ "version": 1,
53
+ "output": {"dtype": "float32"},
54
+ "feature_policy": {"on_error": "nan"},
55
+ "features": [{"name": "rms", "source": "waveform"}],
56
+ },
57
+ output="dataset_features.h5ad",
58
+ block_rows=256,
59
+ )
60
+ ```
61
+
62
+ The large-file path is transactional: raw samples are read in observation blocks and the destination is replaced only after all feature blocks succeed.
63
+
64
+ Install from PyPI after the first release:
65
+
66
+ ```bash
67
+ python -m pip install vibframe-anndata
68
+ ```
69
+
70
+ Install for development:
71
+
72
+ ```bash
73
+ python -m pip install -e ".[dev]"
74
+ ```
75
+
76
+ The repository intentionally does **not** version the project `data/` directory. The mandatory CI fixture is generated deterministically from versioned synthetic source.
77
+
78
+ ## License
79
+
80
+ The software package is released under the **BSD 3-Clause License**, allowing academic and research users to inspect, modify and redistribute the code while retaining the copyright and license notices.
81
+
82
+ The BSD license applies to the software source code distributed by this project. External or reference datasets, VibFrame captures and other third-party material are **not** relicensed by this repository unless explicitly stated. Release archives exclude VibFrame reference binaries and the local `data/` tree.
83
+
84
+ ## Documentation
85
+
86
+ - [Documentation index](docs/index.md)
87
+ - [Architecture](docs/ARCHITECTURE.md)
88
+ - [AnnData data contract](docs/DATA_MODEL.md)
89
+ - [Configuration](docs/CONFIGURATION.md)
90
+ - [Metric support](docs/METRICS.md)
91
+ - [Testing and CI](docs/TESTING.md)
92
+ - [Known limitations](docs/LIMITATIONS.md)
93
+ - [Requirements compliance](docs/REQUIREMENTS.md)
94
+ - [0.1.0 release procedure](docs/RELEASE.md)
95
+ - [Roadmap / 0.2.0 debt](docs/ROADMAP.md)
96
+ - [Changelog](docs/CHANGELOG.md)
@@ -0,0 +1,32 @@
1
+ # C vs NumPy benchmark — v1.3 evidence snapshot
2
+
3
+ This directory contains the repository evidence extracted from the project benchmark archive supplied on 2026-09-10.
4
+
5
+ Original archive:
6
+
7
+ - filename: `vibframe_c_vs_numpy_benchmark_v1_3.zip`
8
+ - size: `73643220` bytes
9
+ - SHA-256: `fc815489034d5964841bedbd3cffd7308a34b651be7f9fc4ee0794130774fe3f`
10
+
11
+ The supplied archive also bundles compiled macOS artefacts and downloaded DuckDB binaries. Those third-party/generated binaries are deliberately not copied into this repository.
12
+
13
+ ## Preserved here
14
+
15
+ The repository keeps the pieces required to audit the decision without vendoring large binaries:
16
+
17
+ - the exact C implementation of the six benchmark statistics;
18
+ - the corresponding NumPy implementation;
19
+ - the exact C/NumPy equivalence smoke test;
20
+ - the captured benchmark environment;
21
+ - a compact performance table covering every recorded scenario;
22
+ - maximum numerical error by metric.
23
+
24
+ The complete methodology and interpretation are documented in [`docs/BENCHMARK.md`](../../docs/BENCHMARK.md).
25
+
26
+ ## Scope
27
+
28
+ The benchmark metrics are:
29
+
30
+ `peak_positive`, `peak_negative`, `p2p`, `rms`, `crest_factor`, and `kurtosis`.
31
+
32
+ This benchmark is evidence for the NumPy-vs-C implementation decision. It is separate from the catalog-level T8/VibFrame regression against `trends.parquet`.
@@ -0,0 +1,33 @@
1
+ from __future__ import annotations
2
+ import numpy as np
3
+
4
+ METRIC_NAMES = (
5
+ "peak_positive",
6
+ "peak_negative",
7
+ "p2p",
8
+ "rms",
9
+ "crest_factor",
10
+ "kurtosis",
11
+ )
12
+
13
+
14
+ def compute_numpy(x: np.ndarray) -> np.ndarray:
15
+ peak_pos = float(np.max(x))
16
+ peak_neg = float(np.min(x))
17
+ rms = float(np.sqrt(np.mean(x * x)))
18
+ mean = float(np.mean(x))
19
+ centered = x - mean
20
+ m2 = float(np.mean(centered * centered))
21
+ m4 = float(np.mean((centered * centered) ** 2))
22
+ peak_abs = max(abs(peak_pos), abs(peak_neg))
23
+ return np.array(
24
+ [
25
+ peak_pos,
26
+ peak_neg,
27
+ peak_pos - peak_neg,
28
+ rms,
29
+ peak_abs / rms if rms > 0.0 else 0.0,
30
+ m4 / (m2 * m2) if m2 > 0.0 else 0.0,
31
+ ],
32
+ dtype=np.float64,
33
+ )
@@ -0,0 +1,23 @@
1
+ from __future__ import annotations
2
+ import platform
3
+ import resource
4
+ from pathlib import Path
5
+
6
+
7
+ def shared_library_name() -> str:
8
+ return "libvibmetrics.dylib" if platform.system() == "Darwin" else "libvibmetrics.so"
9
+
10
+
11
+ def shared_library_path(root: Path) -> Path:
12
+ return root / "build" / shared_library_name()
13
+
14
+
15
+ def peak_rss_kib() -> int:
16
+ """Return ru_maxrss normalized to KiB on Linux and macOS.
17
+
18
+ Linux reports ru_maxrss in KiB; macOS reports bytes.
19
+ """
20
+ rss = int(resource.getrusage(resource.RUSAGE_SELF).ru_maxrss)
21
+ if platform.system() == "Darwin":
22
+ rss //= 1024
23
+ return rss
@@ -0,0 +1,24 @@
1
+ {
2
+ "created_at": "2026-09-04T12:40:11+0200",
3
+ "platform": "macOS-26.6.2-arm64-arm-64bit",
4
+ "machine": "arm64",
5
+ "python": "3.9.6 (default, Apr 7 2026, 02:38:40) \n[Clang 21.0.0 (clang-2100.0.123.102)]",
6
+ "numpy": "2.0.2",
7
+ "pyarrow": "21.0.0",
8
+ "duckdb_c_api": "1.5.5",
9
+ "cpu_count_logical": 6,
10
+ "trials": 4,
11
+ "repeats": 1,
12
+ "compression": "snappy",
13
+ "scale_sizes_payload_mib": [
14
+ 4,
15
+ 16,
16
+ 64,
17
+ 256,
18
+ 512,
19
+ 1024,
20
+ 2048
21
+ ],
22
+ "native_enabled": true,
23
+ "note": "target_mib is decoded float64 payload; physical Parquet size is recorded separately"
24
+ }
@@ -0,0 +1,7 @@
1
+ metric,max_abs_error,max_rel_error,max_mean_abs_error,max_rmse
2
+ crest_factor,1.5276668818842157e-13,1.9091554498552136e-14,4.4117487441042164e-14,5.3173192662063305e-14
3
+ kurtosis,3.312905505481467e-13,9.622538579227361e-14,9.02333763264096e-14,1.0694208517255857e-13
4
+ p2p,0.0,0.0,0.0,0.0
5
+ peak_negative,0.0,0.0,0.0,0.0
6
+ peak_positive,0.0,0.0,0.0,0.0
7
+ rms,1.63202784619898e-14,1.916619150647869e-14,5.009881398621019e-15,6.0817020147297566e-15