alias-mapper 1.0.0__tar.gz

alias_mapper-1.0.0/LICENSE

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

alias_mapper-1.0.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: alias-mapper
+Version: 1.0.0
+Summary: Translate chromosome/scaffold names in bioinformatics files between naming conventions
+Author: Max Reese
+License: MIT
+Project-URL: Homepage, https://github.com/guigolab/alias-mapper
+Project-URL: Issues, https://github.com/guigolab/alias-mapper/issues
+Keywords: bioinformatics,genomics,gff,fasta,naming-conventions,ncbi
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: License :: OSI Approved :: MIT License
+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: platformdirs>=4.0
+Requires-Dist: certifi
+Provides-Extra: trusted
+Requires-Dist: truststore; extra == "trusted"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# alias-mapper
+
+Translate chromosome and scaffold names in bioinformatics files
+between naming conventions (GenBank, RefSeq, UCSC, and others).
+
+## What it does
+
+Research files from different sources use different names for the same
+sequences: `chr1`, `NC_000001.11`, `CM000663.2`, and `1` can all refer
+to the same human chromosome. Files using different conventions can't
+be combined without translation.
+
+`alias-mapper` rewrites the sequence names in GFF, GTF, and FASTA
+files from one convention to another using a precomputed alias table
+built from NCBI assembly reports. Source convention and genome
+assembly are auto-detected from the input by default.
+
+## Install
+
+```bash
+pip install git+https://github.com/guigolab/alias-mapper.git
+```
+
+On networks that perform TLS inspection (corporate / institutional,
+e.g. CRG), also install the `trusted` extra so the tool uses the
+system keychain for cert verification:
+
+```bash
+pip install "alias-mapper[trusted] @ git+https://github.com/guigolab/alias-mapper.git"
+```
+
+The first time you run `convert`, the tool downloads the latest alias
+data (~100 MB) from GitHub Releases and builds a local SQLite database
+in your platform cache directory:
+
+- macOS:   `~/Library/Caches/alias-mapper/aliases.db`
+- Linux:   `~/.cache/alias-mapper/aliases.db`
+- Windows: `%LOCALAPPDATA%\alias-mapper\Cache\aliases.db`
+
+First-run setup takes about a minute. Subsequent runs use the cached
+database directly. If the database schema changes in a newer release,
+the cache is rebuilt automatically.
+
+## Quickstart
+
+```bash
+alias-mapper convert annotations.gff --to ucsc -o annotations.ucsc.gff
+```
+
+A summary on stderr reports how many rows were translated and how many
+had sequence names not in the alias database (those rows are passed
+through unchanged with a warning).
+
+## Usage
+
+```
+# single file
+alias-mapper convert <input> --to <convention> -o <output> [options]
+
+# multi-file: conform annotations to a reference FASTA (FASTA untouched)
+alias-mapper convert --fasta <ref> [<ann> ...] --out-dir <dir> [options]
+
+# multi-file: force the FASTA and annotations to one convention
+alias-mapper convert --fasta <ref> [<ann> ...] --overwrite-to <convention> --out-dir <dir>
+
+alias-mapper update
+```
+
+### Subcommands
+
+- **`convert`** — translate a single file, or a reference FASTA plus
+  its annotation files (multi-file mode; see [Multi-file mode](#multi-file-mode)).
+- **`update`** — re-download the latest alias data and rebuild the
+  cached database. Run manually when you want newer data.
+
+### Supported file types
+
+GFF (`.gff`, `.gff3`), GTF (`.gtf`), and FASTA (`.fa`, `.fasta`,
+`.fna`). The translator is picked by file extension.
+
+### Supported conventions
+
+`genbank`, `refseq`, `ucsc`, `sequence-name`, `assigned-molecule`.
+
+### Examples
+
+```bash
+# Translate from RefSeq to UCSC explicitly
+alias-mapper convert annotations.gff \
+    --from refseq --to ucsc \
+    -o out.gff
+
+# Pin the assembly when auto-detection is ambiguous
+alias-mapper convert annotations.gff \
+    --to ucsc \
+    --assembly GCF_000001405.40 \
+    -o out.gff
+
+# FASTA — same syntax, different file
+alias-mapper convert reference.fa \
+    --from genbank --to sequence-name \
+    --assembly GCA_963924405.1 \
+    -o reference.renamed.fa
+
+# Multi-file conform: rewrite the annotations to match reference.fa's
+# own convention; reference.fa is left untouched
+alias-mapper convert --fasta reference.fa genes.gff peaks.bed.gff \
+    --out-dir conformed/
+
+# Multi-file overwrite: force reference.fa and its annotations to UCSC
+alias-mapper convert --fasta reference.fa genes.gff \
+    --overwrite-to ucsc --out-dir ucsc_out/
+
+# Refresh the cached alias data
+alias-mapper update
+```
+
+### Multi-file mode
+
+Pass `--fasta <ref>` to process a reference FASTA together with its
+annotation files in one invocation. The assembly is detected once from
+the FASTA and the alias table is loaded once for the whole batch.
+Outputs go to `--out-dir`, named `<stem>.<convention>.<ext>` (gzip
+preserved).
+
+There are two modes:
+
+- **Conform** (the default, when `--overwrite-to` is omitted): each
+  annotation is rewritten to match the FASTA's *own* convention, and
+  the FASTA is left unchanged. Use this to make a set of annotations
+  agree with a genome you already have. The FASTA is not copied into
+  the output directory, since it is unchanged.
+- **Overwrite** (`--overwrite-to <convention>`): the FASTA and every
+  annotation are converted to the named convention.
+
+`--to` is single-file only; in `--fasta` mode use `--overwrite-to`
+(or omit it to conform).
+
+### Flags (`convert`)
+
+| Flag             | Mode        | Purpose                                                       |
+| ---------------- | ----------- | ------------------------------------------------------------- |
+| `--to`           | single-file | Target naming convention (required in single-file mode)       |
+| `-o`             | single-file | Output path                                                   |
+| `--fasta`        | multi-file  | Reference FASTA; enables multi-file mode                      |
+| `--overwrite-to` | multi-file  | Force the FASTA and all annotations to this convention        |
+| `--out-dir`      | multi-file  | Output directory for the converted files                      |
+| `--from`         | both        | Source convention. Auto-detected if absent (not used to conform) |
+| `--assembly`     | both        | Assembly accession. Auto-detected if absent                   |
+| `--alias-db`     | both        | Path to a specific alias SQLite database (overrides cache)    |
+
+### Auto-detection
+
+When `--from` or `--assembly` is omitted, the tool reads up to 50
+unique sequence names from the input and scores them against the
+database. It commits to a result only when the top candidate has at
+least 5 matches and beats the runner-up by 2× or more. Otherwise it
+errors out and asks for the flag explicitly.
+
+### Unmapped names
+
+If a sequence name in the input isn't in the alias database, the line
+is written to the output unchanged and counted in the unmapped total.
+Up to five example names are printed at the end of the run so you can
+see what didn't translate.
+
+Before giving up on a name, the tool tries a couple of conservative
+fallbacks: swapping a UCSC-style `vN` version separator for the `.N`
+form (and vice versa), and stripping an `ENA|...|accession` header
+wrapper down to the bare accession. These only run when the exact name
+isn't found, so they never override a direct match.
+
+## Data updates
+
+A weekly GitHub Actions workflow rebuilds the alias dataset from
+NCBI's published assembly summaries and publishes it as a
+`data-YYYY-MM-DD` GitHub Release. Each release ships three artifacts:
+
+- `aliases.tsv.gz` — the merged-row alias data the CLI consumes.
+- `historical.tsv.gz` — dead-accession lookup with suppression dates
+  and best-effort replacements.
+- `failures.tsv` — per-assembly collection failure log.
+
+## More
+
+See [`docs/design.md`](docs/design.md) for architecture, design
+decisions, and direction.

alias_mapper-1.0.0/README.md

@@ -0,0 +1,187 @@
+# alias-mapper
+
+Translate chromosome and scaffold names in bioinformatics files
+between naming conventions (GenBank, RefSeq, UCSC, and others).
+
+## What it does
+
+Research files from different sources use different names for the same
+sequences: `chr1`, `NC_000001.11`, `CM000663.2`, and `1` can all refer
+to the same human chromosome. Files using different conventions can't
+be combined without translation.
+
+`alias-mapper` rewrites the sequence names in GFF, GTF, and FASTA
+files from one convention to another using a precomputed alias table
+built from NCBI assembly reports. Source convention and genome
+assembly are auto-detected from the input by default.
+
+## Install
+
+```bash
+pip install git+https://github.com/guigolab/alias-mapper.git
+```
+
+On networks that perform TLS inspection (corporate / institutional,
+e.g. CRG), also install the `trusted` extra so the tool uses the
+system keychain for cert verification:
+
+```bash
+pip install "alias-mapper[trusted] @ git+https://github.com/guigolab/alias-mapper.git"
+```
+
+The first time you run `convert`, the tool downloads the latest alias
+data (~100 MB) from GitHub Releases and builds a local SQLite database
+in your platform cache directory:
+
+- macOS:   `~/Library/Caches/alias-mapper/aliases.db`
+- Linux:   `~/.cache/alias-mapper/aliases.db`
+- Windows: `%LOCALAPPDATA%\alias-mapper\Cache\aliases.db`
+
+First-run setup takes about a minute. Subsequent runs use the cached
+database directly. If the database schema changes in a newer release,
+the cache is rebuilt automatically.
+
+## Quickstart
+
+```bash
+alias-mapper convert annotations.gff --to ucsc -o annotations.ucsc.gff
+```
+
+A summary on stderr reports how many rows were translated and how many
+had sequence names not in the alias database (those rows are passed
+through unchanged with a warning).
+
+## Usage
+
+```
+# single file
+alias-mapper convert <input> --to <convention> -o <output> [options]
+
+# multi-file: conform annotations to a reference FASTA (FASTA untouched)
+alias-mapper convert --fasta <ref> [<ann> ...] --out-dir <dir> [options]
+
+# multi-file: force the FASTA and annotations to one convention
+alias-mapper convert --fasta <ref> [<ann> ...] --overwrite-to <convention> --out-dir <dir>
+
+alias-mapper update
+```
+
+### Subcommands
+
+- **`convert`** — translate a single file, or a reference FASTA plus
+  its annotation files (multi-file mode; see [Multi-file mode](#multi-file-mode)).
+- **`update`** — re-download the latest alias data and rebuild the
+  cached database. Run manually when you want newer data.
+
+### Supported file types
+
+GFF (`.gff`, `.gff3`), GTF (`.gtf`), and FASTA (`.fa`, `.fasta`,
+`.fna`). The translator is picked by file extension.
+
+### Supported conventions
+
+`genbank`, `refseq`, `ucsc`, `sequence-name`, `assigned-molecule`.
+
+### Examples
+
+```bash
+# Translate from RefSeq to UCSC explicitly
+alias-mapper convert annotations.gff \
+    --from refseq --to ucsc \
+    -o out.gff
+
+# Pin the assembly when auto-detection is ambiguous
+alias-mapper convert annotations.gff \
+    --to ucsc \
+    --assembly GCF_000001405.40 \
+    -o out.gff
+
+# FASTA — same syntax, different file
+alias-mapper convert reference.fa \
+    --from genbank --to sequence-name \
+    --assembly GCA_963924405.1 \
+    -o reference.renamed.fa
+
+# Multi-file conform: rewrite the annotations to match reference.fa's
+# own convention; reference.fa is left untouched
+alias-mapper convert --fasta reference.fa genes.gff peaks.bed.gff \
+    --out-dir conformed/
+
+# Multi-file overwrite: force reference.fa and its annotations to UCSC
+alias-mapper convert --fasta reference.fa genes.gff \
+    --overwrite-to ucsc --out-dir ucsc_out/
+
+# Refresh the cached alias data
+alias-mapper update
+```
+
+### Multi-file mode
+
+Pass `--fasta <ref>` to process a reference FASTA together with its
+annotation files in one invocation. The assembly is detected once from
+the FASTA and the alias table is loaded once for the whole batch.
+Outputs go to `--out-dir`, named `<stem>.<convention>.<ext>` (gzip
+preserved).
+
+There are two modes:
+
+- **Conform** (the default, when `--overwrite-to` is omitted): each
+  annotation is rewritten to match the FASTA's *own* convention, and
+  the FASTA is left unchanged. Use this to make a set of annotations
+  agree with a genome you already have. The FASTA is not copied into
+  the output directory, since it is unchanged.
+- **Overwrite** (`--overwrite-to <convention>`): the FASTA and every
+  annotation are converted to the named convention.
+
+`--to` is single-file only; in `--fasta` mode use `--overwrite-to`
+(or omit it to conform).
+
+### Flags (`convert`)
+
+| Flag             | Mode        | Purpose                                                       |
+| ---------------- | ----------- | ------------------------------------------------------------- |
+| `--to`           | single-file | Target naming convention (required in single-file mode)       |
+| `-o`             | single-file | Output path                                                   |
+| `--fasta`        | multi-file  | Reference FASTA; enables multi-file mode                      |
+| `--overwrite-to` | multi-file  | Force the FASTA and all annotations to this convention        |
+| `--out-dir`      | multi-file  | Output directory for the converted files                      |
+| `--from`         | both        | Source convention. Auto-detected if absent (not used to conform) |
+| `--assembly`     | both        | Assembly accession. Auto-detected if absent                   |
+| `--alias-db`     | both        | Path to a specific alias SQLite database (overrides cache)    |
+
+### Auto-detection
+
+When `--from` or `--assembly` is omitted, the tool reads up to 50
+unique sequence names from the input and scores them against the
+database. It commits to a result only when the top candidate has at
+least 5 matches and beats the runner-up by 2× or more. Otherwise it
+errors out and asks for the flag explicitly.
+
+### Unmapped names
+
+If a sequence name in the input isn't in the alias database, the line
+is written to the output unchanged and counted in the unmapped total.
+Up to five example names are printed at the end of the run so you can
+see what didn't translate.
+
+Before giving up on a name, the tool tries a couple of conservative
+fallbacks: swapping a UCSC-style `vN` version separator for the `.N`
+form (and vice versa), and stripping an `ENA|...|accession` header
+wrapper down to the bare accession. These only run when the exact name
+isn't found, so they never override a direct match.
+
+## Data updates
+
+A weekly GitHub Actions workflow rebuilds the alias dataset from
+NCBI's published assembly summaries and publishes it as a
+`data-YYYY-MM-DD` GitHub Release. Each release ships three artifacts:
+
+- `aliases.tsv.gz` — the merged-row alias data the CLI consumes.
+- `historical.tsv.gz` — dead-accession lookup with suppression dates
+  and best-effort replacements.
+- `failures.tsv` — per-assembly collection failure log.
+
+## More
+
+See [`docs/design.md`](docs/design.md) for architecture, design
+decisions, and direction.

alias_mapper-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alias-mapper"
+dynamic = ["version"]
+description = "Translate chromosome/scaffold names in bioinformatics files between naming conventions"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Max Reese" },
+]
+keywords = ["bioinformatics", "genomics", "gff", "fasta", "naming-conventions", "ncbi"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "platformdirs>=4.0",
+    "certifi",
+]
+
+[project.optional-dependencies]
+# truststore makes the package use the system keychain for TLS
+# verification, which is necessary on networks that do TLS inspection
+# (e.g. corporate / institutional networks like CRG's). Harmless
+# elsewhere. Install with: pip install alias-mapper[trusted]
+trusted = [
+    "truststore",
+]
+# Test dependencies. Install with: pip install -e .[test]
+test = [
+    "pytest>=7",
+]
+
+[project.urls]
+Homepage = "https://github.com/guigolab/alias-mapper"
+Issues = "https://github.com/guigolab/alias-mapper/issues"
+
+[project.scripts]
+alias-mapper = "alias_mapper.cli:main"
+
+# Single-source the version from the package so a release is one number to
+# bump (src/alias_mapper/__init__.py). setuptools reads __version__ without
+# importing the package, so this stays cheap and import-safe.
+[tool.setuptools.dynamic]
+version = { attr = "alias_mapper.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["alias_mapper*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Put src/ on sys.path so `pytest` finds the package without an install
+# (CI does `pip install -e .[test]`, but this keeps a bare `pytest` working
+# locally too). pythonpath requires pytest >= 7.
+pythonpath = ["src"]

alias_mapper-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alias_mapper-1.0.0/src/alias_mapper/__init__.py

@@ -0,0 +1,8 @@
+"""
+alias-mapper: translate chromosome / scaffold names in bioinformatics
+files between naming conventions.
+
+See README.md and docs/design.md for usage and architecture.
+"""
+
+__version__ = "1.0.0"

alias_mapper-1.0.0/src/alias_mapper/_ssl.py

@@ -0,0 +1,40 @@
+"""
+_ssl.py
+-------
+Shared SSL context setup for the installed alias-mapper package.
+
+Mirrors scripts/_http.py's setup, but lives inside the package so
+bootstrap.py and any future HTTP-using module (e.g. HttpAliasSource)
+can import it without depending on scripts/.
+
+Order of preference: truststore > certifi > stdlib defaults.
+
+  - truststore: uses the system keychain (necessary on networks with
+    TLS inspection like CRG's, which inject a non-Mozilla root cert)
+  - certifi: Mozilla's CA bundle, covers most environments including
+    GitHub Actions runners
+  - stdlib: last fallback, used if neither extra is installed
+
+Both truststore and certifi are optional installs. The package will
+work without them on any network where the system already trusts the
+NCBI/GitHub cert chains.
+"""
+
+import ssl
+
+try:
+    import truststore
+    truststore.inject_into_ssl()
+    SSL_BACKEND = "truststore"
+except ImportError:
+    SSL_BACKEND = None
+
+try:
+    import certifi
+    SSL_CONTEXT = ssl.create_default_context(cafile=certifi.where())
+    if SSL_BACKEND is None:
+        SSL_BACKEND = "certifi"
+except ImportError:
+    SSL_CONTEXT = ssl.create_default_context()
+    if SSL_BACKEND is None:
+        SSL_BACKEND = "stdlib"