eosframes 1.1.0__tar.gz

eosframes-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ersilia Open Source Initiative
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eosframes-1.1.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: eosframes
+Version: 1.1.0
+Summary: Ersilia utilities for working with tabular output data
+License: MIT
+License-File: LICENSE
+Keywords: ersilia,cheminformatics,data,machine-learning
+Author: Ersilia Open Source Initiative
+Author-email: hello@ersilia.io
+Requires-Python: >=3.8
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Dist: click (>=8.0)
+Requires-Dist: h5py (>=3.10.0)
+Requires-Dist: numpy (>=1.24.0)
+Requires-Dist: pandas (>=2.0.0)
+Requires-Dist: requests (>=2.31)
+Requires-Dist: rich (>=10.0)
+Project-URL: Homepage, https://github.com/ersilia-os/eosframes
+Project-URL: Repository, https://github.com/ersilia-os/eosframes
+Description-Content-Type: text/markdown
+
+![Work in Progress](https://img.shields.io/badge/status-work%20in%20progress-orange)
+
+# Manipulating Ersilia's dataframes
+
+`eosframes` is a library for manipulating inputs and outputs from the [Ersilia Model Hub](https://github.com/ersilia-os/ersilia). It splits, assembles, converts, scales, and summarises tabular model output files.
+
+## Installation
+
+Python ≥ 3.8 is required.
+
+```bash
+pip install eosframes
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/ersilia-os/eosframes.git
+cd eosframes
+pip install -e .
+```
+
+## Quick start
+
+Every file the library reads or writes encodes a model ID and version in its filename, e.g. `eos4e40_v1.csv` (model `eos4e40`, version `v1`).
+
+```bash
+# Slice a big input CSV into chunks for parallel model runs
+eosframes split compounds.csv -o chunks/ --chunksize 10000
+
+# Stitch the per-batch outputs back into one file
+eosframes append eos4e40_v1_000.csv eos4e40_v1_001.csv -o eos4e40_v1.csv
+
+# Combine outputs from multiple models, side by side
+eosframes stack eos4e40_v1.csv eos7m30_v1.csv -o project_eosmix.csv
+```
+
+Everything the CLI does is also importable:
+
+```python
+from eosframes import read_csv, hstack, fit, transform
+
+df = read_csv("eos4e40_v1.csv")
+params = fit(df)
+scaled = transform(df, params)
+```
+
+Run `eosframes --help` (or `eosframes <command> --help`) for inline help.
+
+## Commands
+
+| Command     | Purpose                                                       |
+|-------------|---------------------------------------------------------------|
+| `split`     | Slice any CSV into chunk files for parallel model runs.       |
+| `convert`   | CSV ↔ H5, or assemble a chunks folder.                        |
+| `append`    | Vertically concatenate batches from the same model.           |
+| `dedupe`    | Drop duplicate rows by `key`.                                 |
+| `stack`     | Horizontally combine outputs from different models.           |
+| `unstack`   | Split a stacked file back into per-model files.               |
+| `summary`   | Per-feature stats from a local file.                          |
+| `info`      | Model metadata fetched from GitHub.                           |
+| `columns`   | Feature definitions fetched from GitHub.                      |
+| `fit`       | Fit a type-aware robust scaler and save its parameters.       |
+| `transform` | Apply a saved scaler to a file.                               |
+
+See [`docs/cli.md`](docs/cli.md) for every flag, example, and refusal condition.
+
+## Documentation
+
+- [`docs/cli.md`](docs/cli.md) — every CLI command, all flags, examples, and error patterns.
+- [`docs/nomenclature.md`](docs/nomenclature.md) — every recognised filename / directory pattern, the strict/lenient contract, and the two stack modes.
+- [`docs/scaling.md`](docs/scaling.md) — the type-aware robust scaler: column kinds, how each is picked, and quantization / imputation.
+
+## About the Ersilia Open Source Initiative
+
+The [Ersilia Open Source Initiative](https://ersilia.io) is a tech-nonprofit fueling sustainable research in the Global South. Ersilia's main asset is the [Ersilia Model Hub](https://github.com/ersilia-os/ersilia), an open-source repository of AI/ML models for drug discovery.
+
+![Ersilia Logo](assets/Ersilia_Brand.png)
+

eosframes-1.1.0/README.md

@@ -0,0 +1,78 @@
+![Work in Progress](https://img.shields.io/badge/status-work%20in%20progress-orange)
+
+# Manipulating Ersilia's dataframes
+
+`eosframes` is a library for manipulating inputs and outputs from the [Ersilia Model Hub](https://github.com/ersilia-os/ersilia). It splits, assembles, converts, scales, and summarises tabular model output files.
+
+## Installation
+
+Python ≥ 3.8 is required.
+
+```bash
+pip install eosframes
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/ersilia-os/eosframes.git
+cd eosframes
+pip install -e .
+```
+
+## Quick start
+
+Every file the library reads or writes encodes a model ID and version in its filename, e.g. `eos4e40_v1.csv` (model `eos4e40`, version `v1`).
+
+```bash
+# Slice a big input CSV into chunks for parallel model runs
+eosframes split compounds.csv -o chunks/ --chunksize 10000
+
+# Stitch the per-batch outputs back into one file
+eosframes append eos4e40_v1_000.csv eos4e40_v1_001.csv -o eos4e40_v1.csv
+
+# Combine outputs from multiple models, side by side
+eosframes stack eos4e40_v1.csv eos7m30_v1.csv -o project_eosmix.csv
+```
+
+Everything the CLI does is also importable:
+
+```python
+from eosframes import read_csv, hstack, fit, transform
+
+df = read_csv("eos4e40_v1.csv")
+params = fit(df)
+scaled = transform(df, params)
+```
+
+Run `eosframes --help` (or `eosframes <command> --help`) for inline help.
+
+## Commands
+
+| Command     | Purpose                                                       |
+|-------------|---------------------------------------------------------------|
+| `split`     | Slice any CSV into chunk files for parallel model runs.       |
+| `convert`   | CSV ↔ H5, or assemble a chunks folder.                        |
+| `append`    | Vertically concatenate batches from the same model.           |
+| `dedupe`    | Drop duplicate rows by `key`.                                 |
+| `stack`     | Horizontally combine outputs from different models.           |
+| `unstack`   | Split a stacked file back into per-model files.               |
+| `summary`   | Per-feature stats from a local file.                          |
+| `info`      | Model metadata fetched from GitHub.                           |
+| `columns`   | Feature definitions fetched from GitHub.                      |
+| `fit`       | Fit a type-aware robust scaler and save its parameters.       |
+| `transform` | Apply a saved scaler to a file.                               |
+
+See [`docs/cli.md`](docs/cli.md) for every flag, example, and refusal condition.
+
+## Documentation
+
+- [`docs/cli.md`](docs/cli.md) — every CLI command, all flags, examples, and error patterns.
+- [`docs/nomenclature.md`](docs/nomenclature.md) — every recognised filename / directory pattern, the strict/lenient contract, and the two stack modes.
+- [`docs/scaling.md`](docs/scaling.md) — the type-aware robust scaler: column kinds, how each is picked, and quantization / imputation.
+
+## About the Ersilia Open Source Initiative
+
+The [Ersilia Open Source Initiative](https://ersilia.io) is a tech-nonprofit fueling sustainable research in the Global South. Ersilia's main asset is the [Ersilia Model Hub](https://github.com/ersilia-os/ersilia), an open-source repository of AI/ML models for drug discovery.
+
+![Ersilia Logo](assets/Ersilia_Brand.png)

eosframes-1.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+style = "pep440"
+
+[tool.poetry]
+name = "eosframes"
+version = "1.1.0"
+description = "Ersilia utilities for working with tabular output data"
+authors = ["Ersilia Open Source Initiative <hello@ersilia.io>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/ersilia-os/eosframes"
+repository = "https://github.com/ersilia-os/eosframes"
+keywords = ["ersilia", "cheminformatics", "data", "machine-learning"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+packages = [{include = "eosframes", from = "src"}]
+
+[tool.poetry.dependencies]
+python = ">=3.8"
+pandas = ">=2.0.0"
+numpy = ">=1.24.0"
+h5py = ">=3.10.0"
+requests = ">=2.31"
+click = ">=8.0"
+rich = ">=10.0"
+
+[tool.poetry.group.dev.dependencies]
+ruff = ">=0.4,<1"
+pytest = ">=7.0"
+
+[tool.poetry.scripts]
+eosframes = "eosframes.cli:main"
+
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "D"]
+ignore = [
+    "E501",   # line too long — handled by formatter
+    "B008",   # do not perform function calls in default arguments (Click uses this)
+    "UP007",  # use X | Y for type annotations (not available in 3.8)
+    "UP006",  # use type instead of Type (not available in 3.8)
+    "D203",   # conflicts with D211 (no blank line before class docstring)
+    "D213",   # conflicts with D212 (summary on first line)
+    "D301",   # backslashes — Click uses \b in help text, raw-strings hurt readability
+    "D401",   # imperative mood — too opinionated for descriptive docstrings
+    "D403",   # first-word capitalisation — the brand "eosframes" stays lowercase
+    "D415",   # first line ends with punctuation — D400 already covers periods
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests document themselves via descriptive names; don't require docstrings.
+"tests/*" = ["D"]
+# Subpackage __init__.py docstrings live in the modules they expose.
+"src/eosframes/**/__init__.py" = ["D104"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["eosframes"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Disable pytest's fd-level capture so the eosframes logger's handler
+# (pinned to sys.__stderr__ in tests/conftest.py) reaches the real terminal
+# during test runs. Without -s, pytest captures fd 2 even before the
+# Python-level sys.__stderr__ stream sees it.
+addopts = "-s"

eosframes-1.1.0/src/eosframes/__init__.py

@@ -0,0 +1,121 @@
+"""``eosframes`` — utilities for Ersilia model output dataframes.
+
+Split, assemble, convert, stack, scale, and summarise tabular outputs from
+the `Ersilia Model Hub <https://github.com/ersilia-os/ersilia>`_. The CLI
+entry point is ``eosframes`` (registered as a ``poetry`` script); the same
+operations are available as Python functions imported from this package.
+
+The architecture is layered: ``cli`` → ``ops`` / ``scale`` →
+``read`` / ``write`` / ``stack`` / ``naming`` / ``hub``. Every
+DataFrame that flows through the library carries two loose attributes —
+``df.model_id`` (always) and ``df.version`` (when the filename encodes
+it) — and write paths cross-validate them against the destination
+filename. See ``CLAUDE.md`` for the full attribute and naming contracts.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("eosframes")
+except PackageNotFoundError:
+    # Not installed (e.g. running from a source checkout without
+    # `pip install -e .`). Keep the package importable but signal the
+    # situation — scaler files will fail the version-match check.
+    __version__ = "0.0.0+unknown"
+
+from .exceptions import EosframesError
+from .hub import fetch_columns, fetch_metadata
+from .logger import get_logger, set_verbosity
+from .naming import (
+    get_model_id_from_path,
+    get_version_from_path,
+    is_model_id_valid,
+    is_valid_columns_name,
+    is_valid_info_name,
+    is_valid_name,
+    is_valid_stack_explicit_name,
+    is_valid_stack_mix_name,
+    is_valid_summary_name,
+    is_valid_transformer_name,
+    make_chunks_dir_name,
+    make_columns_name,
+    make_info_name,
+    make_output_name,
+    make_stack_explicit_name,
+    make_stack_mix_name,
+    make_summary_name,
+    make_transformer_name,
+    parse_name,
+    parse_stack_explicit_name,
+    parse_stack_mix_name,
+    parse_transformer_name,
+)
+from .ops import (
+    append_files,
+    convert_file,
+    dedupe_file,
+    split_csv,
+    stack_files,
+    unstack_file,
+)
+from .read import read_chunked_csvs, read_csv, read_h5
+from .scale import fit, fit_file, transform, transform_file
+from .stack import hstack, vstack
+from .write import write_chunked_csvs, write_csv, write_h5
+
+__all__ = [
+    "__version__",
+    # Low-level I/O
+    "read_csv",
+    "read_h5",
+    "read_chunked_csvs",
+    "write_csv",
+    "write_h5",
+    "write_chunked_csvs",
+    # DataFrame operations
+    "hstack",
+    "vstack",
+    # File-level operations
+    "split_csv",
+    "convert_file",
+    "stack_files",
+    "unstack_file",
+    "append_files",
+    "dedupe_file",
+    # GitHub / hub
+    "fetch_metadata",
+    "fetch_columns",
+    # Scaling
+    "fit",
+    "transform",
+    "fit_file",
+    "transform_file",
+    # Naming utilities
+    "parse_name",
+    "make_output_name",
+    "make_chunks_dir_name",
+    "make_info_name",
+    "make_columns_name",
+    "make_summary_name",
+    "make_transformer_name",
+    "make_stack_mix_name",
+    "make_stack_explicit_name",
+    "parse_stack_mix_name",
+    "parse_stack_explicit_name",
+    "parse_transformer_name",
+    "get_version_from_path",
+    "get_model_id_from_path",
+    "is_valid_name",
+    "is_valid_info_name",
+    "is_valid_columns_name",
+    "is_valid_summary_name",
+    "is_valid_stack_mix_name",
+    "is_valid_stack_explicit_name",
+    "is_valid_transformer_name",
+    "is_model_id_valid",
+    # Misc
+    "get_logger",
+    "set_verbosity",
+    "EosframesError",
+]