pysec2pri 0.2.1__tar.gz → 0.2.3__tar.gz

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysec2pri
-Version: 0.2.1
+Version: 0.2.3
 Summary: Secondary to primary identifier mapping
 Keywords: snekpack,cookiecutter
 Author: Javier Millán Acosta
@@ -40,7 +40,7 @@ Requires-Dist: numpy
 Requires-Dist: rdkit
 Requires-Dist: polars-runtime-32
 Requires-Dist: sssom-schema==1.1.0a5
-Requires-Dist: mapkgsutils>=0.0.5
+Requires-Dist: mapkgsutils==0.1.1
 Maintainer: Javier Millán Acosta
 Maintainer-email: Javier Millán Acosta <javier.millan.acosta@gmail.com>
 Requires-Python: >=3.10
@@ -96,20 +96,33 @@ uv pip install git+https://github.com/jmillanacosta/pysec2pri.git
 
 ### Generating mapping sets
 
-To obtain the secondary to primary identifier SSSOM mapping set for ChEBI:
+Mapping sets can be generated from bash:
 
 ```bash
-pysec2pri chebi ids
+# ID mapping sets
+pysec2pri chebi ids (--help)
+pysec2pri ensembl ids (--help)
+pysec2pri hgnc ids (--help)
+pysec2pri vgnc ids (--help)
+pysec2pri ncbi ids (--help)
+pysec2pri hmdb-protein ids (--help)
+pysec2pri hmdb-gene ids (--help)
+pysec2pri uniprot ids (--help)
+# Label mapping sets
+pysec2pri chebi labels (--help)
+pysec2pri hgnc labels (--help)
+pysec2pri ensembl labels (--help)
+pysec2pri vgnc labels (--help)
 ```
 
-This will automatically download the latest ChEBI release and generate an SSSOM
-mapping file in your current directory.
+Or python:
 
-To process local files and specify the output:
-
-```bash
-pysec2pri chebi ids ChEBI_complete_3star.sdf --output my_mappings.sssom.tsv
 ```
+from pysec2pri import generate_ensembl_labels, generate_ensembl
+```
+
+Replacing Ensembl by the supported database. These functions return either a
+`IdMappingSet` or `LabelMappingSet`, SSSOM `MappingSet`s.
 
 For more options and help on any command:
 
@@ -122,14 +135,23 @@ The default output is in [SSSOM](https://mapping-commons.github.io/sssom/)
 
 ### Updating IDs and labels
 
-A generated mapping set can be used to update IDs and labels in Python:
+A generated mapping set can be used to update IDs and labels in Python: ChEBI
+synonyms:
 
 ```python
 from pysec2pri import generate_chebi_synonyms, resolve_labels
-cs = generate_chebi_synonyms()
+chebi_ms = generate_chebi_synonyms()
 resolve_labels(["Glucose", "ATP", "Guanine"], cs)
 ```
 
+Ensembl gene identifiers in a dataframe:
+
+```python
+from pysec2pri import update_ids, generate_ensembl
+ens_ms = generate_ensembl(version="115", species="9606")
+df_with_new_column = update_ids(mapping_set=ens_ms, ids = df, at="Ensembl_id")  # `at` is the name of the column
+```
+
 Or from the command line, given a TSV file `gene_ex.tsv`:
 
 ```
@@ -212,7 +234,7 @@ mappings.
 ### Aliases / synonyms
 
 Alias mappings use `oboInOwl:hasExactSynonym`. The alias is the `subject_label`
-and the authoritative name is the `object_label`/`object_id`.
+and the primary name is the `object_label`/`object_id`.
 
 ```mermaid
 flowchart LR

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/README.md

@@ -43,20 +43,33 @@ uv pip install git+https://github.com/jmillanacosta/pysec2pri.git
 
 ### Generating mapping sets
 
-To obtain the secondary to primary identifier SSSOM mapping set for ChEBI:
+Mapping sets can be generated from bash:
 
 ```bash
-pysec2pri chebi ids
+# ID mapping sets
+pysec2pri chebi ids (--help)
+pysec2pri ensembl ids (--help)
+pysec2pri hgnc ids (--help)
+pysec2pri vgnc ids (--help)
+pysec2pri ncbi ids (--help)
+pysec2pri hmdb-protein ids (--help)
+pysec2pri hmdb-gene ids (--help)
+pysec2pri uniprot ids (--help)
+# Label mapping sets
+pysec2pri chebi labels (--help)
+pysec2pri hgnc labels (--help)
+pysec2pri ensembl labels (--help)
+pysec2pri vgnc labels (--help)
 ```
 
-This will automatically download the latest ChEBI release and generate an SSSOM
-mapping file in your current directory.
+Or python:
 
-To process local files and specify the output:
-
-```bash
-pysec2pri chebi ids ChEBI_complete_3star.sdf --output my_mappings.sssom.tsv
 ```
+from pysec2pri import generate_ensembl_labels, generate_ensembl
+```
+
+Replacing Ensembl by the supported database. These functions return either a
+`IdMappingSet` or `LabelMappingSet`, SSSOM `MappingSet`s.
 
 For more options and help on any command:
 
@@ -69,14 +82,23 @@ The default output is in [SSSOM](https://mapping-commons.github.io/sssom/)
 
 ### Updating IDs and labels
 
-A generated mapping set can be used to update IDs and labels in Python:
+A generated mapping set can be used to update IDs and labels in Python: ChEBI
+synonyms:
 
 ```python
 from pysec2pri import generate_chebi_synonyms, resolve_labels
-cs = generate_chebi_synonyms()
+chebi_ms = generate_chebi_synonyms()
 resolve_labels(["Glucose", "ATP", "Guanine"], cs)
 ```
 
+Ensembl gene identifiers in a dataframe:
+
+```python
+from pysec2pri import update_ids, generate_ensembl
+ens_ms = generate_ensembl(version="115", species="9606")
+df_with_new_column = update_ids(mapping_set=ens_ms, ids = df, at="Ensembl_id")  # `at` is the name of the column
+```
+
 Or from the command line, given a TSV file `gene_ex.tsv`:
 
 ```
@@ -159,7 +181,7 @@ mappings.
 ### Aliases / synonyms
 
 Alias mappings use `oboInOwl:hasExactSynonym`. The alias is the `subject_label`
-and the authoritative name is the `object_label`/`object_id`.
+and the primary name is the `object_label`/`object_id`.
 
 ```mermaid
 flowchart LR

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/pyproject.toml

@@ -7,7 +7,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pysec2pri"
-version = "0.2.1"
+version = "0.2.3"
 description = "Secondary to primary identifier mapping"
 readme = "README.md"
 authors = [
@@ -71,7 +71,7 @@ dependencies = [
     "rdkit", # Chemistry toolkit for SDF parsing
     "polars-runtime-32", # Polars runtime for 32-bit systems
     "sssom-schema==1.1.0a5", # SSSOM schema for validation
-    "mapkgsutils>=0.0.5",
+    "mapkgsutils==0.1.1",
 ]
 
 # see https://peps.python.org/pep-0735/ and https://docs.astral.sh/uv/concepts/dependencies/#dependency-groups
@@ -255,7 +255,7 @@ known-first-party = [
 docstring-code-format = true
 
 [tool.bumpversion]
-current_version = "0.2.1"
+current_version = "0.2.3"
 parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)(?:-(?P<release>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?(?:\\+(?P<build>[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*))?"
 serialize = [
     "{major}.{minor}.{patch}-{release}+{build}",

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/api.py

@@ -244,8 +244,7 @@ def generate_hgnc_primary_ids(
     Only the HGNC complete set file is downloaded/read.  The returned mapping
     set has an empty ``mappings`` list; its ``_primary_ids`` store is
     populated with every current HGNC ID so that ``to_pri_ids()`` produces
-    the authoritative complete list, not just the subset of primaries that
-    happen to have an associated secondary.
+    the complete list.
 
     Args:
         input_path: Local HGNC complete set TSV. Auto-downloaded if ``None``.
@@ -1001,7 +1000,7 @@ def generate_ensembl_labels(
         species: Canonical NCBI taxon ID, or ``"all"`` (default) to process
             every species Ensembl publishes and combine them into one
             mapping set -- see :func:`_generate_ensembl_all_species`. A
-            symbol shared by two species becomes genuinely ambiguous in
+            symbol shared by two species becomes ambiguous in
             that combined output (there's no longer a per-species scope to
             disambiguate it). This is network-heavy (~276 species); pass
             an explicit taxon ID for a fast, single-species run.
@@ -1112,9 +1111,7 @@ def generate_ensembl_label_history(
     previous-symbol -> current-symbol transitions are derived by diffing
     each release's primary-label snapshot per stable ID. Delegates to
     :func:`pysec2pri.consolidate.build_label_history`, which walks every
-    historical release (or a bounded range) and resumes on re-run. This is
-    a network-heavy, run-on-demand operation, not part of normal
-    single-release generation.
+    historical release (or a bounded range) and resumes on re-run.
 
     Args:
         species: Canonical NCBI taxon ID (default ``9606`` for human).
@@ -2015,15 +2012,10 @@ def crosswalk(
 ) -> dict[str, str] | pd.DataFrame:
     r"""Map a gene identifier from one vocabulary to another, via HGNC.
 
-    A thin convenience wrapper, not a separate resolver: ``frm="symbol"``
-    resolves through :func:`generate_hgnc_labels` +
+    Wrapper: ``frm="symbol"`` resolves through :func:`generate_hgnc_labels` +
     :func:`~pysec2pri.update_ids.update_labels`, so a *previous* HGNC symbol
-    still resolves to its current identity (the temporal aspect) and a
-    genuinely ambiguous symbol is left blank and reported rather than
-    guessed. ``frm`` in ``"ensembl"``, ``"entrez"``, ``"refseq"``, or
-    ``"uniprot"`` resolves through HGNC's own cross-reference crosswalk
-    table, downloaded from the ``xref_sources`` declared in
-    ``config/hgnc.yaml`` unless *xref_mapping* is supplied explicitly.
+    still resolves to its current identity (the temporal aspect) and an ambiguous
+    label is left blank and reported rather than guessed.
 
     Args:
         input_data: A single identifier string, a list of identifier

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/cli.py

@@ -464,7 +464,7 @@ def ensembl_label_history_cmd(
     Ensembl's core schema has no previous-gene-symbol table, so this walks
     every historical release (or a bounded --from-version/--to-version
     range) and diffs each release's primary-label snapshot to recover
-    genuine previous -> current symbol transitions. Network-heavy and
+    true previous -> current symbol transitions. Network-heavy and
     resumable; run on demand, not part of normal mapping generation.
     """
     from pysec2pri.api import generate_ensembl_label_history
@@ -638,11 +638,11 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
     """Return a decorated (but not yet click.command-wrapped) ``consolidate`` callable."""
 
     def _cmd(
-        mode: str,
         mapping_sets: str,
         cache_dir: Path | None,
         force: bool,
         no_progress: bool,
+        output: Path | None,
         **extra_kwargs: Any,
     ) -> None:
         from pysec2pri.consolidate import _sssom_output_path, consolidate_mapping_dates
@@ -650,34 +650,23 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
         extras = ", ".join(f"{k}={v}" for k, v in extra_kwargs.items() if v is not None)
         click.echo(
             f"Consolidating {cfg_id.upper()} mapping dates "
-            f"(mode={mode}{', ' + extras if extras else ''}, {mapping_sets})..."
+            f"({extras + ', ' if extras else ''}{mapping_sets})..."
         )
         try:
             path, _ = consolidate_mapping_dates(
                 cfg_id,
-                mode=mode,
                 cache_dir=cache_dir,
                 mapping_sets=mapping_sets,
                 show_progress=not no_progress,
                 force=force,
+                output=output,
                 **extra_kwargs,
             )
         except ValueError as exc:
             raise click.ClickException(str(exc)) from exc
-        click.echo(f"Wrote consolidated mapping set -> {_sssom_output_path(path)}")
+        click.echo(f"Wrote consolidated mapping set -> {output or _sssom_output_path(path)}")
 
     decorators: list[Callable[..., Any]] = [
-        click.option(
-            "--mode",
-            default="release",
-            show_default=True,
-            type=click.Choice(["release", "date"]),
-            help=(
-                "'release': walk every historical release for the first-seen version/date. "
-                "'date': single pass using the source's own per-row date (falls back to "
-                "'release' with a warning if the source has none)."
-            ),
-        ),
         *extra_opts,
         click.option(
             "--mapping-sets",
@@ -693,6 +682,13 @@ def _make_consolidate_cmd(cfg_id: str, extra_opts: list[Callable[..., Any]]) ->
             default=False,
             help="Re-scan every release, ignoring resume state.",
         ),
+        click.option(
+            "-o",
+            "--output",
+            type=PathType,
+            default=None,
+            help="Also write the consolidated SSSOM mapping set to this path.",
+        ),
         _opt_no_progress,
     ]
     for dec in reversed(decorators):
@@ -718,12 +714,13 @@ def _register_consolidate_commands(parent: click.Group) -> None:
                     "Build/update the per-mapping first-seen-date index, written as a real "
                     "SSSOM mapping set whose mapping_date is each mapping's date of first "
                     "appearance.\n\n"
-                    "In 'release' mode (default), walks every historical release once to "
-                    "discover the earliest release each mapping appeared in. This is slow "
-                    "and network-heavy (~250 releases for ChEBI); meant to be run as a "
-                    "manual/one-off operation, not as part of normal mapping generation. "
-                    "In 'date' mode, a single current-release pass captures the source's "
-                    "own per-row date directly (fast)."
+                    "For datasources with a versioned archive (ChEBI, Ensembl, HGNC, "
+                    "UniProt), walks every historical release once to discover the earliest "
+                    "release each mapping appeared in. This is slow and network-heavy (~250 "
+                    "releases for ChEBI); meant to be run as a manual/one-off operation, not "
+                    "as part of normal mapping generation. For datasources without one "
+                    "(NCBI, VGNC), a single current-release pass captures the source's own "
+                    "per-row date directly (fast)."
                 ),
             )(raw_cmd)
         )

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/config/ensembl.yaml

@@ -7,13 +7,6 @@ prefix: "ENSEMBL"
 curie_base_url: "http://identifiers.org/ensembl/"
 entity_types: ["genes"]
 
-# Canonical key = NCBI taxon ID. `token` is Ensembl's own species directory
-# component (e.g. https://ftp.ensembl.org/pub/release-115/mysql/homo_sapiens_core_115_38/).
-# `default: "all"` processes every species Ensembl publishes for the
-# release and combines them into one mapping set (see
-# pysec2pri.api._generate_ensembl_all_species) -- network-heavy (~276
-# species, one download each); pass an explicit taxon ID for a fast,
-# single-species run.
 species:
   default: "all"
   available:
@@ -511,5 +504,4 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default."

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/config/hgnc.yaml

@@ -142,8 +142,7 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default"
 
 mapping_sets:
   ids:

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/config/ncbi.yaml

@@ -9,14 +9,6 @@ prefix: "NCBIGene"
 curie_base_url: "http://identifiers.org/ncbigene/"
 entity_types: ["genes"]
 
-# NCBI's own token IS the canonical taxon ID (no translation needed, unlike
-# Ensembl) -- gene_history/gene_info are filtered directly on #tax_id, which
-# accepts ANY taxon ID, not just the ones listed here. `available` exists
-# only to drive CLI help/choices for common species; NCBIParser never calls
-# species_token(), so it never restricts which taxon IDs are accepted.
-# `default: "all"` processes every organism in the file instead of
-# filtering to one (see NCBIParser.ALL_SPECIES) -- cheap here since
-# gene_info/gene_history are single global files already being downloaded.
 species:
   default: "all"
   available:
@@ -173,5 +165,4 @@ xref_sources:
       refseq: "RefSeq IDs"
       uniprot: "UniProt ID(supplied by UniProt)"
     note:
-      "Source of truth for cross-references varies; this is a suggested default,
-      not authoritative."
+      "Source of truth for cross-references varies; this is a suggested default"

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/config/vgnc.yaml

@@ -7,22 +7,6 @@ prefix: "VGNC"
 curie_base_url: "http://identifiers.org/vgnc/"
 entity_types: ["genes"]
 
-# VGNC (Vertebrate Gene Nomenclature Committee) names genes for vertebrate
-# species that lack their own nomenclature committee (human/mouse/rat are
-# deliberately out of scope -- HGNC/MGI/RGD cover those). Unlike Ensembl
-# (one download URL per species), VGNC publishes a single global TSV per
-# file with a `taxon_id` column, filtered the same way NCBI's
-# gene_info/gene_history are filtered by `#tax_id` -- see VGNCParser.
-# `default: "all"` processes every species together (see
-# VGNCParser.ALL_SPECIES) -- cheap for ids (the global withdrawn set is
-# always parsed in full regardless), heavier for labels (a symbol shared
-# by two species becomes genuinely ambiguous with no per-species scope to
-# disambiguate it). VGNCParser never calls species_token(), so `available`
-# exists only to drive CLI help/choices and never restricts which taxon IDs
-# are accepted. Taxon IDs below were verified against the live data (each
-# species' own vgnc/tsv/<species>/*_vgnc_gene_set_All.tsv, cross-referenced
-# by VGNC ID against vgnc/tsv/all/all_vgnc_gene_set_All.tsv's taxon_id
-# column).
 species:
   default: "all"
   available:

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/consolidate.py

@@ -40,7 +40,6 @@ import json
 import os
 import shutil
 import tempfile
-import warnings
 from collections.abc import Callable, Iterable
 from pathlib import Path
 from typing import Any
@@ -60,7 +59,7 @@ __all__ = [
 ]
 
 # Datasources this module knows how to download+parse per release.
-# NCBI and VGNC have no versioned archive, so only mode="date" applies to them.
+# NCBI and VGNC have no versioned archive, so they take the single-parse path.
 SUPPORTED_DATASOURCES = ("chebi", "ensembl", "hgnc", "ncbi", "uniprot", "vgnc")
 
 # mapping_sets kinds each datasource's parser actually supports.
@@ -100,7 +99,8 @@ def _uniprot_versions(**kwargs: Any) -> list[str]:
     return UniProtDownloader().list_versions()
 
 
-# Datasources with a versioned archive that can be walked for mode="release".
+# Datasources with a versioned archive that can be walked release by release.
+# Datasources absent here (NCBI, VGNC) take the single-parse path instead.
 _LIST_VERSIONS_FNS: dict[str, Callable[..., list[str]]] = {
     "chebi": _chebi_versions,
     "ensembl": _ensembl_versions,
@@ -161,6 +161,12 @@ _read_meta = _consolidate.read_meta
 _write_meta = _consolidate.write_meta
 
 
+def _save_optional_output(mapping_set: BaseMappingSet, output: Path | None) -> None:
+    """Write *mapping_set* to *output* as SSSOM when an output path is given."""
+    if output is not None:
+        mapping_set.save("sssom", output)
+
+
 def load_mapping_dates(
     datasource: str,
     cache_dir: Path | None = None,
@@ -382,48 +388,48 @@ def _write_consolidated_sssom(
 def consolidate_mapping_dates(
     datasource: str,
     *,
-    mode: str = "release",
     cache_dir: Path | None = None,
     mapping_sets: str = "ids",
     show_progress: bool = True,
     force: bool = False,
+    output: Path | None = None,
     **kwargs: Any,
 ) -> tuple[Path, BaseMappingSet]:
     """Build/update the first-seen-date index for *datasource*.
 
-    Two strategies, selected via *mode*:
-
-    - ``"release"``: walk every historical release of *datasource* once
-      (oldest first, resuming from the last completed version unless
-      *force* is set). For every mapping seen, records the version/date it
-      first appeared and keeps bumping the version/date it was last seen.
-      This is a slow, network-heavy operation (~250 releases for ChEBI) and
-      is meant to be run manually/as a one-off, not as part of normal
-      mapping generation. Requires a versioned archive (ChEBI, HGNC,
-      UniProt); raises :class:`ValueError` for datasources without one
-      (e.g. NCBI).
-    - ``"date"``: a single (current) parse, capturing whatever real
-      per-row ``mapping_date`` the datasource's parser already produces
-      (e.g. HGNC's ``date_symbol_changed``, NCBI's ``Discontinue_Date``).
-      Fast -- no historical walk. If *datasource* never produces a real
-      per-row date (ChEBI, UniProt), falls back to ``"release"`` mode and
-      warns the user.
-
-    Either way, alongside the internal cache file this also writes a
-    companion real SSSOM mapping set (see :func:`_sssom_output_path`) where
-    every row's ``mapping_date`` is its true first-seen date, rather than
-    whichever release happened to be parsed last.
+    Collects every mapping using all available provenance. The walk shape is
+    chosen automatically by data availability, not by a requested mode:
+
+    - Datasources **with** a versioned archive (ChEBI, Ensembl, HGNC,
+      UniProt): walk every historical release once (oldest first, resuming
+      from the last completed version unless *force*). For every mapping
+      seen, records the version/date it first appeared and keeps bumping the
+      version/date it was last seen. Slow and network-heavy (~250 releases
+      for ChEBI); meant to be run manually/as a one-off.
+    - Datasources **without** one (NCBI, VGNC): a single current parse
+      caching the *full* mapping set — every mapping kept, stamped with its
+      own per-row ``mapping_date`` when the parser provides one and left
+      undated otherwise. Fast, no historical walk.
+
+    Alongside the internal cache file this also writes a companion real SSSOM
+    mapping set (see :func:`_sssom_output_path`) where each row's
+    ``mapping_date`` is its per-row date when present, else its first-seen
+    release date — distinct from the first-seen release version carried in
+    ``subject_source_version``/``object_source_version``.
 
     Args:
         datasource: One of :data:`SUPPORTED_DATASOURCES`.
-        mode: ``"release"`` or ``"date"``.
         cache_dir: Directory to write the cache file. Defaults to
             :func:`default_cache_dir`.
         mapping_sets: ``"ids"`` or ``"labels"``.
         show_progress: Whether to show a progress bar over releases
-            (``"release"`` mode only).
+            (versioned-archive datasources only).
         force: Re-scan every release from scratch, ignoring any existing
-            cache/resume state (``"release"`` mode only).
+            cache/resume state (versioned-archive datasources only).
+        output: Optional path to also write the consolidated SSSOM mapping
+            set to. The internal cache-adjacent copy (see
+            :func:`_sssom_output_path`) is always written; when *output* is
+            given, the same full mapping set is additionally saved there.
         **kwargs: Datasource-specific knobs (``subset`` for ChEBI, ``species``
             for NCBI/Ensembl); ignored for datasources with no such config
             block.
@@ -434,13 +440,9 @@ def consolidate_mapping_dates(
         written alongside it) and the in-memory consolidated mapping set.
 
     Raises:
-        ValueError: For an unknown *mode*, an unsupported *datasource*, an
-            unsupported *mapping_sets* for *datasource*, or
-            ``mode="release"`` against a datasource with no versioned
-            archive.
+        ValueError: For an unsupported *datasource* or an unsupported
+            *mapping_sets* for *datasource*.
     """
-    if mode not in ("release", "date"):
-        raise ValueError(f"mode must be 'release' or 'date', got {mode!r}")
     if datasource not in SUPPORTED_DATASOURCES:
         raise ValueError(
             f"Unsupported datasource: {datasource!r}. Supported: {SUPPORTED_DATASOURCES}"
@@ -465,46 +467,43 @@ def consolidate_mapping_dates(
     cache_path = _cache_path(cache_dir, datasource, mapping_sets, **kwargs)
     meta_path = _meta_path(cache_dir, datasource, mapping_sets, **kwargs)
 
-    if mode == "date":
-        got_dates = _consolidate.consolidate_by_date(
-            cache_path,
-            meta_path,
-            run_one_version=lambda: _run_one_version(datasource, None, mapping_sets, **kwargs),
-        )
-        if got_dates:
-            _, mapping_set = _write_consolidated_sssom(
-                datasource, mapping_sets, cache_path, meta_path
-            )
-            return cache_path, mapping_set
-        msg = (
-            f"{datasource!r} has no parseable per-row mapping dates; "
-            "falling back to mode='release'."
-        )
-        logger.warning(msg)
-        warnings.warn(msg, UserWarning, stacklevel=2)
+    def _run(version: str | None) -> Any:
+        return _run_one_version(datasource, version, mapping_sets, **kwargs)
 
     list_versions_fn = _LIST_VERSIONS_FNS.get(datasource)
     if list_versions_fn is None:
-        raise ValueError(f"{datasource!r} has no versioned archive; only mode='date' is supported.")
+        # No versioned archive (NCBI, VGNC): single current parse, full set.
+        _consolidate.consolidate(
+            cache_path,
+            meta_path,
+            label=datasource,
+            run_one_version=_run,
+            show_progress=show_progress,
+            force=force,
+        )
+    else:
+        # Versioned archive: walk every historical release for first-seen dates.
+        from pysec2pri.download import resolve_release_date
 
-    from pysec2pri.download import resolve_release_date
+        fn = list_versions_fn
+        _consolidate.consolidate(
+            cache_path,
+            meta_path,
+            label=datasource,
+            run_one_version=_run,
+            list_versions=lambda: fn(**kwargs),
+            resolve_release_date=lambda v: resolve_release_date(datasource, v, **kwargs),
+            show_progress=show_progress,
+            force=force,
+        )
 
-    _consolidate.consolidate_by_release(
-        cache_path,
-        meta_path,
-        label=datasource,
-        list_versions=lambda: list_versions_fn(**kwargs),
-        run_one_version=lambda v: _run_one_version(datasource, v, mapping_sets, **kwargs),
-        resolve_release_date=lambda v: resolve_release_date(datasource, v, **kwargs),
-        show_progress=show_progress,
-        force=force,
-    )
     _, mapping_set = _write_consolidated_sssom(datasource, mapping_sets, cache_path, meta_path)
+    _save_optional_output(mapping_set, output)
     return cache_path, mapping_set
 
 
 # Cross-release label history (e.g. Ensembl, whose core schema has no
-# previous-gene-symbol table -- genuine previous->current symbol transitions
+# previous-gene-symbol table: previous->current symbol transitions
 # are recovered by diffing each release's current-label snapshot).
 
 
@@ -571,8 +570,8 @@ def build_label_history(
     previous release's, oldest to newest. Network-heavy and resumable --
     meant to be run on demand, not as part of normal mapping generation
     (mirrors the release-walk pattern in
-    :func:`mapkgsutils.consolidate.consolidate_by_release`, but tracks a
-    carried label map instead of first/last-seen dates).
+    :func:`mapkgsutils.consolidate.consolidate`, but tracks a carried label
+    map instead of first/last-seen dates).
 
     Args:
         datasource: Currently only ``"ensembl"`` is supported.
@@ -648,7 +647,7 @@ def build_label_history(
             shutil.rmtree(tmpdir, ignore_errors=True)
 
         release_date = resolve_release_date(datasource, v, species=species)
-        # Unlike consolidate_by_release's plain-dict cache, these rows become
+        # Unlike the consolidate walk's plain-dict cache, these rows become
         # real Mapping objects -- mapping_date must be a valid date or None,
         # never the raw (non-date-shaped) version string.
         date_str = release_date.date().isoformat() if release_date else None

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/downloads/ensembl.py

@@ -375,8 +375,16 @@ def urls_and_date(
         urls = _get_ensembl_urls_for_version(version, species=species)
         logger.info("Ensembl version %s (species %s): %s", version, species, urls)
     else:
-        release_info = check_ensembl_release()
-        urls = release_info.files
-        release_date = release_info.release_date
-        logger.info("Ensembl release %s: %s", release_info.version, urls)
+        # The release number is global across species, but the URLs (and the
+        # resolved release date) are species-specific, so resolve the latest
+        # version and build URLs for the requested species rather than reusing
+        # check_ensembl_release()'s human-only URLs.
+        versions = EnsemblDownloader(show_progress=False).list_versions()
+        if not versions:
+            raise ValueError("Could not find Ensembl releases on the FTP server")
+        version = versions[-1]
+        urls = _get_ensembl_urls_for_version(version, species=species)
+        check_url = urls.get("stable_id_event")
+        release_date = get_file_last_modified(check_url) if check_url else None
+        logger.info("Ensembl release %s (species %s): %s", version, species, urls)
     return urls, release_date

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/parsers/chebi.py

@@ -190,8 +190,7 @@ class ChEBIParser(BaseParser):
         Reads ``compounds.tsv`` (TSV releases >= 245) to extract every current
         ChEBI compound ID.  The returned mapping set has an empty ``mappings``
         list; its ``_primary_ids`` store is populated with every current ChEBI
-        ID (CHEBI: prefixed) so that ``to_pri_ids()`` produces the authoritative
-        complete list.
+        ID (CHEBI: prefixed) so that ``to_pri_ids()`` produces the complete list.
 
         Args:
             input_path: Path to a directory containing ``compounds.tsv``, or
@@ -496,7 +495,7 @@ def _parse_names_tsv(
 
     Format: id|compound_id|name|type|status_id|adapted|language_code|ascii_name
 
-    The authoritative primary (canonical) name for each compound is taken from
+    The true primary (canonical) name for each compound is taken from
     the ``name`` column of ``compounds.tsv``: the same value displayed on the
     ChEBI website and stored as the top-level label in the ChEBI ontology.
     Every entry in ``names.tsv`` that differs from that canonical name is
@@ -526,7 +525,7 @@ def _parse_names_tsv(
             "Pass the path to compounds.tsv."
         )
 
-    # Load canonical names from compounds.tsv (ChEBI-authoritative primary label)
+    # Load canonical names from compounds.tsv (ChEBI primary label)
     cpd_cols = ["id", "name", "stars"] if subset == "3star" else ["id", "name"]
     cpd_df = pl.read_csv(
         compounds_path,

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/parsers/hmdb.py

@@ -17,7 +17,6 @@ import gzip
 import io
 import re
 import zipfile
-from collections.abc import Callable
 from pathlib import Path
 from typing import IO, TYPE_CHECKING
 
@@ -85,7 +84,6 @@ class HMDBParser(BaseParser):
         element_tag: str,
         prefix: str,
         desc: str,
-        secondary_normaliser: Callable[[str], str] | None = None,
     ) -> BaseMappingSet:
         """Parse an HMDB XML file and return a mapping set.
 
@@ -95,8 +93,6 @@ class HMDBParser(BaseParser):
                 ``"protein"``).
             prefix: CURIE prefix (``"HMDB"`` for both record types).
             desc: Progress-bar description string.
-            secondary_normaliser: Optional callable ``(raw_str) -> str``
-                applied to each raw secondary accession before prefixing.
 
         Returns:
             :class:`BaseMappingSet` with computed cardinalities and
@@ -130,10 +126,10 @@ class HMDBParser(BaseParser):
                         accession_elem = elem.find("accession")
                     if accession_elem is not None and accession_elem.text:
                         primary_ids_found.add(f"{prefix}:{accession_elem.text.strip()}")
-                    rows_data.extend(self._process_record(elem, prefix, secondary_normaliser))
+                    rows_data.extend(self._process_record(elem, prefix))
                     elem.clear()
         except DefusedET.ParseError:
-            rows_data = self._parse_simple_xml(file_path, element_tag, prefix, secondary_normaliser)
+            rows_data = self._parse_simple_xml(file_path, element_tag, prefix)
 
         mappings = self._build_mappings(
             rows_data, fixed, desc="Building HMDB mappings", total=len(rows_data)
@@ -147,9 +143,14 @@ class HMDBParser(BaseParser):
         self,
         elem: Element,
         prefix: str,
-        secondary_normaliser: Callable[[str], str] | None,
     ) -> list[dict[str, str]]:
-        """Extract row dicts from a single record element."""
+        """Extract row dicts from a single record element.
+
+        Bare-numeric ``secondary_accessions`` entries are skipped: in the
+        proteins file these are HMDB's internal database row ids (not legacy
+        accessions), and a bare integer is never a valid HMDB accession for
+        either record type. See issue #44.
+        """
         # Primary accession
         accession_elem = elem.find("hmdb:accession", HMDB_NS)
         if accession_elem is None:
@@ -177,8 +178,8 @@ class HMDBParser(BaseParser):
             if not sec_elem.text:
                 continue
             raw_sec = sec_elem.text.strip()
-            if secondary_normaliser is not None:
-                raw_sec = secondary_normaliser(raw_sec)
+            if _BARE_NUM_RE.match(raw_sec):
+                continue
             secondary_id = f"{prefix}:{raw_sec}"
             rows.append(
                 {
@@ -200,7 +201,6 @@ class HMDBParser(BaseParser):
         file_path: Path,
         element_tag: str,
         prefix: str,
-        secondary_normaliser: Callable[[str], str] | None,
     ) -> list[dict[str, str]]:
         """Fallback parser for test files without a namespace declaration."""
         rows_data: list[dict[str, str]] = []
@@ -208,7 +208,7 @@ class HMDBParser(BaseParser):
             tree = DefusedET.parse(file_path)
             root = tree.getroot()
             for record in root.findall(f".//{element_tag}"):
-                rows_data.extend(self._process_record(record, prefix, secondary_normaliser))
+                rows_data.extend(self._process_record(record, prefix))
         except Exception as e:
             logger.warning("Failed to parse HMDB XML: %s", e)
         return rows_data
@@ -329,9 +329,15 @@ class HMDBProteinParser(HMDBParser):
 
     Reads configuration from ``hmdb_proteins.yaml``.
     Primary accessions have the form ``HMDBP…`` (e.g. ``HMDBP00001``).
-    Secondary accessions may be bare numbers (legacy format, e.g. ``5229``)
-    or full ``HMDBP`` accessions; both are normalised by
-    :meth:`_normalise_protein_secondary`.
+
+    A record's ``<secondary_accessions>`` block holds two distinct kinds of
+    value. Only the first is a real identifier:
+
+    * **``HMDBP``-prefixed accessions** (e.g. ``HMDBP05261``): genuine retired
+      accessions that map to the record's primary accession.
+    * **Bare numeric values** (e.g. ``5229``): HMDB's internal database row id,
+      *not* a legacy accession. These are dropped by the shared
+      :meth:`~HMDBParser._process_record` (see issue #44).
     """
 
     datasource_name = "hmdb_proteins"
@@ -341,26 +347,6 @@ class HMDBProteinParser(HMDBParser):
         """Proteins download URL from ``hmdb_proteins.yaml``."""
         return self.get_download_url("proteins") or ""
 
-    @staticmethod
-    def _normalise_protein_secondary(raw: str) -> str:
-        """Normalise a raw secondary protein accession to a ``HMDBP``-prefixed form.
-
-        Bare numeric values (legacy IDs) are zero-padded to five digits and
-        prefixed with ``HMDBP`` to match the primary accession pattern.
-        Already-prefixed values are returned unchanged.
-
-        Args:
-            raw: Raw secondary accession string (e.g. ``"5229"`` or
-                ``"HMDBP05229"``).
-
-        Returns:
-            Normalised accession string (e.g. ``"HMDBP05229"``).
-        """
-        raw = raw.strip()
-        if _BARE_NUM_RE.match(raw):
-            return f"HMDBP{int(raw):05d}"
-        return raw
-
     def parse(self, input_path: Path | str | None) -> BaseMappingSet:
         """Parse ``hmdb_proteins.xml`` (or ``.zip`` / ``.gz``).
 
@@ -377,7 +363,6 @@ class HMDBProteinParser(HMDBParser):
             element_tag="protein",
             prefix="HMDBP",
             desc="Parsing HMDB proteins XML",
-            secondary_normaliser=self._normalise_protein_secondary,
         )
 
 

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/parsers/vgnc.py

@@ -25,9 +25,8 @@ This parser extracts:
    detection and ``to_pri_labels()`` stay scoped to one species' namespace
    instead of flagging cross-species homonyms as ambiguous. Passing
    :data:`ALL_SPECIES` processes every species together instead, in which
-   case a shared symbol *is* genuinely ambiguous (there's no other context
-   to tell the species apart) and gets flagged accordingly -- that's
-   ``_annotate_ambiguous_mappings`` doing its job, not a bug.
+   case a shared symbol is really ambiguous (there's no other context
+   to tell the species apart) and gets flagged accordingly.
 
 Uses SSSOM-compliant MappingSet classes with cardinality computation.
 """

{pysec2pri-0.2.1 → pysec2pri-0.2.3}/src/pysec2pri/version.py

@@ -12,7 +12,7 @@ __all__ = [
     "get_version",
 ]
 
-VERSION = "0.2.1"
+VERSION = "0.2.3"
 
 
 def get_git_hash() -> str: