pysec2pri 0.2.3__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysec2pri
-Version: 0.2.3
+Version: 0.2.4
 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.1.1
+Requires-Dist: mapkgsutils==0.1.2
 Maintainer: Javier Millán Acosta
 Maintainer-email: Javier Millán Acosta <javier.millan.acosta@gmail.com>
 Requires-Python: >=3.10
@@ -182,6 +182,15 @@ pysec2pri hgnc ids  # outputs hgnc_{version}_sssom.tsv
 pysec2pri update-ids gene_ex.tsv hgnc --at gene --mapping hgnc_{version}_sssom.tsv
 ```
 
+In Python, `load_<datasource>` reads a written SSSOM file back into the same
+`IdMappingSet`/`LabelMappingSet`:
+
+```python
+from pysec2pri import load_hgnc, update_ids
+hgnc_ms = load_hgnc("hgnc_115_sssom.tsv")
+df_with_new_column = update_ids(mapping_set=hgnc_ms, ids=df, at="gene")
+```
+
 Ambiguous mappings (where a deprecated ID or label serves as a recommended for
 another entity) are not resolved, but flagged for users to solve them manually.
 If the input file has a column of known aliases or synonyms for each row, pass
@@ -324,15 +333,15 @@ crosswalk("ENSG00000141510", frm="ensembl", to="symbol")  # via HGNC's own cross
 ### Consolidating mapping dates across releases
 
 A single release snapshot only presents each mapping's _last-seen_ date.
-`consolidate` builds a first-seen-date index by walking a datasource's
-historical archive (or, where the parser already exposes a real per-row date
-such as HGNC's `date_symbol_changed`, a single fast pass) and writes it back out
-as a real SSSOM mapping set whose `mapping_date` is each mapping's true first
-appearance:
+`consolidate` builds a first-seen-date index and writes it back out as a real
+SSSOM mapping set whose `mapping_date` is each mapping's true first appearance.
+The path is chosen automatically: datasources with a versioned archive are
+walked release by release, while those without one (NCBI, VGNC) are covered in a
+single fast pass over the current release:
 
 ```bash
-pysec2pri chebi consolidate --mode release   # walks ~250 ChEBI releases; slow, run as a one-off
-pysec2pri hgnc consolidate --mode date       # fast: uses HGNC's own per-row date
+pysec2pri chebi consolidate   # walks ~250 ChEBI releases (versioned archive); slow, run as a one-off
+pysec2pri ncbi consolidate    # single fast pass (no versioned archive)
 ```
 
 Supported for `chebi`, `ensembl`, `hgnc`, `ncbi`, `uniprot`, and `vgnc`. Ensembl

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

@@ -129,6 +129,15 @@ pysec2pri hgnc ids  # outputs hgnc_{version}_sssom.tsv
 pysec2pri update-ids gene_ex.tsv hgnc --at gene --mapping hgnc_{version}_sssom.tsv
 ```
 
+In Python, `load_<datasource>` reads a written SSSOM file back into the same
+`IdMappingSet`/`LabelMappingSet`:
+
+```python
+from pysec2pri import load_hgnc, update_ids
+hgnc_ms = load_hgnc("hgnc_115_sssom.tsv")
+df_with_new_column = update_ids(mapping_set=hgnc_ms, ids=df, at="gene")
+```
+
 Ambiguous mappings (where a deprecated ID or label serves as a recommended for
 another entity) are not resolved, but flagged for users to solve them manually.
 If the input file has a column of known aliases or synonyms for each row, pass
@@ -271,15 +280,15 @@ crosswalk("ENSG00000141510", frm="ensembl", to="symbol")  # via HGNC's own cross
 ### Consolidating mapping dates across releases
 
 A single release snapshot only presents each mapping's _last-seen_ date.
-`consolidate` builds a first-seen-date index by walking a datasource's
-historical archive (or, where the parser already exposes a real per-row date
-such as HGNC's `date_symbol_changed`, a single fast pass) and writes it back out
-as a real SSSOM mapping set whose `mapping_date` is each mapping's true first
-appearance:
+`consolidate` builds a first-seen-date index and writes it back out as a real
+SSSOM mapping set whose `mapping_date` is each mapping's true first appearance.
+The path is chosen automatically: datasources with a versioned archive are
+walked release by release, while those without one (NCBI, VGNC) are covered in a
+single fast pass over the current release:
 
 ```bash
-pysec2pri chebi consolidate --mode release   # walks ~250 ChEBI releases; slow, run as a one-off
-pysec2pri hgnc consolidate --mode date       # fast: uses HGNC's own per-row date
+pysec2pri chebi consolidate   # walks ~250 ChEBI releases (versioned archive); slow, run as a one-off
+pysec2pri ncbi consolidate    # single fast pass (no versioned archive)
 ```
 
 Supported for `chebi`, `ensembl`, `hgnc`, `ncbi`, `uniprot`, and `vgnc`. Ensembl

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

@@ -7,7 +7,7 @@ build-backend = "uv_build"
 
 [project]
 name = "pysec2pri"
-version = "0.2.3"
+version = "0.2.4"
 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.1.1",
+    "mapkgsutils==0.1.2",
 ]
 
 # 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.3"
+current_version = "0.2.4"
 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.3 → pysec2pri-0.2.4}/src/pysec2pri/__init__.py

@@ -33,6 +33,17 @@ from pysec2pri.api import (
     generate_wikidata,
     generate_wikidata_labels,
     list_versions,
+    load_chebi,
+    load_ensembl,
+    load_hgnc,
+    load_hmdb,
+    load_hmdb_proteins,
+    load_label_mapping,
+    load_mapping,
+    load_ncbi,
+    load_uniprot,
+    load_vgnc,
+    load_wikidata,
     resolve_ids,
     resolve_labels,
     write_json,
@@ -101,6 +112,17 @@ __all__ = [
     "generate_wikidata",
     "generate_wikidata_labels",
     "list_versions",
+    "load_chebi",
+    "load_ensembl",
+    "load_hgnc",
+    "load_hmdb",
+    "load_hmdb_proteins",
+    "load_label_mapping",
+    "load_mapping",
+    "load_ncbi",
+    "load_uniprot",
+    "load_vgnc",
+    "load_wikidata",
     "load_xref_mapping",
     "resolve_ambiguous_with_hints",
     "resolve_ids",

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

@@ -86,8 +86,17 @@ __all__ = [
     "generate_wikidata_labels",
     "generate_wikidata_labels",
     "list_versions",
+    "load_chebi",
+    "load_ensembl",
+    "load_hgnc",
+    "load_hmdb",
+    "load_hmdb_proteins",
     "load_label_mapping",
     "load_mapping",
+    "load_ncbi",
+    "load_uniprot",
+    "load_vgnc",
+    "load_wikidata",
     "load_xref_mapping",
     "resolve_ids",
     "resolve_labels",
@@ -1503,95 +1512,139 @@ def write_diff_output(
 
 
 def load_mapping(path: Path | str) -> IdMappingSet:
-    """Load an ID mapping set from a pysec2pri TSV file.
+    """Load an ID mapping set from an SSSOM TSV file.
 
-    Accepts the ``sec2pri`` TSV format (columns ``subject_id``, ``object_id``,
-    ``predicate_id``, ``mapping_cardinality``) and the full SSSOM TSV format
-    (comment-prefixed metadata lines are skipped automatically).
+    Produces the same :class:`~pysec2pri.parsers.base.IdMappingSet` a fresh
+    parse would, ready to pass to :func:`resolve_ids`.
 
     Args:
-        path: Path to the TSV file to load.
-
-    Returns:
-        An :class:`~pysec2pri.parsers.base.IdMappingSet` populated from the
-        file, ready to pass to :func:`resolve_ids`.
+        path: Path to the SSSOM TSV file to load.
     """
-    import pandas as pd
-    from sssom_schema import Mapping
+    from mapkgsutils.exports import read_sssom
 
-    path = Path(path)
-    df = pd.read_csv(path, sep="\t", dtype=str, comment="#")
-    ms = IdMappingSet(
-        mapping_set_id=str(path),
-        license="https://creativecommons.org/licenses/by/4.0/",
-    )
-    mappings: list[Mapping] = []
-    for _, row in df.iterrows():
-        m = Mapping(
-            subject_id=row.get("subject_id") or "",
-            object_id=row.get("object_id") or "",
-            predicate_id=row.get("predicate_id") or "",
-            mapping_justification=row.get("mapping_justification")
-            or "semapv:BackgroundKnowledgeBasedMatching",
-            mapping_cardinality=row.get("mapping_cardinality") or None,
-        )
-        mappings.append(m)
-    ms.mappings = mappings
-    return ms
+    return read_sssom(path, mapping_set_class=IdMappingSet, on="id")
 
 
 def load_label_mapping(path: Path | str) -> LabelMappingSet:
-    """Load a label/label mapping set from a pysec2pri TSV file.
+    """Load a label mapping set from an SSSOM TSV file.
+
+    Produces the same :class:`~pysec2pri.parsers.base.LabelMappingSet` a fresh
+    parse would, ready to pass to :func:`resolve_labels`.
+
+    Args:
+        path: Path to the SSSOM TSV file to load.
+    """
+    from mapkgsutils.exports import read_sssom
 
-    Accepts two column-name conventions:
+    return read_sssom(path, mapping_set_class=LabelMappingSet, on="label")
 
-    - **New** (``label_sec2pri`` tabular output): ``secondary_id``,
-      ``secondary_label``, ``primary_id``, ``primary_label``,
-      ``predicate_id``, ``mapping_cardinality``.
-    - **Legacy** (SSSOM or old tabular output): ``subject_id``,
-      ``subject_label``, ``object_id``, ``object_label``, ``predicate_id``.
 
-    Full SSSOM TSV (comment-prefixed metadata lines) is also accepted.
+def load_chebi(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load a ChEBI SSSOM file into the proper mapping set object.
 
     Args:
-        path: Path to the TSV file to load.
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import ChEBIParser
 
-    Returns:
-        A :class:`~pysec2pri.parsers.base.LabelMappingSet` populated from
-        the file, ready to pass to :func:`resolve_labels`.
+    return ChEBIParser().load(path, mapping_type=mapping_type)
+
+
+def load_ensembl(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load an Ensembl SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
     """
-    import pandas as pd
-    from sssom_schema import Mapping
+    from pysec2pri.parsers import EnsemblParser
 
-    path = Path(path)
-    df = pd.read_csv(path, sep="\t", dtype=str, comment="#")
-    ms = LabelMappingSet(
-        mapping_set_id=str(path),
-        license="https://creativecommons.org/licenses/by/4.0/",
-    )
+    return EnsemblParser().load(path, mapping_type=mapping_type)
 
-    def _col(row: pd.Series, *names: str) -> str | None:
-        for name in names:
-            val = row.get(name)
-            if val and str(val).strip():
-                return str(val).strip()
-        return None
-
-    mappings: list[Mapping] = []
-    for _, row in df.iterrows():
-        m = Mapping(
-            subject_id=_col(row, "secondary_id", "subject_id") or "",
-            subject_label=_col(row, "secondary_label", "subject_label"),
-            object_id=_col(row, "primary_id", "object_id") or "",
-            object_label=_col(row, "primary_label", "object_label"),
-            predicate_id=_col(row, "predicate_id") or "",
-            mapping_justification=_col(row, "mapping_justification")
-            or "semapv:BackgroundKnowledgeBasedMatching",
-            mapping_cardinality=_col(row, "mapping_cardinality"),
-        )
-        mappings.append(m)
-    ms.mappings = mappings
-    return ms
+
+def load_hgnc(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load an HGNC SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import HGNCParser
+
+    return HGNCParser().load(path, mapping_type=mapping_type)
+
+
+def load_ncbi(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load an NCBI SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import NCBIParser
+
+    return NCBIParser().load(path, mapping_type=mapping_type)
+
+
+def load_uniprot(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load a UniProt SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import UniProtParser
+
+    return UniProtParser().load(path, mapping_type=mapping_type)
+
+
+def load_vgnc(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load a VGNC SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import VGNCParser
+
+    return VGNCParser().load(path, mapping_type=mapping_type)
+
+
+def load_hmdb(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load an HMDB metabolite SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import HMDBMetaboliteParser
+
+    return HMDBMetaboliteParser().load(path, mapping_type=mapping_type)
+
+
+def load_hmdb_proteins(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load an HMDB protein SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import HMDBProteinParser
+
+    return HMDBProteinParser().load(path, mapping_type=mapping_type)
+
+
+def load_wikidata(path: Path | str, *, mapping_type: str | None = None) -> BaseMappingSet:
+    """Load a Wikidata SSSOM file into the proper mapping set object.
+
+    Args:
+        path: Path to the SSSOM TSV file.
+        mapping_type: ``"id"``/``"label"`` to force the class, else inferred.
+    """
+    from pysec2pri.parsers import WikidataParser
+
+    return WikidataParser().load(path, mapping_type=mapping_type)
 
 
 def resolve_ids(

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

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