thresher-py 0.2.1__py3-none-any.whl

thresher/__init__.py

@@ -0,0 +1,3 @@
+#!/usr/bin/env python
+
+from thresher.interface import Thresher

thresher/algorithm.py

@@ -0,0 +1,28 @@
+from collections import namedtuple
+
+Algorithm = namedtuple('Algorithm', ['id', 'full_name', 'synonyms', 'data_vol_thresh'])
+
+available_algorithms = {'auto': Algorithm(id='auto', synonyms=['default', 'default_heuristics'],
+                                          data_vol_thresh=None, full_name='Default heuristics'),
+                        'ls': Algorithm(id='ls', synonyms=['linear', 'linear_search'],
+                                        data_vol_thresh=1000, full_name='Linear search'),
+                        'sgd': Algorithm(id='sgd', synonyms=['curve_fitting', ],
+                                         data_vol_thresh=None, full_name='Stochastic gradient descent'),
+                        'gen': Algorithm(id='gen', synonyms=['genetic', 'sim'],
+                                         data_vol_thresh=None, full_name='Genetic algorithm'),
+                        'grid': Algorithm(id='grid', synonyms=['grid-search', 'gs'],
+                                          data_vol_thresh=50*1000, full_name='Grid search'),
+                        'sgrid': Algorithm(id='sgrid', synonyms=['random-grid-search', 'rn-grid', 's-grid'],
+                                           data_vol_thresh=None, full_name='Stochastic grid search'),
+                        }
+
+DEFAULT = available_algorithms['auto']
+
+
+def retrieve_by_alias(name: str):
+    name = name.lower()
+    try:
+        return available_algorithms[name]
+    except KeyError:
+        # try to match by the 'alternate name'
+        return next(_ for _ in available_algorithms.values() if name in _.synonyms)

thresher/algs/common/meta_optimizer.py

@@ -0,0 +1,9 @@
+import numpy as np
+
+
+def calculate_range_mean(scores, actual_classes, label):
+    return np.mean([_[0] for _ in zip(scores, actual_classes) if _[1] == label])
+
+
+def get_mean_value_for_class_pd(label, label_column, data, data_column):
+    return np.mean(data[data[label_column] == label][data_column])

thresher/algs/common/stochastic.py

@@ -0,0 +1,21 @@
+import random
+
+
+def stochastic_process(evaluated, scores, actual_classes, random_factor, miss_class=True):
+    population_size = len(scores)
+
+    sample = random.sample(range(population_size), int(random_factor * population_size))
+    number_of_correct, number_of_incorrect = 0, 0
+    for idx in sample:
+        element = scores[idx]
+        actual_class = actual_classes[idx]
+        pred = 1 if element > evaluated else -1
+        if pred == actual_class:
+            number_of_correct += 1
+        else:
+            number_of_incorrect += 1
+
+    if miss_class:
+        return number_of_incorrect / (number_of_incorrect + number_of_correct)  # ratio of mis-class
+    else:
+        return number_of_correct / (number_of_incorrect + number_of_correct)

thresher/algs/common/tools.py

@@ -0,0 +1,3 @@
+def granularity_of_scores(scores, number_of_decimal_places=2):
+    for score in scores:
+        yield round(score, number_of_decimal_places)

thresher/algs/genetic/compute.py

@@ -0,0 +1,90 @@
+import random
+import numpy as np
+
+from thresher.algs.common.meta_optimizer import calculate_range_mean
+from thresher.algs.common.stochastic import stochastic_process
+from thresher.utils import get_or_default, print_progress_bar
+
+population_size_default = 30
+number_of_generations_default = 20
+number_of_iterations_default = 10
+sus_factor_default = 2
+stoch_ratio_default = 0.02
+mutation_chance_default = 0.05
+mutation_factor_default = 0.10
+
+
+def run(scores, actual_classes, verbose, progress_bar, alg_options) -> float:
+    if verbose and progress_bar:
+        print('Warning! Enabling verbosity automatically disables a progress bar.')
+        progress_bar = False
+
+    # Defining the population size
+    population_size = get_or_default(alg_options, 'population_size', population_size_default)
+    population_initial_range = (calculate_range_mean(scores, actual_classes, -1),
+                                calculate_range_mean(scores, actual_classes, 1))
+
+    number_of_generations = get_or_default(alg_options, 'number_of_generations', number_of_generations_default)
+    number_of_iterations = get_or_default(alg_options, 'number_of_iterations', number_of_iterations_default)
+
+    sus_factor = population_size - get_or_default(alg_options, 'sus_factor', sus_factor_default)
+    # how many agents should die child-less after a generation
+
+    stoch_ratio = get_or_default(alg_options, 'stoch_ratio', stoch_ratio_default)
+    # random ratio - the lower, the faster sim
+
+    mutation_factor = get_or_default(alg_options, 'mutation_factor', mutation_factor_default)
+
+    population = []
+
+    # Build the population
+    for i in range(population_size):
+        population.append({'id': f'agent_{i}',
+                           'trait': random.uniform(population_initial_range[0], population_initial_range[1]),
+                           'trait_eff': list()})
+
+    for generation_no in range(number_of_generations):
+        if verbose:
+            print(f'Running generation no {generation_no}')
+
+        if progress_bar:
+            print_progress_bar(generation_no, number_of_generations)
+
+        for iteration_no in range(number_of_iterations):
+            for agent in population:
+                agent['trait_eff'].append(stochastic_process(agent['trait'],
+                                                             scores, actual_classes, random_factor=stoch_ratio))
+                # for every iteration, get a stochastic fitness score
+
+        # calculate fitness score - the mean mis-classification ratio over this
+        # generation's iterations, so that lower is fitter
+        for agent in population:
+            agent['trait_eff'] = np.mean(agent['trait_eff'])
+
+        # select most fit (SUS)
+        sort_by_fit = [_ for _ in sorted(population, key=lambda x: x['trait_eff'], reverse=False)][0:sus_factor]
+
+        # do crossover
+        population = []
+        for i in range(population_size):
+            l = random.sample(sort_by_fit, 1)[0]['trait']
+            r = random.sample(sort_by_fit, 1)[0]['trait']
+            if l > r:
+                l, r = r, l
+            # new_trait = random.sample([l, l + ((r-l)*random.random()), r], 1)[0]
+            new_trait = l + ((r-l)*random.random())
+            population.append({'id': f'agent_{i}',
+                               'trait': new_trait,
+                               'trait_eff': list()})
+
+        # mutate
+        if random.random() < get_or_default(alg_options, 'mutation_chance', mutation_chance_default):
+            population[int(len(population) * random.random())]['trait'] += mutation_factor * random.random()
+
+        if verbose:
+            print(f'Population after gen: {generation_no} - {[_["trait"] for _ in population]}')
+
+    if progress_bar:
+        print_progress_bar(number_of_generations, number_of_generations)
+
+    return float(np.mean([_["trait"] for _ in population]))

thresher/algs/grid/compute.py

@@ -0,0 +1,63 @@
+import numpy as np
+from thresher.utils import get_or_default, print_progress_bar
+import random
+
+no_of_decimal_places_default = 2
+stoch_ratio_default = 0.05
+reshuffle_default = False
+
+
+def run_stoch(scores, actual_classes, verbose, progress_bar, alg_options):
+    return run(scores, actual_classes, verbose, progress_bar, alg_options, True)
+
+
+def run(scores, actual_classes, verbose, progress_bar, alg_options, stochastic=False):
+    best_threshold, best_accuracy, iteration = None, -1, 0
+
+    no_of_decimal_places = get_or_default(alg_options, 'no_of_decimal_places', no_of_decimal_places_default)
+    stoch_ratio = get_or_default(alg_options, 'stoch_ratio', stoch_ratio_default)
+    reshuffle = get_or_default(alg_options, 'reshuffle', reshuffle_default)
+
+    batch_size = (10**no_of_decimal_places)+1
+
+    if verbose:
+        print(f'Evaluating {batch_size} solutions. Please wait for results.')
+
+    def get_random_projection(_scores, _actual_classes, _stoch_ratio):
+        return random.sample(list(zip(_scores, _actual_classes)), int(_stoch_ratio * len(_scores)))
+
+    if stochastic and (not reshuffle):
+        one_time_projection = get_random_projection(scores, actual_classes, stoch_ratio)
+
+    for single_point in np.linspace(0, 1, batch_size):
+        iteration += 1
+
+        if progress_bar:
+            print_progress_bar(iteration, batch_size)
+
+        count_correct, count_incorrect = 0, 0
+
+        if stochastic:
+            if reshuffle:
+                projection = get_random_projection(scores, actual_classes, stoch_ratio)
+            else:
+                projection = one_time_projection
+        else:
+            projection = zip(scores, actual_classes)
+
+        for l, r in projection:
+            predicted = 1 if l > single_point else -1
+            if predicted == r:
+                count_correct += 1
+            else:
+                count_incorrect += 1
+
+        accuracy = count_correct / (count_correct + count_incorrect)
+
+        if accuracy > best_accuracy:
+            best_threshold, best_accuracy = single_point, accuracy
+
+    if progress_bar:
+        print_progress_bar(batch_size, batch_size)
+
+    return best_threshold

thresher/algs/linear/compute.py

@@ -0,0 +1,75 @@
+from thresher.utils import pairwise, print_progress_bar
+import multiprocessing as mp
+from functools import partial
+
+
+def process_batch(scores, actual_classes, data_point):
+    count_correct, count_incorrect = 0, 0
+
+    for l, r in zip(scores, actual_classes):
+        predicted = 1 if l > data_point else -1
+        if predicted == r:
+            count_correct += 1
+        else:
+            count_incorrect += 1
+
+    accuracy = count_correct / (count_correct + count_incorrect)
+
+    return data_point, accuracy
+
+
+def run_parallel(scores, actual_classes, verbose, n_jobs) -> float:
+    batch_size = len(scores)
+    number_of_processors = mp.cpu_count()
+
+    if (n_jobs < -1) or (n_jobs > number_of_processors):
+        print(f'Improper value for n_jobs. It must be either -1, or at most, the number of available processors')
+
+    if verbose:
+        print(f'Doing linear search with {batch_size} iterations, running in parallel {n_jobs} jobs.')
+
+    def iterate_through_scores():
+        for score in scores:
+            yield score
+
+    pool = mp.Pool(processes=number_of_processors-1 if n_jobs == -1 else n_jobs)
+    mp_func = partial(process_batch, scores, actual_classes)
+    results = pool.map(func=mp_func, iterable=iterate_through_scores(), chunksize=int(batch_size/n_jobs))
+
+    return next(i[0] for i in sorted(results, key=lambda x: x[1], reverse=True))
+
+
+def run(scores, actual_classes, verbose, progress_bar) -> float:
+    best_threshold, best_accuracy, iteration = None, -1, 0
+
+    batch_size = len(scores)
+
+    if verbose:
+        print(f'Doing linear search with {batch_size} iterations. It can take some time, depending on the data volume.')
+
+    for a, b in pairwise(sorted(scores)):
+        iteration += 1
+
+        if progress_bar:
+            print_progress_bar(iteration, batch_size)
+
+        middle = (a + b) / 2
+
+        count_correct, count_incorrect = 0, 0
+
+        for l, r in zip(scores, actual_classes):
+            predicted = 1 if l > middle else -1
+            if predicted == r:
+                count_correct += 1
+            else:
+                count_incorrect += 1
+
+        accuracy = count_correct / (count_correct + count_incorrect)
+
+        if accuracy > best_accuracy:
+            best_threshold, best_accuracy = middle, accuracy
+
+    if progress_bar:
+        print_progress_bar(batch_size, batch_size)
+
+    return best_threshold

thresher/algs/sgd/compute.py

@@ -0,0 +1,80 @@
+import numpy as np
+from thresher.algs.common.stochastic import stochastic_process
+from thresher.utils import get_or_default
+
+
+num_of_iters_default = 200
+stop_thresh_default = 0.001
+alpha_default = 0.01
+
+
+def sgd_solver(eval_func, starting_point, gradient, verbose, num_of_iters, stop_thresh, alpha):
+    previous_eval_point = starting_point
+    previous_eval = 0.0
+
+    first_run = eval_func(previous_eval_point, previous_eval)
+
+    evaluation, gain = first_run[0], -first_run[1]
+
+    if verbose:
+        print(f'SGD initial run (from point {starting_point}). Evaluation: {evaluation} and gain: {gain}')
+
+    for iter_no in range(num_of_iters):
+
+        previous_eval = evaluation
+        previous_gain = gain
+
+        if verbose:
+            print(f'SGD iteration {iter_no}. Previous evaluation: {previous_eval} for X:{previous_eval_point} and previous gain: {previous_gain}')
+
+        new_point = previous_eval_point + gradient
+
+        if verbose:
+            print(f'SGD iteration {iter_no}. New point set to: {new_point} because gradient: {gradient}')
+
+        evaluation, gain = eval_func(new_point, previous_eval)
+
+        if verbose:
+            print(f'SGD iteration {iter_no}. Evaluation: {evaluation} and gain: {gain}')
+
+        previous_eval_point = new_point
+
+        gradient = gradient * (gain/previous_eval) * (1.0 - alpha)
+        if gain < 0:
+            gradient *= -1.0
+
+        if verbose:
+            print(f'SGD iteration {iter_no}. New gradient set to: {gradient}')
+
+        if abs(gain) < stop_thresh:
+            return previous_eval_point
+
+    # hadn't converged with 'num_of_iters', return anyway
+    return previous_eval_point
+
+
+def run(scores, actual_classes, verbose, progress_bar, alg_options) -> float:
+
+    def evaluate_threshold(threshold, previous_eval, random_factor=0.05):
+        if verbose:
+            print(f'Currently evaluating threshold: {threshold}')
+
+        new_eval = stochastic_process(threshold, scores, actual_classes, random_factor)
+        gain = previous_eval - new_eval
+
+        return new_eval, gain
+
+    starting_point = np.mean(scores)
+    if verbose:
+        print(f'Starting point set to: {starting_point}')
+
+    starting_gradient = 0.05
+
+    num_of_iters = get_or_default(alg_options, 'num_of_iters', num_of_iters_default)
+    stop_thresh = get_or_default(alg_options, 'stop_thresh', stop_thresh_default)
+    alpha = get_or_default(alg_options, 'alpha', alpha_default)
+
+    result = sgd_solver(evaluate_threshold, starting_point, starting_gradient, verbose,
+                        num_of_iters=num_of_iters, stop_thresh=stop_thresh, alpha=alpha)
+
+    return result

thresher/exceptions.py

@@ -0,0 +1,2 @@
+NOT_IMPLEMENTED_ERROR = 'The "scores" attribute is not an Iterable! Please provide a list-like object'
+UNKNOWN_ALGORITHM = 'Unknown algorithm. Run get_supported_algorithms() to get a list of available algorithms.'

thresher/interface.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python
+
+import numpy as np
+import pandas as pd
+from collections.abc import Iterable
+
+from thresher import algorithm
+from thresher.oracle import run_oracle, run_computations
+from thresher.exceptions import NOT_IMPLEMENTED_ERROR
+from thresher.utils import map_labels
+
+
+class ThresherBase(object):
+
+    def _run_oracle(self, data_traits: dict):
+        if self.options['algorithm'] == algorithm.DEFAULT:
+            if self.options['verbose']:
+                print("Running heuristics on choosing a proper algorithm")
+            chosen_algorithm = run_oracle(data_traits)
+
+        else:
+            chosen_algorithm = self.options['algorithm']
+
+        if self.options['verbose']:
+            print(f"Chosen algorithm: {chosen_algorithm.full_name}")
+
+        return chosen_algorithm
+
+    def _compute(self, chosen_algorithm, scores, actual_classes):
+        return run_computations(chosen_algorithm, scores, actual_classes,
+                                self.options['verbose'],
+                                self.options['progress_bar'],
+                                self.options['allow_parallel'],
+                                self.options['algorithm_params'])
+
+
+class Thresher(ThresherBase):
+
+    def __init__(self, **kwargs):
+        """Creates a new Thresher object, an interface to the Thesher evaluator.
+
+        The __init__ method creates the Thresher object.
+
+        Note:
+            No need to pass any extra arguments if you don't understand what you're doing
+
+        Args:
+            kwargs (:obj:`dict`, optional): Any hidden arguments, which you wish to pass.
+        """
+
+        super(ThresherBase, self).__init__()
+
+        self.options = {
+            'algorithm': 'auto',
+            'allow_parallel': True,
+            'verbose': False,
+            'progress_bar': False,
+            'algorithm_params': {}
+        }
+
+        self.options.update(kwargs)
+
+        self.options['algorithm'] = algorithm.retrieve_by_alias(self.options['algorithm'])
+
+    def get_current_algorithm(self):
+        """Get current language."""
+        with self.options['algorithm'] as current_algorithm:
+            return {'name': current_algorithm.id, 'object': current_algorithm}
+
+    def get_current_options(self):
+        return self.options
+
+    def set_algorithm(self, algorithm_name):
+        try:
+            self.options['algorithm'] = algorithm.retrieve_by_alias(algorithm_name)
+        except StopIteration:
+            print('Unknown algorithm, please use a name available in get_supported_algorithms()')
+        return self
+
+    @staticmethod
+    def get_supported_algorithms(as_dict=False):
+        """Get list of supported languages."""
+        if as_dict:
+            return {k: v.full_name for k, v in algorithm.available_algorithms.items()}
+        else:
+            return list(algorithm.available_algorithms.keys())
+
+    def optimize_threshold(self, scores, actual_classes):
+        if not isinstance(scores, Iterable):
+            raise AttributeError(NOT_IMPLEMENTED_ERROR)
+        if not isinstance(actual_classes, Iterable):
+            raise AttributeError(NOT_IMPLEMENTED_ERROR)
+
+        scores = list(scores)
+        if ('labels' in self.options) and (isinstance(self.options['labels'], Iterable)):
+            actual_classes = list(map_labels(actual_classes, self.options['labels']))
+        else:
+            actual_classes = list(actual_classes)
+
+        data_traits = {'data_length': len(scores)}
+
+        chosen_algorithm = self._run_oracle(data_traits)
+
+        return self._compute(chosen_algorithm, scores, actual_classes)

thresher/oracle.py

@@ -0,0 +1,53 @@
+from thresher import algorithm
+from thresher.algs.linear import compute as linear_compute
+from thresher.algs.sgd import compute as sgd_compute
+from thresher.algs.genetic import compute as gen_compute
+from thresher.algs.grid import compute as grid_compute
+from thresher.exceptions import UNKNOWN_ALGORITHM
+
+
+LINEAR_ALGORITHM = algorithm.available_algorithms['ls']
+STOCHASTIC_GRADIENT_DESCENT = algorithm.available_algorithms['sgd']
+GENETIC_ALGORITHM = algorithm.available_algorithms['gen']
+GRID_SEARCH_ALGORITHM = algorithm.available_algorithms['grid']
+STOCHASTIC_GRID_SEARCH_ALGORITHM = algorithm.available_algorithms['sgrid']
+
+
+def run_oracle(data_traits: dict):
+    data_volume = data_traits['data_length']
+
+    # some the 'ThresherPerformanceTest.ipynb' notebook for some thought process behind this
+    # an algorithm of recommendation for big datasets is currently 'sgd'
+
+    if data_volume <= algorithm.available_algorithms['ls'].data_vol_thresh:
+        chosen_algorithm = algorithm.available_algorithms['ls']
+    elif data_volume <= algorithm.available_algorithms['grid'].data_vol_thresh:
+        chosen_algorithm = algorithm.available_algorithms['grid']
+    else:
+        chosen_algorithm = algorithm.available_algorithms['sgd']
+
+    return chosen_algorithm
+
+
+def run_computations(chosen_algorithm: algorithm.Algorithm, scores, actual_classes,
+                     verbose, progress_bar, allow_parallel, alg_options) -> float:
+    assert set(actual_classes) == {-1, 1}
+
+    if verbose:
+        print(f'Executing the {chosen_algorithm.full_name} algorithm... please wait for the result.')
+
+    if chosen_algorithm == LINEAR_ALGORITHM:
+        if allow_parallel and ('n_jobs' in alg_options) and (alg_options['n_jobs'] != 1):
+            return linear_compute.run_parallel(scores, actual_classes, verbose, alg_options['n_jobs'])
+        else:
+            return linear_compute.run(scores, actual_classes, verbose, progress_bar)
+    elif chosen_algorithm == STOCHASTIC_GRADIENT_DESCENT:
+        return sgd_compute.run(scores, actual_classes, verbose, progress_bar, alg_options)
+    elif chosen_algorithm == GENETIC_ALGORITHM:
+        return gen_compute.run(scores, actual_classes, verbose, progress_bar, alg_options)
+    elif chosen_algorithm == GRID_SEARCH_ALGORITHM:
+        return grid_compute.run(scores, actual_classes, verbose, progress_bar, alg_options)
+    elif chosen_algorithm == STOCHASTIC_GRID_SEARCH_ALGORITHM:
+        return grid_compute.run_stoch(scores, actual_classes, verbose, progress_bar, alg_options)
+    else:
+        raise NotImplementedError(UNKNOWN_ALGORITHM)

thresher/utils.py

@@ -0,0 +1,51 @@
+from itertools import tee
+
+
+NEGATIVE_LABEL = -1
+POSITIVE_LABEL = 1
+
+
+def map_labels(labels, mapping):
+    assert type(mapping) in [list, tuple]
+    for label in labels:
+        if label == mapping[0]:
+            yield NEGATIVE_LABEL
+        elif label == mapping[1]:
+            yield POSITIVE_LABEL
+        else:
+            raise TypeError('Value not found in the mapping - map_labels() cannot map label classes.')
+
+
+def get_or_default(options, key, default):
+    if key in options:
+        return options[key]
+    else:
+        return default
+
+
+def pairwise(iterable):
+    a, b = tee(iterable)
+    next(b, None)
+    return zip(a, b)
+
+
+# Print iterations progress
+def print_progress_bar(iteration, total, prefix='', suffix='', decimals=1, length=100, fill='#'):
+    """
+    Call in a loop to create terminal progress bar
+    @params:
+        iteration   - Required  : current iteration (Int)
+        total       - Required  : total iterations (Int)
+        prefix      - Optional  : prefix string (Str)
+        suffix      - Optional  : suffix string (Str)
+        decimals    - Optional  : positive number of decimals in percent complete (Int)
+        length      - Optional  : character length of bar (Int)
+        fill        - Optional  : bar fill character (Str)
+    """
+    percent = ("{0:." + str(decimals) + "f}").format(100 * (iteration / float(total)))
+    filled_length = int(length * iteration // total)
+    bar = fill * filled_length + '-' * (length - filled_length)
+    print('\r%s |%s| %s%% %s' % (prefix, bar, percent, suffix), end='\r')
+    # Print New Line on Complete
+    if iteration == total:
+        print()

thresher_py-0.2.1.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.4
+Name: thresher-py
+Version: 0.2.1
+Summary: Find threshold for fine-tuning output from predict_proba
+Project-URL: Homepage, https://github.com/oskar-j/thresher
+Project-URL: Repository, https://github.com/oskar-j/thresher
+Project-URL: Issues, https://github.com/oskar-j/thresher/issues
+Author-email: Oskar Jarczyk <oskar.jarczyk@gmail.com>
+Maintainer-email: Oskar Jarczyk <oskar.jarczyk@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: AutoML,Finetuning,Hyper-parameters,ML,Optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: pandas
+Description-Content-Type: text/markdown
+
+# Thresher - THRESHold EvaluatoR for Python
+
+![eye illusion old vs young woman face](https://www.shared.com/content/images/2018/09/InkedUntitled-design--5-_LI_GH_content_1150px.jpg) 
+
+_That's either a young girl's head, or an old woman face - it all depends on what the brain chooses to see._
+
+_Choose your cut-off point wise!_
+
+## Project description
+
+A bare pandas implementation of a tool for finding the threshold which maximizes accuracy 
+of `predict_proba` like-outputs (from e.g. `scikit-learn`), in regard to the provided ground truth (labels).
+
+_Note: you can jump directly to the sample usage [here](https://github.com/oskar-j/thresher#sample-usage)._
+
+Method interesting for the user is `optimize_threshold(scores, actual_classes)`, which is available 
+from the `Thresher` class. This method, for given _scores_ and _actual classes_, 
+returns a threshold that yields the _**highest fraction** of correctly classified_ samples.
+
+```
+optimize_threshold parameters:
+  scores​:list
+    The list of scores.
+  actual_classes​:list
+    The list of ground truth (correct) classes. 
+    Classes are represented as -1 and 1.
+returns:
+  threshold:​float
+    The threshold value that yields ​the highest fraction of correctly classified 
+    samples​. If multiple thresholds give the optimal fraction, return any threshold.
+```
+
+### An oracle mechanism
+
+We implemented a meta-optimizer - an 'oracle' mechanism, which chooses a proper algorithm in regard to the provided data. This is the default behaviour, and can be controlled by changing the `algorithm` param of the `Thresher` constructor. See the source code of [oracle.py](https://github.com/oskar-j/thresher/blob/main/thresher/oracle.py) and [interface.py](https://github.com/oskar-j/thresher/blob/main/thresher/interface.py) for more details.
+
+### Implemented algorithms
+
+### Linear search
+
+This is the most basic, iterative approach. Recommended for smaller datasets. For every _threshold_ present in the input (in the _scores_ list), we evaluate it by calculating the exact accuracy of _split_ produced by such threshold. Then, return the threshold which produce the most accurate split. 
+
+List of parameters to customize:
+* `n_jobs` (default: 1) - set to `-1` for using all available processors except one; any value of `2` or more 
+enables multiprocessing, while the default value of `1` disables multiprocessing
+
+### 2-dim Stochastic Gradient Descent
+
+This algorithm uses a naive implementation of the popular algorithm 'Stochastic Gradient Descent', which tries to converge over a function - in our case, it
+is an error curve representing ratio of miss-classifies for a threshold. Using a gradient, algorithm follows the curve to find the optimal value, that is, 
+a threshold producing the smaller number of miss-classifies. The disadvantage of this algorithm is it's questionable robustness - it may happen
+that it converges to a local optimum instead of a global one. 
+
+List of parameters to customize:
+* `num_of_iters` (default: 200) - number of iterations during which algorithm tries to converge
+* `stop_thresh` (default: 0.001) - minimal value of improvement, below which algorithm stops
+* `alpha` (default: 0.01)
+
+### Evolutionary algorithm
+
+This is a simulation approach which uses an evolutionary algorithm. It works by simulating multiple generations of a "population" of candidate solutions. During every iteration of a single generation, algorithm stochasticly evaluates the candidate solution. After the end of a single generation, we remove the from the population least fit agents (solutions), and do the _crossover_ between the left solitions to produce new "offspring" candidate solutions. Moreover, they may mutate to provide additional random chance. 
+
+List of parameters to customize:
+* `population_size` (default: 30) - number of agents in the simulation
+* `number_of_generations` (default: 20) - number of generations
+* `number_of_iterations` (default: 10) - number of iterations per a generation
+* `sus_factor` (default: 2) - how many least-fit agents should be childless at the end of generation
+* `stoch_ratio` (default: 0.02) - percentage of data to evaluate fit of a single agent per iteration
+* `optimized_start` (default: True)
+* `mutation_chance` (default: 0.05)
+* `mutation_factor` (default: 0.10)
+
+### Grid search
+
+Added in version `0.1.2`. This algorithm works by generate a grid of possible solutions, with a granularity set
+by parameter named `no_of_decimal_places`. All candidate solutions are evaluated thoroughly 
+and the best one is chosen at the end.
+
+List of parameters to customize:
+* `no_of_decimal_places` (default: 2) - generate the grid by rounding the number to the given number of decimal places
+
+### Stochastic Grid search
+
+Added in version `0.1.2`. This algorithm works similarly like the above-mentioned 'Grid search' method, with the difference, that
+every single point generated by the grid is evaluated only partially (which can be controlled by the `stoch_ratio` parameter)
+
+List of parameters to customize:
+* `no_of_decimal_places` (default: 2) - generate the grid by rounding the number to the given number of decimal places
+* `stoch_ratio` (default: 0.05) - percentage of data to evaluate fit of a candidate number in the grid
+* `reshuffle` (default: False) - set whether the random projection should be calculated every step, or not
+
+## How to setup?
+
+The process is rather straightforward, you just need to just whether to install 
+from the sources (latest revision), or from the PyPI repository (stable release).
+
+### Requirements
+
+Requires Python `3.10+`. Tested on Python 3.10, 3.11, 3.12, 3.13 and 3.14.
+
+### Installation
+
+Stable release using the `pip` tool:
+
+```
+pip install thresher-py
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```
+uv add thresher-py
+```
+
+Installation from source (latest revision):
+
+```
+pip install git+https://github.com/oskar-j/thresher.git
+```
+
+### Development setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management, with
+`pyproject.toml` and a locked `uv.lock`:
+
+```
+uv sync --group dev
+```
+
+Run the test suite (it loads its `.xlsx` fixtures through a relative path, so it must be
+run from inside `thresher/tests`):
+
+```
+cd thresher/tests && uv run python -m unittest test
+```
+
+## Custom parameters
+
+It's possible to provide additional parameters in the `Thresher` constructor. 
+
+```python
+Thresher(algorithm='auto',
+         allow_parallel=True,
+         verbose=False, 
+         progress_bar=False,
+         labels=(0,1))
+```
+
+Here is a description of what does every particular parameter do:
+
+* **algorithm** (default value: `'auto'`) - allows to manually choose the algorithm from the list of available algorithms.
+Same effect can be achieved with running the method called `set_algorithm(algorithm_name)` on the `Thresher` instance. 
+The default value is 'auto', which means that the tool uses an oracle mechanism to manually choose a proper algorithm.
+* **allow_parallel** (default value: `True`) - enables/disabled multiprocessing for algorithms
+* **verbose** (default value: `False`) - enables verbosity
+* **progress_bar** (default value: `False`) - shows a progress bar in the terminal (if supported by the algorithm)
+* **labels** - necessary if your labels are different from `(-1, 1)` - first item from the tuple/list is a negative label, 
+and the second item is a positive label
+
+### Control parameters for the algorithms
+
+Some of the above-mentioned algorithms allow to change their parameters. 
+They should be provided in a dictionary, inside the `algorithm_params` parameter. 
+If no such customs parameters are provided, default values apply.
+
+Examples:
+
+```python
+t = thresher.Thresher(algorithm_params={'n_jobs': 3})
+```
+
+```python
+t = thresher.Thresher(algorithm_params={'no_of_decimal_places': 3,
+                                        'stoch_ratio': 0.10})
+```
+
+## Sample usage
+
+```python
+import thresher
+
+t = thresher.Thresher()
+
+print('Currently supported algorithms:')
+print(t.get_supported_algorithms())
+
+cases = [0.1, 0.3, 0.4, 0.7]
+actual_labels = [-1, -1, 1, 1]
+
+print(f'Optimization result: {t.optimize_threshold(cases, actual_labels)}')
+```
+
+See the [examples](https://github.com/oskar-j/thresher/tree/main/examples) directory for more sample code.
+
+## Performance tests
+
+A very basic performance test (with 10 repeats, on a real-world [anonymized data](https://github.com/oskar-j/thresher/blob/main/examples/performance_test/milion_samples.7z) consisting of `10^6` rows) can be found in the Notebook [located here](https://github.com/oskar-j/thresher/blob/main/examples/performance_test/TresherPerformanceTest.ipynb).
+Similar experiment, but with more iterations, was conducted in the file [TresherPerformanceTestExtended.ipynb](https://github.com/oskar-j/thresher/blob/main/examples/performance_test/TresherPerformanceTestExtended.ipynb) to test the oracle.
+
+## Future work
+
+* adding more algorithms,
+* publishing on conda,
+* more heavy test loads,
+* python docs.

thresher_py-0.2.1.dist-info/RECORD

@@ -0,0 +1,23 @@
+thresher/__init__.py,sha256=nJVLhxEftlPxSvsogYM1GI3CTUFznc0F5FSBsR08jyY,63
+thresher/algorithm.py,sha256=i-WoIZeUaSi7c9muumYlecebSkihJ3SVlcW7NTBncOA,1575
+thresher/exceptions.py,sha256=FoobZr7e4jyojF0UE-abZGQOVSsrasDaCoU24XCrxK4,214
+thresher/interface.py,sha256=K4orNGmJc_baCV2BrrCo6iC7FirZUGFwJ1XydMM9uus,3585
+thresher/oracle.py,sha256=hMhyUzPh4k-HLZizy_POELSX7xj8NCRKWGChjnoRcNo,2591
+thresher/utils.py,sha256=Nal9ukEiFranYApqfEylSEa8J6-yZOPlxKIfKUnQuQY,1633
+thresher/algs/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/common/meta_optimizer.py,sha256=rnmlO_OiMldTuc-JSVh3K63imKDAXy-7EHsljh96TE0,301
+thresher/algs/common/stochastic.py,sha256=iwb7jURZTgnYnO3RWJfSBfXaet1LL7u6AyxCzssemWw,752
+thresher/algs/common/tools.py,sha256=u1Ge5hu_flxQXPd4ik3zoRGp-xXRgBUR8K4HwReQ9lo,141
+thresher/algs/genetic/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/genetic/compute.py,sha256=86_zuSVPWEMYzh2112bX-bLgXMkrIiqBghW4_OiX0uY,3872
+thresher/algs/grid/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/grid/compute.py,sha256=L945wLXt2n8V5HEvC7IY355Qn-woljG2lgpxmqPyV9Y,2160
+thresher/algs/linear/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/linear/compute.py,sha256=QlgGVk6gPkq9srust55UC6EetEdRSO4LhuyUS7fd0fw,2369
+thresher/algs/sgd/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+thresher/algs/sgd/compute.py,sha256=S3a-lYueKtWyEfsDHLFWp836xOTZdYpr30vfKVxHGGM,2628
+thresher_py-0.2.1.dist-info/METADATA,sha256=09OWQX5oJoMJQBqpmlkI1gEkqs2S2_J5nwtvulq743o,10093
+thresher_py-0.2.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+thresher_py-0.2.1.dist-info/licenses/LICENSE,sha256=FRXuRbOPMCNUgzV23MpfHA-3hE-5GsNKT-PP9SbgKNo,1070
+thresher_py-0.2.1.dist-info/RECORD,,

thresher_py-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

thresher_py-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Oskar Jarczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.