copairs 0.4.1__py3-none-any.whl

copairs/__init__.py

@@ -0,0 +1,4 @@
+"""
+Package to create pairwise lists based on sameby and diffby criteria
+"""
+from .matching import Matcher, MatcherMultilabel

copairs/compute.py

@@ -0,0 +1,199 @@
+import itertools
+import os
+from multiprocessing.pool import ThreadPool
+from pathlib import Path
+from typing import Callable
+
+import numpy as np
+from tqdm.autonotebook import tqdm
+
+
+def parallel_map(par_func, items):
+    """Execute par_func(i) for every i in items using ThreadPool and tqdm."""
+    num_items = len(items)
+    pool_size = min(num_items, os.cpu_count())
+    chunksize = num_items // pool_size
+    with ThreadPool(pool_size) as pool:
+        tasks = pool.imap_unordered(par_func, items, chunksize=chunksize)
+        for _ in tqdm(tasks, total=len(items), leave=False):
+            pass
+
+
+def batch_processing(
+    pairwise_op: Callable[[np.ndarray, np.ndarray], np.ndarray],
+):
+    """Decorator adding the batch_size param to run the function with
+    multithreading using a list of paired indices"""
+
+    def batched_fn(feats: np.ndarray, pair_ix: np.ndarray, batch_size: int):
+        num_pairs = len(pair_ix)
+        result = np.empty(num_pairs, dtype=np.float32)
+
+        def par_func(i):
+            x_sample = feats[pair_ix[i : i + batch_size, 0]]
+            y_sample = feats[pair_ix[i : i + batch_size, 1]]
+            result[i : i + len(x_sample)] = pairwise_op(x_sample, y_sample)
+
+        parallel_map(par_func, np.arange(0, num_pairs, batch_size))
+
+        return result
+
+    return batched_fn
+
+
+@batch_processing
+def pairwise_corr(x_sample: np.ndarray, y_sample: np.ndarray) -> np.ndarray:
+    """
+    Compute pearson correlation between two matrices in a paired row-wise
+    fashion. `x_sample` and `y_sample` must be of the same shape.
+    """
+    x_mean = x_sample.mean(axis=1, keepdims=True)
+    y_mean = y_sample.mean(axis=1, keepdims=True)
+
+    x_center = x_sample - x_mean
+    y_center = y_sample - y_mean
+
+    numer = (x_center * y_center).sum(axis=1)
+
+    denom = (x_center**2).sum(axis=1) * (y_center**2).sum(axis=1)
+    denom = np.sqrt(denom)
+
+    corrs = numer / denom
+    return corrs
+
+
+@batch_processing
+def pairwise_cosine(x_sample: np.ndarray, y_sample: np.ndarray) -> np.ndarray:
+    x_norm = x_sample / np.linalg.norm(x_sample, axis=1)[:, np.newaxis]
+    y_norm = y_sample / np.linalg.norm(y_sample, axis=1)[:, np.newaxis]
+    c_sim = np.sum(x_norm * y_norm, axis=1)
+    return c_sim
+
+
+def random_binary_matrix(n, m, k, rng):
+    """Generate a random binary matrix of n*m with exactly k values in 1 per row.
+    Args:
+    n: Number of rows.
+    m: Number of columns.
+    k: Number of 1's per row.
+
+    Returns:
+    A: Random binary matrix of n*m with exactly k values in 1 per row.
+    """
+    matrix = np.zeros((n, m), dtype=int)
+    matrix[:, :k] = 1
+    rng.permuted(matrix, axis=1, out=matrix)
+    return matrix
+
+
+def average_precision(rel_k) -> np.ndarray:
+    """Compute average precision based on binary list sorted by relevance"""
+    tp = np.cumsum(rel_k, axis=1)
+    num_pos = tp[:, -1]
+    k = np.arange(1, rel_k.shape[1] + 1)
+    pr_k = tp / k
+    ap = (pr_k * rel_k).sum(axis=1) / num_pos
+    return ap
+
+
+def ap_contiguous(rel_k_list, counts):
+    """Compute average precision from a list of contiguous values"""
+    cutoffs = to_cutoffs(counts)
+
+    num_pos = np.add.reduceat(rel_k_list, cutoffs)
+    shift = np.empty_like(num_pos)
+    shift[0], shift[1:] = 0, num_pos[:-1]
+
+    tp = rel_k_list.cumsum() - np.repeat(shift.cumsum(), counts)
+    k = np.arange(1, len(rel_k_list) + 1) - np.repeat(cutoffs, counts)
+
+    pr_k = tp / k
+    ap_scores = np.add.reduceat(pr_k * rel_k_list, cutoffs) / num_pos
+    null_confs = np.stack([num_pos, counts], axis=1)
+    return ap_scores, null_confs
+
+
+def random_ap(num_perm: int, num_pos: int, total: int, seed) -> np.ndarray:
+    """Compute multiple average_precision scores generated at random"""
+    rng = np.random.default_rng(seed)
+    rel_k = random_binary_matrix(num_perm, total, num_pos, rng)
+    null_dist = average_precision(rel_k)
+    return null_dist
+
+
+def null_dist_cached(num_pos, total, seed, null_size, cache_dir):
+    if seed is not None:
+        cache_file = cache_dir / f"n{total}_k{num_pos}.npy"
+        if cache_file.is_file():
+            null_dist = np.load(cache_file)
+        else:
+            null_dist = random_ap(null_size, num_pos, total, seed)
+            np.save(cache_file, null_dist)
+    else:
+        null_dist = random_ap(null_size, num_pos, total, seed)
+    return null_dist
+
+
+def get_null_dists(confs, null_size, seed):
+    cache_dir = Path.home() / ".copairs" / f"seed{seed}" / f"ns{null_size}"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    num_confs = len(confs)
+    rng = np.random.default_rng(seed)
+    seeds = rng.integers(8096, size=num_confs)
+
+    null_dists = np.empty([len(confs), null_size], dtype=np.float32)
+
+    def par_func(i):
+        num_pos, total = confs[i]
+        null_dists[i] = null_dist_cached(num_pos, total, seeds[i], null_size, cache_dir)
+
+    parallel_map(par_func, np.arange(num_confs))
+    return null_dists
+
+
+def p_values(ap_scores: np.ndarray, null_confs: np.ndarray, null_size: int, seed: int):
+    """Calculate p values for an array of ap_scores and null configurations. It uses the path
+    folder to cache null calculations.
+
+    Parameters
+    ----------
+    ap_scores : np.ndarray
+        Ap scores for which to calculate p value.
+    null_confs : np.ndarray
+        Number of average precisions calculated. It serves as an indicator of
+        how relevant is the resultant score.
+    null_size : int
+    seed : int
+        Random initializing value.
+
+    Examples
+    --------
+    FIXME: Add docs.
+
+
+    """
+    confs, rev_ix = np.unique(null_confs, axis=0, return_inverse=True)
+    null_dists = get_null_dists(confs, null_size, seed)
+    null_dists.sort(axis=1)
+    pvals = np.empty(len(ap_scores), dtype=np.float32)
+    for i, (ap_score, ix) in enumerate(zip(ap_scores, rev_ix)):
+        # Reverse to get from hi to low
+        num = null_size - np.searchsorted(null_dists[ix], ap_score)
+        pvals[i] = (num + 1) / (null_size + 1)
+    return pvals
+
+
+def concat_ranges(start: np.ndarray, end: np.ndarray) -> np.ndarray:
+    """Create a 1-d array concatenating multiple ranges"""
+    slices = map(range, start, end)
+    slices = itertools.chain.from_iterable(slices)
+    count = (end - start).sum()
+    mask = np.fromiter(slices, dtype=np.int32, count=count)
+    return mask
+
+
+def to_cutoffs(counts: np.ndarray):
+    """Convert a list of counts into cutoff indices."""
+    cutoffs = np.empty_like(counts)
+    cutoffs[0], cutoffs[1:] = 0, counts.cumsum()[:-1]
+    return cutoffs

copairs/map/__init__.py

@@ -0,0 +1,3 @@
+from .map import mean_average_precision
+from . import multilabel
+from .average_precision import average_precision

copairs/map/average_precision.py

@@ -0,0 +1,94 @@
+import itertools
+import logging
+
+import numpy as np
+import pandas as pd
+
+from copairs import compute
+from copairs.matching import Matcher, UnpairedException
+
+from .filter import evaluate_and_filter, flatten_str_list, validate_pipeline_input
+
+logger = logging.getLogger("copairs")
+
+
+def build_rank_lists(pos_pairs, neg_pairs, pos_sims, neg_sims):
+    labels = np.concatenate(
+        [
+            np.ones(pos_pairs.size, dtype=np.int32),
+            np.zeros(neg_pairs.size, dtype=np.int32),
+        ]
+    )
+    ix = np.concatenate([pos_pairs.ravel(), neg_pairs.ravel()])
+    sim_all = np.concatenate([np.repeat(pos_sims, 2), np.repeat(neg_sims, 2)])
+    ix_sort = np.lexsort([1 - sim_all, ix])
+    rel_k_list = labels[ix_sort]
+    paired_ix, counts = np.unique(ix, return_counts=True)
+    return paired_ix, rel_k_list, counts
+
+
+def average_precision(
+    meta, feats, pos_sameby, pos_diffby, neg_sameby, neg_diffby, batch_size=20000
+) -> pd.DataFrame:
+    columns = flatten_str_list(pos_sameby, pos_diffby, neg_sameby, neg_diffby)
+    validate_pipeline_input(meta, feats, columns)
+
+    # Critical!, otherwise the indexing wont work
+    meta = meta.reset_index(drop=True).copy()
+    logger.info("Indexing metadata...")
+    matcher = Matcher(*evaluate_and_filter(meta, columns), seed=0)
+
+    logger.info("Finding positive pairs...")
+    pos_pairs = matcher.get_all_pairs(sameby=pos_sameby, diffby=pos_diffby)
+    pos_total = sum(len(p) for p in pos_pairs.values())
+    if pos_total == 0:
+        raise UnpairedException("Unable to find positive pairs.")
+    pos_pairs = np.fromiter(
+        itertools.chain.from_iterable(pos_pairs.values()),
+        dtype=np.dtype((np.int32, 2)),
+        count=pos_total,
+    )
+
+    logger.info("Finding negative pairs...")
+    neg_pairs = matcher.get_all_pairs(sameby=neg_sameby, diffby=neg_diffby)
+    neg_total = sum(len(p) for p in neg_pairs.values())
+    if neg_total == 0:
+        raise UnpairedException("Unable to find negative pairs.")
+    neg_pairs = np.fromiter(
+        itertools.chain.from_iterable(neg_pairs.values()),
+        dtype=np.dtype((np.int32, 2)),
+        count=neg_total,
+    )
+
+    logger.info("Computing positive similarities...")
+    pos_sims = compute.pairwise_cosine(feats, pos_pairs, batch_size)
+
+    logger.info("Computing negative similarities...")
+    neg_sims = compute.pairwise_cosine(feats, neg_pairs, batch_size)
+
+    logger.info("Building rank lists...")
+    paired_ix, rel_k_list, counts = build_rank_lists(
+        pos_pairs, neg_pairs, pos_sims, neg_sims
+    )
+
+    logger.info("Computing average precision...")
+    ap_scores, null_confs = compute.ap_contiguous(rel_k_list, counts)
+
+    logger.info("Creating result DataFrame...")
+    meta["n_pos_pairs"] = 0
+    meta["n_total_pairs"] = 0
+    meta.loc[paired_ix, "average_precision"] = ap_scores
+    meta.loc[paired_ix, "n_pos_pairs"] = null_confs[:, 0]
+    meta.loc[paired_ix, "n_total_pairs"] = null_confs[:, 1]
+    logger.info("Finished.")
+    return meta
+
+
+def p_values(dframe: pd.DataFrame, null_size: int, seed: int):
+    """Compute p-values"""
+    mask = dframe["n_pos_pairs"] > 0
+    pvals = np.full(len(dframe), np.nan, dtype=np.float32)
+    scores = dframe.loc[mask, "average_precision"].values
+    null_confs = dframe.loc[mask, ["n_pos_pairs", "n_total_pairs"]].values
+    pvals[mask] = compute.p_values(scores, null_confs, null_size, seed)
+    return pvals

copairs/map/filter.py

@@ -0,0 +1,51 @@
+import itertools
+import re
+from typing import List, Tuple
+
+import pandas as pd
+import numpy as np
+
+
+def validate_pipeline_input(meta, feats, columns):
+    if meta[columns].isna().any(axis=None):
+        raise ValueError("metadata columns should not have null values.")
+    if len(meta) != len(feats):
+        raise ValueError("meta and feats have different number of rows")
+    if np.isnan(feats).any():
+        raise ValueError("features should not have null values.")
+
+
+def flatten_str_list(*args):
+    """create a single list with all the params given"""
+    columns = set()
+    for col in args:
+        if isinstance(col, str):
+            columns.add(col)
+        elif isinstance(col, dict):
+            columns.update(itertools.chain.from_iterable(col.values()))
+        else:
+            columns.update(col)
+    columns = list(columns)
+    return columns
+
+
+def evaluate_and_filter(df, columns) -> Tuple[pd.DataFrame, List[str]]:
+    """Evaluate the query and filter the dataframe"""
+    parsed_cols = []
+    for col in columns:
+        if col in df.columns:
+            parsed_cols.append(col)
+            continue
+
+        column_names = re.findall(r"(\w+)\s*[=<>!]+", col)
+        valid_column_names = [col for col in column_names if col in df.columns]
+        if not valid_column_names:
+            raise ValueError(f"Invalid query or column name: {col}")
+
+        try:
+            df = df.query(col)
+            parsed_cols.extend(valid_column_names)
+        except:
+            raise ValueError(f"Invalid query expression: {col}")
+
+    return df, parsed_cols

copairs/map/map.py

@@ -0,0 +1,51 @@
+import logging
+
+import numpy as np
+import pandas as pd
+from statsmodels.stats.multitest import multipletests
+from tqdm.contrib.concurrent import thread_map
+
+from copairs import compute
+
+logger = logging.getLogger("copairs")
+
+
+def mean_average_precision(
+    ap_scores: pd.DataFrame, sameby, null_size: int, threshold: float, seed: int
+) -> pd.DataFrame:
+    ap_scores = ap_scores.query("~average_precision.isna() and n_pos_pairs > 0")
+    ap_scores = ap_scores.reset_index(drop=True).copy()
+
+    logger.info("Computing null_dist...")
+    null_confs = ap_scores[["n_pos_pairs", "n_total_pairs"]].values
+    null_confs, rev_ix = np.unique(null_confs, axis=0, return_inverse=True)
+    null_dists = compute.get_null_dists(null_confs, null_size, seed=seed)
+    ap_scores["null_ix"] = rev_ix
+
+    def get_p_value(params):
+        map_score, indices = params
+        null_dist = null_dists[rev_ix[indices]].mean(axis=0)
+        num = (null_dist > map_score).sum()
+        p_value = (num + 1) / (null_size + 1)
+        return p_value
+
+    logger.info("Computing p-values...")
+
+    map_scores = ap_scores.groupby(sameby, observed=True).agg(
+        {
+            "average_precision": ["mean", lambda x: list(x.index)],
+        }
+    )
+    map_scores.columns = ["mean_average_precision", "indices"]
+
+    params = map_scores[["mean_average_precision", "indices"]]
+    map_scores["p_value"] = thread_map(get_p_value, params.values, leave=False)
+    reject, pvals_corrected, alphacSidak, alphacBonf = multipletests(
+        map_scores["p_value"], method="fdr_bh"
+    )
+    map_scores["corrected_p_value"] = pvals_corrected
+    map_scores["below_p"] = map_scores["p_value"] < threshold
+    map_scores["below_corrected_p"] = map_scores["corrected_p_value"] < threshold
+    map_scores.drop(columns=["indices"], inplace=True)
+    map_scores.reset_index(inplace=True)
+    return map_scores

copairs/map/multilabel.py

@@ -0,0 +1,151 @@
+import itertools
+import logging
+
+import numpy as np
+import pandas as pd
+
+from copairs import compute
+from copairs.matching import MatcherMultilabel, UnpairedException
+
+from .filter import evaluate_and_filter, flatten_str_list, validate_pipeline_input
+
+logger = logging.getLogger("copairs")
+
+
+def create_neg_query_solver(neg_pairs, neg_sims):
+    # Melting and sorting by ix. neg_cutoffs splits the contiguous array
+    neg_ix = neg_pairs.ravel()
+    neg_sims = np.repeat(neg_sims, 2)
+
+    sort_ix = np.argsort(neg_ix)
+    neg_sims = neg_sims[sort_ix]
+
+    neg_ix, neg_counts = np.unique(neg_ix, return_counts=True)
+    neg_cutoffs = compute.to_cutoffs(neg_counts)
+
+    def negs_for(query: np.ndarray):
+        locs = np.searchsorted(neg_ix, query)
+        sizes = neg_counts[locs]
+        start = neg_cutoffs[locs]
+        end = start + sizes
+        slices = compute.concat_ranges(start, end)
+        batch_sims = neg_sims[slices]
+        return batch_sims, sizes
+
+    return negs_for
+
+
+def build_rank_lists_multi(pos_pairs, pos_sims, pos_counts, negs_for):
+    ap_scores_list, null_confs_list, ix_list = [], [], []
+
+    start = 0
+    for end in pos_counts.cumsum():
+        mpos_pairs = pos_pairs[start:end]
+        mpos_sims = pos_sims[start:end]
+        start = end
+        query = np.unique(mpos_pairs)
+        neg_sims, neg_counts = negs_for(query)
+        neg_ix = np.repeat(query, neg_counts)
+        labels = np.concatenate(
+            [
+                np.ones(mpos_pairs.size, dtype=np.int32),
+                np.zeros(len(neg_sims), dtype=np.int32),
+            ]
+        )
+
+        ix = np.concatenate([mpos_pairs.ravel(), neg_ix])
+        sim_all = np.concatenate([np.repeat(mpos_sims, 2), neg_sims])
+        ix_sort = np.lexsort([1 - sim_all, ix])
+        rel_k_list = labels[ix_sort]
+        _, counts = np.unique(ix, return_counts=True)
+        ap_scores, null_confs = compute.ap_contiguous(rel_k_list, counts)
+        ap_scores_list.append(ap_scores)
+        null_confs_list.append(null_confs)
+        ix_list.append(query)
+    return ap_scores_list, null_confs_list, ix_list
+
+
+def average_precision(
+    meta,
+    feats,
+    pos_sameby,
+    pos_diffby,
+    neg_sameby,
+    neg_diffby,
+    multilabel_col,
+    batch_size=20000,
+) -> pd.DataFrame:
+    columns = flatten_str_list(pos_sameby, pos_diffby, neg_sameby, neg_diffby)
+    validate_pipeline_input(meta, feats, columns)
+    # Critical!, otherwise the indexing wont work
+    meta = meta.reset_index(drop=True).copy()
+
+    logger.info("Indexing metadata...")
+    matcher = MatcherMultilabel(
+        *evaluate_and_filter(meta, columns), multilabel_col=multilabel_col, seed=0
+    )
+
+    logger.info("Finding positive pairs...")
+    pos_pairs = matcher.get_all_pairs(sameby=pos_sameby, diffby=pos_diffby)
+    pos_keys = pos_pairs.keys()
+    pos_counts = np.fromiter(map(len, pos_pairs.values()), dtype=np.int32)
+    pos_total = sum(pos_counts)
+    if pos_total == 0:
+        raise UnpairedException("Unable to find positive pairs.")
+    pos_pairs = np.fromiter(
+        itertools.chain.from_iterable(pos_pairs.values()),
+        dtype=np.dtype((np.int32, 2)),
+        count=pos_total,
+    )
+
+    logger.info("Finding negative pairs...")
+    neg_pairs = matcher.get_all_pairs(sameby=neg_sameby, diffby=neg_diffby)
+    neg_total = sum(len(p) for p in neg_pairs.values())
+    if neg_total == 0:
+        raise UnpairedException("Unable to find any negative pairs.")
+    neg_pairs = np.fromiter(
+        itertools.chain.from_iterable(neg_pairs.values()),
+        dtype=np.dtype((np.int32, 2)),
+        count=neg_total,
+    )
+
+    logger.info("Dropping dups in negative pairs...")
+    neg_pairs = np.unique(neg_pairs, axis=0)
+
+    logger.info("Computing positive similarities...")
+    pos_sims = compute.pairwise_cosine(feats, pos_pairs, batch_size)
+
+    logger.info("Computing negative similarities...")
+    neg_sims = compute.pairwise_cosine(feats, neg_pairs, batch_size)
+
+    logger.info("Computing AP per label...")
+    negs_for = create_neg_query_solver(neg_pairs, neg_sims)
+    ap_scores_list, null_confs_list, ix_list = build_rank_lists_multi(
+        pos_pairs, pos_sims, pos_counts, negs_for
+    )
+
+    logger.info("Creating result DataFrame...")
+    results = []
+    for i, key in enumerate(pos_keys):
+        result = pd.DataFrame(
+            {
+                "average_precision": ap_scores_list[i],
+                "n_pos_pairs": null_confs_list[i][:, 0],
+                "n_total_pairs": null_confs_list[i][:, 1],
+                "ix": ix_list[i],
+            }
+        )
+        if isinstance(key, tuple):
+            # Is a ComposedKey
+            for k, v in zip(key._fields, key):
+                result[k] = v
+        else:
+            result[multilabel_col] = key
+        results.append(result)
+    results = pd.concat(results).reset_index(drop=True)
+    meta = meta.drop(multilabel_col, axis=1)
+    results = meta.merge(results, right_on="ix", left_index=True).drop("ix", axis=1)
+    results["n_pos_pairs"] = results["n_pos_pairs"].fillna(0).astype(np.int32)
+    results["n_total_pairs"] = results["n_total_pairs"].fillna(0).astype(np.int32)
+    logger.info("Finished.")
+    return results