crossref-matcher 1.2.2__tar.gz → 1.3.1__tar.gz

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1}/MANIFEST.in

@@ -1,5 +1,6 @@
 include crossref_matcher/resources/plugins.json
 include crossref_matcher/resources/VERSION.txt
+recursive-include crossref_matcher/strategies *.txt
 recursive-include crossref_matcher/resources/data/models *.pkl *.gz *.local
 recursive-include crossref_matcher/resources/data/common_ror_endings *.txt
 recursive-include crossref_matcher/resources/data/countries *.txt

{crossref_matcher-1.2.2/crossref_matcher.egg-info → crossref_matcher-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crossref-matcher
-Version: 1.2.2
+Version: 1.3.1
 Summary: Crossref's matching API
 Home-page: https://gitlab.com/crossref/marple
 Author: Crossref

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1}/README.md

@@ -135,6 +135,49 @@ Strategies are located in the [strategies directory](crossref_matcher/strategies
 
 Strategies must be added to the "enabled" list in [plugins.json](crossref_matcher/resources/plugins.json) before they can be used.
 
+### Strategy versioning
+
+Each strategy directory can contain a `version.txt` file with a two-part version number (`MAJOR.MINOR`). This versioning is independent of the project's semver.
+
+```
+crossref_matcher/strategies/preprint/sbmv/
+├── strategy.py
+└── version.txt        # contains e.g. "1.2"
+```
+
+When a strategy is loaded, its version is automatically available as a class attribute:
+
+```python
+from crossref_matcher.strategies.preprint.sbmv.strategy import Sbmv
+print(Sbmv.version)  # "1.2"
+```
+
+Strategies without a `version.txt` have `version = None`.
+
+**Bumping a version:**
+
+```sh
+python scripts/bump_strategy_version.py preprint/sbmv minor   # 1.2 → 1.3
+python scripts/bump_strategy_version.py preprint/sbmv major   # 1.2 → 2.0
+```
+
+The path argument can be relative to the `strategies/` directory or an absolute path.
+
+**CI enforcement:**
+
+A CI job (`check-strategy-versions` in `.gitlab-ci.yml`) fails any merge request where a strategy's files are changed but `version.txt` is not updated. To bypass for a trivial change (e.g. a typo fix):
+
+- Pass `--force` to the check script, or
+- Set the `SKIP_BUMP_CHECK=1` environment variable on the pipeline run.
+
+**Local pre-commit hook:**
+
+To enable the check locally (as a non-blocking warning):
+
+```sh
+git config core.hooksPath .githooks
+```
+
 ### Dependencies
 
 Requirements are defined in `setup.py`. Requirements files with exact versions can be updated with `pip-compile`, which is a part of `pip-tools`. First run `pip install pip-tools`. Then:

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1}/crossref_matcher/evaluation/evaluation.py

@@ -176,15 +176,29 @@ class EvaluateSklearn:
         self.mlb.fit(y_true + y_pred)
         y_true_transformed = self.mlb.transform(y_true)
         y_pred_transformed = self.mlb.transform(y_pred)
-        at = y_true_transformed.toarray()
-        af = y_pred_transformed.toarray()
-        false_positives = int((af & (1 - at)).sum())
-        false_negatives = int((at & (1 - af)).sum())
+        # Stay in sparse representation: with large label spaces (e.g. grant
+        # IDs), densifying via .toarray() blows up memory/time since the
+        # dense matrix is n_samples x n_unique_labels.
+        true_positives = y_true_transformed.multiply(y_pred_transformed).sum()
+        false_positives = int(y_pred_transformed.sum() - true_positives)
+        false_negatives = int(y_true_transformed.sum() - true_positives)
+        # sklearn's type_of_target() requires >1 column to classify a target
+        # as "multilabel-indicator" (native sparse support); with exactly one
+        # label column it's classified as "binary" instead, which sklearn
+        # handles via column_or_1d(), and that rejects sparse input outright.
+        # Densify just for that narrow edge case (cheap, since there's only
+        # one column).
+        if y_true_transformed.shape[1] <= 1:
+            y_true_for_fscore = y_true_transformed.toarray()
+            y_pred_for_fscore = y_pred_transformed.toarray()
+        else:
+            y_true_for_fscore = y_true_transformed
+            y_pred_for_fscore = y_pred_transformed
         f_scores = []
         for beta in f_score_betas:
             precision, recall, fscore, _ = precision_recall_fscore_support(
-                at,
-                af,
+                y_true_for_fscore,
+                y_pred_for_fscore,
                 average="micro",
                 zero_division=0.0,
                 sample_weight=sample_weights,
@@ -352,7 +366,7 @@ def run_strategy_on_eval_data(
             extra_data = extra_fn(strategy, data_point, this_result)
             out_item["extra"].update(extra_data)
 
-        if hasattr(data_point, "alternates"):
+        if hasattr(data_point, "alternates") and len(data_point.alternates) > 0:
             dataset_has_alternates = True
             out_item["alternates"] = data_point.alternates
         this_weight = getattr(data_point, "weight", 1.0)

crossref_matcher-1.3.1/crossref_matcher/evaluation/sparse_metrics_verification/verify_sparse_metrics.py

@@ -0,0 +1,239 @@
+"""Reproduces the investigation behind the sparse-matrix rewrite of
+`EvaluateSklearn.run_one_evaluation` in `crossref_matcher/evaluation/evaluation.py`.
+
+Run directly to reproduce all findings:
+
+    python -m crossref_matcher.evaluation.sparse_metrics_verification.verify_sparse_metrics
+
+See README.md in this directory for the narrative writeup of what each
+check demonstrates.
+"""
+
+import random
+import time
+import tracemalloc
+
+import numpy as np
+from sklearn.metrics import precision_recall_fscore_support
+from sklearn.preprocessing import MultiLabelBinarizer
+from sklearn.utils.multiclass import type_of_target
+
+
+def old_dense_false_positives_negatives(at_sparse, af_sparse):
+    """The original implementation: densify, then bitwise AND."""
+    at = at_sparse.toarray()
+    af = af_sparse.toarray()
+    false_positives = int((af & (1 - at)).sum())
+    false_negatives = int((at & (1 - af)).sum())
+    return false_positives, false_negatives
+
+
+def new_sparse_false_positives_negatives(at_sparse, af_sparse):
+    """The replacement implementation: stay sparse throughout."""
+    true_positives = at_sparse.multiply(af_sparse).sum()
+    false_positives = int(af_sparse.sum() - true_positives)
+    false_negatives = int(at_sparse.sum() - true_positives)
+    return false_positives, false_negatives
+
+
+def fscore_inputs(at_sparse, af_sparse):
+    """Mirrors the shape[1] <= 1 densify branch added to run_one_evaluation."""
+    if at_sparse.shape[1] <= 1:
+        return at_sparse.toarray(), af_sparse.toarray()
+    return at_sparse, af_sparse
+
+
+def check_equivalence(trials: int = 500, seed: int = 42) -> int:
+    """Fuzz-tests old (dense bitwise) vs. new (sparse) false_positives /
+    false_negatives / precision / recall / f-score against each other over
+    randomized multi-label data, including empty label sets and duplicate
+    labels within a single sample.
+
+    Returns the number of mismatches found (0 means full equivalence).
+    """
+    rng = random.Random(seed)
+    mismatches = 0
+    checked = 0
+
+    for trial in range(trials):
+        n_samples = rng.randint(1, 8)
+        vocab = [f"id{i}" for i in range(rng.randint(1, 6))]
+        y_true, y_pred = [], []
+        for _ in range(n_samples):
+            yt = rng.sample(vocab, k=rng.randint(0, len(vocab)))
+            if yt and rng.random() < 0.3:
+                yt = yt + [yt[0]]  # duplicate label within a sample
+            yp = rng.sample(vocab, k=rng.randint(0, len(vocab)))
+            y_true.append(yt)
+            y_pred.append(yp)
+
+        if not any(y_true) and not any(y_pred):
+            continue  # matches the early-return "all empty" branch in evaluation.py
+
+        mlb = MultiLabelBinarizer(sparse_output=True)
+        mlb.fit(y_true + y_pred)
+        at_sparse = mlb.transform(y_true)
+        af_sparse = mlb.transform(y_pred)
+
+        checked += 1
+
+        fp_old, fn_old = old_dense_false_positives_negatives(at_sparse, af_sparse)
+        fp_new, fn_new = new_sparse_false_positives_negatives(at_sparse, af_sparse)
+        if (fp_old, fn_old) != (fp_new, fn_new):
+            mismatches += 1
+            print(f"  MISMATCH (fp/fn) trial={trial} y_true={y_true} y_pred={y_pred}")
+            print(f"    old: fp={fp_old} fn={fn_old}  new: fp={fp_new} fn={fn_new}")
+
+        at_dense, af_dense = at_sparse.toarray(), af_sparse.toarray()
+        p_old, r_old, f_old, _ = precision_recall_fscore_support(
+            at_dense, af_dense, average="micro", zero_division=0.0, beta=1.0
+        )
+        yt_new, yp_new = fscore_inputs(at_sparse, af_sparse)
+        p_new, r_new, f_new, _ = precision_recall_fscore_support(
+            yt_new, yp_new, average="micro", zero_division=0.0, beta=1.0
+        )
+        if not np.allclose([p_old, r_old, f_old], [p_new, r_new, f_new]):
+            mismatches += 1
+            print(f"  MISMATCH (fscore) trial={trial} y_true={y_true} y_pred={y_pred}")
+            print(f"    old: p={p_old} r={r_old} f={f_old}")
+            print(f"    new: p={p_new} r={r_new} f={f_new}")
+
+    print(
+        f"[equivalence] checked {checked} non-trivial trials, {mismatches} mismatches"
+    )
+    return mismatches
+
+
+def check_single_column_edge_case() -> None:
+    """Demonstrates why a densify fallback is needed when there is only one
+    unique label across a batch: sklearn's type_of_target() requires more
+    than one column to classify a target as "multilabel-indicator" (which
+    has native sparse support). With exactly one column it's classified as
+    "binary" instead, and sklearn's binary-handling path (column_or_1d)
+    rejects sparse input outright -- regardless of dense vs sparse, the
+    *classification* is the same; only the *acceptance* of sparse input
+    differs downstream.
+    """
+    mlb = MultiLabelBinarizer(sparse_output=True)
+    y_true = [["a"], []]
+    y_pred = [["a"], ["a"]]
+    mlb.fit(y_true + y_pred)
+    at_sparse = mlb.transform(y_true)
+    af_sparse = mlb.transform(y_pred)
+    at_dense, af_dense = at_sparse.toarray(), af_sparse.toarray()
+
+    print(f"[single-column] shape={at_sparse.shape}")
+    print(f"  type_of_target(sparse) = {type_of_target(at_sparse)!r}")
+    print(f"  type_of_target(dense)  = {type_of_target(at_dense)!r}")
+
+    try:
+        precision_recall_fscore_support(
+            at_sparse, af_sparse, average="micro", zero_division=0.0, beta=1.0
+        )
+        print("  sparse input: unexpectedly succeeded")
+    except TypeError as e:
+        print(f"  sparse input raises TypeError: {e}")
+
+    p, r, f, _ = precision_recall_fscore_support(
+        at_dense, af_dense, average="micro", zero_division=0.0, beta=1.0
+    )
+    print(f"  dense input succeeds: precision={p} recall={r} fscore={f}")
+
+
+def check_sample_weight_equivalence() -> None:
+    """Confirms sample_weight produces identical results for sparse vs. dense
+    once the label space has more than one column (the common case)."""
+    mlb = MultiLabelBinarizer(sparse_output=True)
+    y_true = [["a", "b"], ["c"]]
+    y_pred = [["a"], ["c", "d"]]
+    mlb.fit(y_true + y_pred)
+    at_sparse = mlb.transform(y_true)
+    af_sparse = mlb.transform(y_pred)
+    weights = [2.0, 3.0]
+
+    p1, r1, f1, _ = precision_recall_fscore_support(
+        at_sparse,
+        af_sparse,
+        average="micro",
+        zero_division=0.0,
+        beta=1.0,
+        sample_weight=weights,
+    )
+    p2, r2, f2, _ = precision_recall_fscore_support(
+        at_sparse.toarray(),
+        af_sparse.toarray(),
+        average="micro",
+        zero_division=0.0,
+        beta=1.0,
+        sample_weight=weights,
+    )
+    print(f"[sample_weight] sparse: precision={p1} recall={r1} fscore={f1}")
+    print(f"[sample_weight] dense:  precision={p2} recall={r2} fscore={f2}")
+    assert np.allclose([p1, r1, f1], [p2, r2, f2])
+
+
+def benchmark_dense_vs_sparse(n_samples: int = 2000, n_labels: int = 20000) -> None:
+    """Demonstrates the actual cost of `.toarray()` that motivated this fix:
+    a label-indicator matrix scales as n_samples x n_unique_labels, which for
+    a large ID space (e.g. grant DOIs) becomes very large very fast, even
+    though the underlying data is highly sparse (each sample only has a
+    handful of true/predicted labels)."""
+    rng = random.Random(7)
+    vocab = [f"id{i}" for i in range(n_labels)]
+    y_true = [rng.sample(vocab, k=rng.randint(0, 3)) for _ in range(n_samples)]
+    y_pred = [rng.sample(vocab, k=rng.randint(0, 3)) for _ in range(n_samples)]
+
+    mlb = MultiLabelBinarizer(sparse_output=True)
+    mlb.fit(y_true + y_pred)
+    at_sparse = mlb.transform(y_true)
+    af_sparse = mlb.transform(y_pred)
+    print(
+        f"[benchmark] n_samples={n_samples} n_labels={n_labels} "
+        f"matrix shape={at_sparse.shape}"
+    )
+
+    tracemalloc.start()
+    start = time.perf_counter()
+    old_dense_false_positives_negatives(at_sparse, af_sparse)
+    dense_time = time.perf_counter() - start
+    _, dense_peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    tracemalloc.start()
+    start = time.perf_counter()
+    new_sparse_false_positives_negatives(at_sparse, af_sparse)
+    sparse_time = time.perf_counter() - start
+    _, sparse_peak = tracemalloc.get_traced_memory()
+    tracemalloc.stop()
+
+    print(
+        f"[benchmark] dense (.toarray) : {dense_time:.3f}s, "
+        f"peak extra memory {dense_peak / 1e6:.1f} MB"
+    )
+    print(
+        f"[benchmark] sparse (.multiply): {sparse_time:.3f}s, "
+        f"peak extra memory {sparse_peak / 1e6:.1f} MB"
+    )
+
+
+def main() -> None:
+    print(
+        "== 1. Old vs. new false_positives/false_negatives/precision/recall/f-score equivalence =="
+    )
+    mismatches = check_equivalence()
+
+    print("\n== 2. Single-label-column edge case (why the densify fallback exists) ==")
+    check_single_column_edge_case()
+
+    print("\n== 3. sample_weight equivalence (sparse vs. dense) ==")
+    check_sample_weight_equivalence()
+
+    print("\n== 4. Benchmark: dense .toarray() vs. sparse, large label space ==")
+    benchmark_dense_vs_sparse()
+
+    print("\n== Summary ==")
+    print(f"Equivalence mismatches: {mismatches} (expect 0)")
+
+
+if __name__ == "__main__":
+    main()

crossref_matcher-1.3.1/crossref_matcher/resources/VERSION.txt

@@ -0,0 +1 @@
+1.3.1

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1}/crossref_matcher/strategies/__init__.py

@@ -20,17 +20,25 @@ import logging
 
 logger = logging.getLogger(__name__)
 
+STRATEGIES_DIR = "crossref_matcher/strategies"
 
-def pascal_to_snake_case(s):
+
+def pascal_to_snake_case(s: str) -> str:
     return re.sub(r"(?<!^)(?=[A-Z])", "_", s).lower()
 
 
-def kebab_to_snake_case(string: str) -> str:
+def kebab_to_snake_case(string: str | None) -> str | None:
     if string is None:
         return None
     return "_".join(string.split("-"))
 
 
+def snake_to_kebab_case(string: str | None) -> str | None:
+    if string is None:
+        return None
+    return "-".join(string.split("_"))
+
+
 class NoDefaultStrategyError(ValueError):
     """Raised when no default strategy is configured for a task."""
 
@@ -57,6 +65,7 @@ class Strategy(ABC):
     id: str
     task: MatchTask
     description: str
+    version: str | None = None
 
     @classmethod
     def create_dummy_subclass(cls, module_name: str, error: str):
@@ -230,6 +239,13 @@ class Strategy(ABC):
                 raise TypeError(
                     f"Class {cls.__name__} must have a class field '{name}' of type {type.__name__}."
                 )
+        try:
+            pkg = cls.__module__.removesuffix(".strategy")
+            version_ref = resources.files(pkg) / "version.txt"
+            if version_ref.is_file():
+                cls.version = version_ref.read_text().strip()
+        except (TypeError, OSError, ModuleNotFoundError):
+            pass
 
     @classmethod
     def is_default(cls):
@@ -274,7 +290,7 @@ def list_strategies(
 
 
 def get_strategy_by_id(
-    strategy_id: str | None,
+    strategy_id: str | None = None,
     task: MatchTask | str | None = None,
     allow_disabled: bool = False,
 ) -> type[Strategy]:
@@ -298,7 +314,11 @@ def get_strategy_by_id(
             raise ValueError("Must specify at least one of [strategy_id, task]")
         return get_default_strategy(task)
     strategy_found = False
-    for id_to_check in [strategy_id, kebab_to_snake_case(strategy_id)]:
+    for id_to_check in [
+        strategy_id,
+        kebab_to_snake_case(strategy_id),
+        snake_to_kebab_case(strategy_id),
+    ]:
         strategy = [
             c
             for c in list_strategies(task=task, include_disabled=allow_disabled)
@@ -354,7 +374,7 @@ def get_strategy_by_module_name(
 
 
 def get_strategy(
-    strategy_id: str | None,
+    strategy_id: str | None = None,
     task: MatchTask | str | None = None,
     allow_disabled: bool = False,
 ) -> type[Strategy]:

crossref_matcher-1.3.1/crossref_matcher/strategies/funder/funder_name_to_ror_search/version.txt

@@ -0,0 +1 @@
+1.0

crossref_matcher-1.3.1/crossref_matcher/strategies/versioning.py

@@ -0,0 +1,77 @@
+import logging
+import subprocess
+from pathlib import PurePosixPath
+
+from crossref_matcher.strategies import STRATEGIES_DIR
+
+logger = logging.getLogger(__name__)
+
+_STRATEGIES_PATH = PurePosixPath(STRATEGIES_DIR)
+
+
+def _strategy_dir(path: str) -> str | None:
+    """Return 'task/strategy' for a path inside the strategies dir, or None."""
+    try:
+        rel = PurePosixPath(path).relative_to(_STRATEGIES_PATH)
+    except ValueError:
+        return None
+    if len(rel.parts) < 3:  # need task / strategy / filename at minimum
+        return None
+    return f"{rel.parts[0]}/{rel.parts[1]}"
+
+
+def get_changed_files(base: str | None, staged: bool) -> list[str]:
+    if staged:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "--name-only"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    elif base:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", f"{base}...HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    else:
+        raise ValueError("Must specify --base or --staged")
+    return result.stdout.splitlines()
+
+
+def get_changed_strategy_dirs(changed_files: list[str]) -> set[str]:
+    return {
+        _strategy_dir(f)
+        for f in changed_files
+        if PurePosixPath(f).name != "version.txt"
+        if _strategy_dir(f) is not None
+    }
+
+
+def check(base: str | None, staged: bool) -> bool:
+    changed_files = get_changed_files(base, staged)
+    changed_dirs = get_changed_strategy_dirs(changed_files)
+
+    if not changed_dirs:
+        return True
+
+    bumped_dirs = {
+        _strategy_dir(f)
+        for f in changed_files
+        if PurePosixPath(f).name == "version.txt"
+        if _strategy_dir(f) is not None
+    }
+
+    failures = sorted(changed_dirs - bumped_dirs)
+    if failures:
+        missing = "\n".join(f"  {STRATEGIES_DIR}/{d}/version.txt" for d in failures)
+        logger.error(
+            "The following strategies have changes but no version bump:\n%s\n"
+            "\nRun: python scripts/bump_strategy_version.py <strategy-path> <major|minor>"
+            "\nTo skip: rerun with --force, or set SKIP_BUMP_CHECK=1",
+            missing,
+        )
+        return False
+
+    return True

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1/crossref_matcher.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: crossref-matcher
-Version: 1.2.2
+Version: 1.3.1
 Summary: Crossref's matching API
 Home-page: https://gitlab.com/crossref/marple
 Author: Crossref

{crossref_matcher-1.2.2 → crossref_matcher-1.3.1}/crossref_matcher.egg-info/SOURCES.txt

@@ -20,6 +20,8 @@ crossref_matcher/evaluation/evaluation.py
 crossref_matcher/evaluation/google_sheets_connector.py
 crossref_matcher/evaluation/ror_utils.py
 crossref_matcher/evaluation/schemas.py
+crossref_matcher/evaluation/sparse_metrics_verification/__init__.py
+crossref_matcher/evaluation/sparse_metrics_verification/verify_sparse_metrics.py
 crossref_matcher/indexes/__init__.py
 crossref_matcher/indexes/preprint_matching/__init__.py
 crossref_matcher/indexes/preprint_matching/indexer_service.py
@@ -69,6 +71,7 @@ crossref_matcher/resources/data/models/reference_nn_unstructured/eval/events.out
 crossref_matcher/resources/data/models/reference_nn_unstructured/train/events.out.tfevents.1681511550.knopfler.local
 crossref_matcher/strategies/__init__.py
 crossref_matcher/strategies/common.py
+crossref_matcher/strategies/versioning.py
 crossref_matcher/strategies/affiliation/__init__.py
 crossref_matcher/strategies/affiliation/es_utils.py
 crossref_matcher/strategies/affiliation/matching.py
@@ -80,6 +83,7 @@ crossref_matcher/strategies/affiliation/single_search/strategy.py
 crossref_matcher/strategies/funder/__init__.py
 crossref_matcher/strategies/funder/funder_name_to_ror_search/__init__.py
 crossref_matcher/strategies/funder/funder_name_to_ror_search/strategy.py
+crossref_matcher/strategies/funder/funder_name_to_ror_search/version.txt
 crossref_matcher/strategies/healthcheck/__init__.py
 crossref_matcher/strategies/healthcheck/healthcheck/__init__.py
 crossref_matcher/strategies/healthcheck/healthcheck/strategy.py

crossref_matcher-1.2.2/crossref_matcher/resources/VERSION.txt

@@ -1 +0,0 @@
-1.2.2