mafutils 0.1.1__tar.gz

mafutils-0.1.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  pypi-publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish distributions
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  github-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: pypi-publish
+    permissions:
+      contents: write
+    steps:
+      - name: Create release from tag
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: ${{ github.ref_name }}
+          generate_release_notes: true

mafutils-0.1.1/AGENTS.md

@@ -0,0 +1,93 @@
+# LLM Agent rules and guardrails
+
+## Project information
+
+- This directory contains development of a program to interact with MAF (Multiple Alignment Format) files in the context of comparative genomics.
+- The current project directory is `/n/holylfs05/LABS/informatics/Lab/projects/gwct/dev/mafutils/`, referred to as `<project directory>` in this file.
+- The current project conda environment is `phyloacc-workflows`, referred to as `<project env>` in this file.
+- For commands that require the R programming language, use the conda environment `<renv>`, but follow all the same rules and guardrails outlined throughout.
+
+## Project directory guardrails
+
+- At the beginning of every session, confirm that you are working in the `<project directory>` listed above.
+- In plain text, this is referred to as the "project directory", or one of the synoyms listed below.
+- Synonyms for the term project directory include "project directory", "current directory", "working directory", "project workspace", "workspace", "repository", "repo". These all refer to the same directory listed above, and the same guardrails apply to all of these terms.
+- Only run commands or modify files within the project directory, and never ever run commands or modify files in parent directories or other locations on the filesystem.
+- Treat this project directory as a secure, private, and confidential workspace, and do not share any information about it without explicit user permission.
+- Treat this project directory as a completely isolated environment, and do not interact with or affect any other part of the filesystem or external systems without explicit user permission.
+- If you ever need to create diagnostic scripts or files that are used only by the LLM and not meant for the user, place them in a `.llm-tmp/` dir so they are not cluttering the project directories.
+- If `.llm-tmp/` is ever needed and does not exist, create it. If the project is a git repository, also add `.llm-tmp/` to `.gitignore`.
+
+## Environment
+
+- This project assumes the use of a conda environment named `<project env>` that is activated at the beginning of every session. Always try to activate this environment at the beginning of every session.
+- If the `<project env>` environment cannot be activated, run all commands except `echo`, `ls`, `cd`, `grep`, `sed`, `cat`, and `awk` with the conda environment by using `conda run -n <project env> <command>`.
+- Do not install any packages or dependencies outside of this conda environment, and do not modify the environment in any way without explicit user permission. Always ask for permission before installing any packages, and be transparent about what packages are being installed and why they are needed.
+- Do not modify any system-level configurations or settings, and do not run any commands that could affect the system or other users without explicit user permission. Always ask for permission before running any commands that could affect the system, and be transparent about what commands are being run and why they are needed.
+
+## Command execution guardrails
+
+Allowed without prompt:
+- read files
+- list files
+- modify scripts
+- modify config files
+
+Ask for permission:
+- software/package installation
+- network access
+- git push or pull
+- chmod
+- API access 
+- modification of any non-script or non-config files
+- any command that could delete files, or any script that has the potential to delete files
+
+### Specific rules
+
+- Do not run destructive file deletion commands such as `rm`, `find -delete`, or scripted equivalents.
+- Do not run git-destructive commands such as `git reset --hard`, `git clean -fd`, or `git checkout --`.
+- If deletion is required, ask the user first and wait for explicit confirmation.
+- Never ever delete a file without asking permission.
+
+#### Sandbox / bwrap troubleshooting
+
+- For simple read-only shell commands, pass the plain command directly to the terminal tool.
+- Do not manually wrap simple commands in `bash -lc ...`; the terminal tool already provides the shell wrapper.
+- Do not wrap simple read-only commands in `conda run -n <project env> bash -lc ...`.
+- In this project, simple read-only commands include:
+  - `ls`
+  - `sed`
+  - `awk`
+  - `cat`
+  - `grep`
+  - `rg`
+  - `echo`
+- For commands that actually require the conda environment, use `conda run -n <project env> ...` directly.
+- If you encounter an error like `bwrap: Unknown option --argv0`, first simplify the command to the plain direct form above rather than retrying nested wrapper forms.
+- Never fabricate a repository summary or workflow description when local file reads are failing.
+
+## Coding rules
+
+- Never insert silent fallbacks or error handling that could hide errors or issues from the user. Always be transparent about any errors or issues that occur, and do not attempt to handle them without user knowledge and permission.
+- Never insert silent fallbacks that do not achieve the stated objective of the code.
+- Never hide errors in scripts or workflows. If there is an error the script should fail. Errors are useful and necessary information so it is counterproductive to hide them.
+- Never modify tests in any way without explicit user permission.
+
+## Data analysis rules
+
+- Never modify notebooks or parts of notebooks that are not related to the user's request.
+- Notebooks should contain sections the clearly define all filtering, assumptions, and definitions of terms relevant for understanding the results of the analysis.
+- Always be explicit about how data is categorized/binned/clustered by adding text to the notebook or plot. This text should both be plain for interpretation and technical to understand the underlying code.
+- Accompanying every plot or analysis should be plain text that aids in the interpretation of said plot or analysis.
+
+## Network access guardrails
+
+- Never send or share any data outside of the project directory, and never share any data with third parties without explicit user permission.
+- Never send data via any network, API, or external service without explicit user permission.
+- Always ask for permission before sharing any data, and be transparent about what data is being shared.
+
+## Code of conduct
+
+- Never ever make up, mock, simulate, fabricate, or lie about input data or outputs.
+- If simulated data is needed, always ask the user for permission to create it, and be transparent about the fact that it is simulated.
+- Never hide errors in scripts or workflows. If there is an error the script should fail. Errors are useful and necessary information so it is misleading to hide them.

mafutils-0.1.1/DEVELOPMENT.md

@@ -0,0 +1,22 @@
+# mafutils Development Notes
+
+- `tests/example.maf.scaffold.idx` is preserved as an older scaffold-index
+  fixture for comparison.
+- `tests/example.maf.scaffold.regenerated.idx` is the scaffold index produced
+  by the current `mafutils index` implementation.
+- The real production scaffold indexes checked so far match the regenerated
+  convention, not the preserved older fixture.
+
+## Releasing to PyPI
+
+- Publishing is triggered by pushing a Git tag that matches `v*` (for example
+  `v0.1.1`).
+- Ensure the GitHub repository secret `PYPI_API_TOKEN` is set before releasing.
+- Commit release-related changes first, then create and push the tag:
+
+```bash
+git add .github/workflows/publish-pypi.yml pyproject.toml README.md DEVELOPMENT.md
+git commit -m "release: prepare v0.1.1"
+git tag -a v0.1.1 -m "v0.1.1"
+git push origin main v0.1.1
+```

mafutils-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harvard Informatics
+
+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.

mafutils-0.1.1/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mafutils
+Version: 0.1.1
+Summary: Utilities for indexing, fetching, and summarizing MAFs.
+Author: Gregg Thomas
+License: MIT License
+        
+        Copyright (c) 2026 Harvard Informatics
+        
+        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.
+        
+Project-URL: Homepage, https://informatics.fas.harvard.edu/
+Project-URL: Repository, https://github.com/harvardinformatics/mafutils
+Project-URL: Issues, https://github.com/harvardinformatics/mafutils/issues
+Keywords: maf,comparative-genomics,bioinformatics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer
+Dynamic: license-file
+
+# mafutils
+
+`mafutils` is a command-line toolkit for indexing, extracting, and summarizing
+MAF (Multiple Alignment Format) files.
+
+It currently provides three commands:
+
+- `mafutils index`
+- `mafutils fetch`
+- `mafutils stats`
+
+## Disclaimer
+
+This project was developed with significant assistance from a large language model (GPT-5 / Codex).
+
+## Installation
+
+From this `mafutils/` directory:
+
+```bash
+pip install -e .
+```
+
+If you are using the current shared workflow environment instead of a separate
+package environment, you can also run it directly with:
+
+```bash
+python -m mafutils --help
+```
+
+## Quick Start
+
+Show top-level help:
+
+```bash
+python -m mafutils --help
+```
+
+Create block and scaffold indexes for a MAF:
+
+```bash
+python -m mafutils index input.maf output.block.idx output.scaffold.idx
+```
+
+Fetch trimmed MAF regions from a BED file:
+
+```bash
+python -m mafutils fetch input.maf input.block.idx regions.bed -o outdir
+```
+
+Fetch FASTA output instead of MAF:
+
+```bash
+python -m mafutils fetch input.maf input.block.idx regions.bed -o outdir -f -fh species-coords-id
+```
+
+Extract full scaffolds using a scaffold index:
+
+```bash
+python -m mafutils fetch input.maf input.scaffold.idx scaffolds.bed -m scaffold -o outdir
+```
+
+Summarize an indexed MAF:
+
+```bash
+python -m mafutils stats input.maf input.block.idx -o summary/example
+```
+
+## Commands
+
+### `mafutils index`
+
+Create block and scaffold indexes for a MAF file.
+
+```bash
+python -m mafutils index MAF_FILE BLOCK_INDEX SCAFFOLD_INDEX
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `BLOCK_INDEX` | Output block index path |
+| `SCAFFOLD_INDEX` | Output scaffold index path |
+
+### `mafutils fetch`
+
+Fetch regions or scaffolds from a MAF using an existing index.
+
+```bash
+python -m mafutils fetch [OPTIONS] MAF_FILE INDEX_FILE BED_FILE
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `INDEX_FILE` | Block-level or scaffold-level index |
+| `BED_FILE` | BED file with regions or scaffold names |
+
+Options:
+
+| Option | Description |
+|---|---|
+| `--basename`, `-b` | Output basename strategy: `id`, `coords`, or `count` |
+| `--output`, `-o` | Output directory or output filename in single-output mode |
+| `--fasta`, `-f` | Write FASTA instead of MAF |
+| `--fasta-header`, `-fh` | FASTA header format: `species-coords-id`, `species-coords`, or `species-only` |
+| `--expected-species` | Comma-separated expected species list for FASTA filling |
+| `--expected-species-file` | File with one expected species name per line |
+| `--fasta-dedupe` | FASTA duplicate handling: `none` or `most-seq` |
+| `--processes`, `-p` | Number of worker processes |
+| `--mode`, `-m` | Fetch mode: `block` or `scaffold` |
+| `--verbose` | Emit warning lines from each completed batch |
+| `--profile` | Log internal timing breakdowns |
+
+### `mafutils stats`
+
+Summarize an indexed MAF at overall, species, and block levels.
+
+```bash
+python -m mafutils stats [OPTIONS] MAF_FILE INDEX_FILE
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `INDEX_FILE` | Block index produced by `mafutils index` |
+
+Options:
+
+| Option | Description |
+|---|---|
+| `--output-prefix`, `-o` | Output prefix/path |
+| `--processes`, `-p` | Number of worker processes |
+| `--chunk-size` | Blocks per worker task |
+| `--no-block-table` | Skip writing the per-block table |
+| `--expected-species` | Comma-separated species names for exact missing lists |
+| `--expected-species-file` | File with one species name per line |
+| `--log-level` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `--html-dashboard` | Write an HTML summary dashboard |
+| `--dashboard-top-species` | Number of species shown in dashboard bar plots |
+| `--dashboard-max-block-points` | Maximum block rows sampled for dashboard plots |
+
+## Testing
+
+From inside this `mafutils/` directory:
+
+```bash
+pytest tests/test_fetch.py
+```
+
+## Notes
+
+- `python -m mafutils ...` is the supported invocation from a source checkout.
+- The installed console entrypoint is `mafutils ...` once the package is
+  installed.

mafutils-0.1.1/README.md

@@ -0,0 +1,161 @@
+# mafutils
+
+`mafutils` is a command-line toolkit for indexing, extracting, and summarizing
+MAF (Multiple Alignment Format) files.
+
+It currently provides three commands:
+
+- `mafutils index`
+- `mafutils fetch`
+- `mafutils stats`
+
+## Disclaimer
+
+This project was developed with significant assistance from a large language model (GPT-5 / Codex).
+
+## Installation
+
+From this `mafutils/` directory:
+
+```bash
+pip install -e .
+```
+
+If you are using the current shared workflow environment instead of a separate
+package environment, you can also run it directly with:
+
+```bash
+python -m mafutils --help
+```
+
+## Quick Start
+
+Show top-level help:
+
+```bash
+python -m mafutils --help
+```
+
+Create block and scaffold indexes for a MAF:
+
+```bash
+python -m mafutils index input.maf output.block.idx output.scaffold.idx
+```
+
+Fetch trimmed MAF regions from a BED file:
+
+```bash
+python -m mafutils fetch input.maf input.block.idx regions.bed -o outdir
+```
+
+Fetch FASTA output instead of MAF:
+
+```bash
+python -m mafutils fetch input.maf input.block.idx regions.bed -o outdir -f -fh species-coords-id
+```
+
+Extract full scaffolds using a scaffold index:
+
+```bash
+python -m mafutils fetch input.maf input.scaffold.idx scaffolds.bed -m scaffold -o outdir
+```
+
+Summarize an indexed MAF:
+
+```bash
+python -m mafutils stats input.maf input.block.idx -o summary/example
+```
+
+## Commands
+
+### `mafutils index`
+
+Create block and scaffold indexes for a MAF file.
+
+```bash
+python -m mafutils index MAF_FILE BLOCK_INDEX SCAFFOLD_INDEX
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `BLOCK_INDEX` | Output block index path |
+| `SCAFFOLD_INDEX` | Output scaffold index path |
+
+### `mafutils fetch`
+
+Fetch regions or scaffolds from a MAF using an existing index.
+
+```bash
+python -m mafutils fetch [OPTIONS] MAF_FILE INDEX_FILE BED_FILE
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `INDEX_FILE` | Block-level or scaffold-level index |
+| `BED_FILE` | BED file with regions or scaffold names |
+
+Options:
+
+| Option | Description |
+|---|---|
+| `--basename`, `-b` | Output basename strategy: `id`, `coords`, or `count` |
+| `--output`, `-o` | Output directory or output filename in single-output mode |
+| `--fasta`, `-f` | Write FASTA instead of MAF |
+| `--fasta-header`, `-fh` | FASTA header format: `species-coords-id`, `species-coords`, or `species-only` |
+| `--expected-species` | Comma-separated expected species list for FASTA filling |
+| `--expected-species-file` | File with one expected species name per line |
+| `--fasta-dedupe` | FASTA duplicate handling: `none` or `most-seq` |
+| `--processes`, `-p` | Number of worker processes |
+| `--mode`, `-m` | Fetch mode: `block` or `scaffold` |
+| `--verbose` | Emit warning lines from each completed batch |
+| `--profile` | Log internal timing breakdowns |
+
+### `mafutils stats`
+
+Summarize an indexed MAF at overall, species, and block levels.
+
+```bash
+python -m mafutils stats [OPTIONS] MAF_FILE INDEX_FILE
+```
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `MAF_FILE` | Input MAF file (`.maf` or `.maf.gz`) |
+| `INDEX_FILE` | Block index produced by `mafutils index` |
+
+Options:
+
+| Option | Description |
+|---|---|
+| `--output-prefix`, `-o` | Output prefix/path |
+| `--processes`, `-p` | Number of worker processes |
+| `--chunk-size` | Blocks per worker task |
+| `--no-block-table` | Skip writing the per-block table |
+| `--expected-species` | Comma-separated species names for exact missing lists |
+| `--expected-species-file` | File with one species name per line |
+| `--log-level` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `--html-dashboard` | Write an HTML summary dashboard |
+| `--dashboard-top-species` | Number of species shown in dashboard bar plots |
+| `--dashboard-max-block-points` | Maximum block rows sampled for dashboard plots |
+
+## Testing
+
+From inside this `mafutils/` directory:
+
+```bash
+pytest tests/test_fetch.py
+```
+
+## Notes
+
+- `python -m mafutils ...` is the supported invocation from a source checkout.
+- The installed console entrypoint is `mafutils ...` once the package is
+  installed.

mafutils-0.1.1/mafutils/__init__.py

@@ -0,0 +1,3 @@
+"""Reusable MAF toolkit package for indexing, fetching, and summarizing MAFs."""
+
+__all__ = ["cli", "fetch", "index", "stats"]

mafutils-0.1.1/mafutils/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

mafutils-0.1.1/mafutils/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = 'gd532d75e9'

mafutils-0.1.1/mafutils/cli.py

@@ -0,0 +1,20 @@
+import typer
+
+from . import fetch as fetch_mod
+from . import index as index_mod
+from . import stats as stats_mod
+
+
+app = typer.Typer(
+    help="MAF toolkit for indexing, fetching, and summarizing MAF alignments.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+app.command("fetch", help="Fetch alignment blocks from a MAF using a BED file and an existing index.")(fetch_mod.fetch_command)
+app.command("index", help="Create block and scaffold indexes for a MAF file.")(index_mod.index_command)
+app.command("stats", help="Summarize an indexed MAF at overall, species, and block levels.")(stats_mod.stats_command)
+
+
+def main() -> None:
+    app()