biosppy.biometrics

biosppy.biometrics

This module provides classifier interfaces for identity recognition (biometrics) applications. The core API methods are: * enroll: add a new subject; * dismiss: remove an existing subject; * identify: determine the identity of collected biometric dataset; * authenticate: verify the identity of collected biometric dataset.

copyright:

3. 2015-2026 by Instituto de Telecomunicacoes

license:

BSD 3-clause, see LICENSE for more details.

Functions

assess_classification([results, thresholds])	Assess the performance of a biometric classification test.
assess_runs([results, subjects])	Assess the performance of multiple biometric classification runs.
combination([results, weights])	Combine results from multiple classifiers.
cross_validation(labels[, n_iter, ...])	Return a Cross Validation (CV) iterator.
get_auth_rates([TP, FP, TN, FN, thresholds])	Compute authentication rates from the confusion matrix.
get_id_rates([H, M, R, N, thresholds])	Compute identification rates from the confusion matrix.
get_subject_results([results, subject, ...])	Compute authentication and identification performance metrics for a given subject.
majority_rule([labels, random])	Determine the most frequent class label.

Classes

BaseClassifier()	Base biometric classifier class.
KNN([k, metric, metric_args])	K Nearest Neighbors (k-NN) biometric classifier.
SVM([C, kernel, degree, gamma, coef0, ...])	Support Vector Machines (SVM) biometric classifier.

Exceptions

CombinationError	Exception raised when the combination method fails.
SubjectError([subject])	Exception raised when the subject is unknown.
UntrainedError	Exception raised when classifier is not trained.

class biosppy.biometrics.BaseClassifier

Bases: object

Base biometric classifier class.

This class is a skeleton for actual classifier classes. The following methods must be overridden or adapted to build a new classifier:

• __init__

• _authenticate

• _get_thresholds

• _identify

• _prepare

• _train

• _update

EER_IDX

Reference index for the Equal Error Rate.

Type:

int

EER_IDX = 0

authenticate(data, subject, threshold=None)

Authenticate a set of feature vectors, allegedly belonging to the given subject.

Parameters:

• data (array) – Input test data.

• subject (hashable) – Subject identity.

• threshold (int, float, optional) – Authentication threshold.

Returns:

decision (array) – Authentication decision for each input sample.

batch_train(data=None)

Train the classifier in batch mode.

Parameters:

data (dict) – Dictionary holding training data for each subject; if the object for a subject is None, performs a dismiss.

check_subject(subject)

Check if a subject is enrolled.

Parameters:

subject (hashable) – Subject identity.

Returns:

check (bool) – If True, the subject is enrolled.

classmethod cross_validation(data, labels, cv, thresholds=None, **kwargs)

Perform Cross Validation (CV) on a data set.

Parameters:

• data (array) – An m by n array of m data samples in an n-dimensional space.

• labels (list, array) – A list of m class labels.

• cv (CV iterator) – A sklearn.model_selection iterator.

• thresholds (array, optional) – Classifier thresholds to use.

• **kwargs (dict, optional) – Classifier parameters.

Returns:

• runs (list) – Evaluation results for each CV run.

• assessment (dict) – Final CV biometric statistics.

dismiss(subject=None, deferred=False)

Remove a subject.

Parameters:

• subject (hashable) – Subject identity.

• deferred (bool, optional) – If True, computations are delayed until flush is called.

Raises:

SubjectError – If the subject to remove is not enrolled.

Notes

• When using deferred calls, a dismiss overrides a previous enroll for the same subject.

enroll(data=None, subject=None, deferred=False)

Enroll new data for a subject.

If the subject is already enrolled, new data is combined with existing data.

Parameters:

• data (array) – Data to enroll.

• subject (hashable) – Subject identity.

• deferred (bool, optional) – If True, computations are delayed until flush is called.

Notes

• When using deferred calls, an enroll overrides a previous dismiss for the same subject.

evaluate(data, thresholds=None, path=None, show=False)

Assess the performance of the classifier in both authentication and identification scenarios.

Parameters:

• data (dict) – Dictionary holding test data for each subject.

• thresholds (array, optional) – Classifier thresholds to use.

• path (str, optional) – If provided, the plot will be saved to the specified file.

• show (bool, optional) – If True, show a summary plot.

Returns:

• classification (dict) – Classification results.

• assessment (dict) – Biometric statistics.

flush()

Flush deferred computations.

get_auth_thr(subject, ready=False)

Get the authentication threshold of a subject.

Parameters:

• subject (hashable) – Subject identity.

• ready (bool, optional) – If True, subject is the internal classifier label.

Returns:

threshold (int, float) – Threshold value.

get_id_thr(subject, ready=False)

Get the identification threshold of a subject.

Parameters:

• subject (hashable) – Subject identity.

• ready (bool, optional) – If True, subject is the internal classifier label.

Returns:

threshold (int, float) – Threshold value.

get_thresholds(force=False)

Get an array of reasonable thresholds.

Parameters:

force (bool, optional) – If True, forces generation of thresholds.

Returns:

ths (array) – Generated thresholds.

identify(data, threshold=None)

Identify a set of feature vectors.

Parameters:

• data (array) – Input test data.

• threshold (int, float, optional) – Identification threshold.

Returns:

subjects (list) – Identity of each input sample.

io_del(label)

Delete subject data.

Parameters:

label (str) – Internal classifier subject label.

io_load(label)

Load enrolled subject data.

Parameters:

label (str) – Internal classifier subject label.

Returns:

data (array) – Subject data.

io_save(label, data)

Save subject data.

Parameters:

• label (str) – Internal classifier subject label.

• data (array) – Subject data.

list_subjects()

List all the enrolled subjects.

Returns:

subjects (list) – Enrolled subjects.

classmethod load(path)

Load classifier instance from a file.

Parameters:

path (str) – Source file path.

Returns:

clf (object) – Loaded classifier instance.

save(path)

Save classifier instance to a file.

Parameters:

path (str) – Destination file path.

set_auth_thr(subject, threshold, ready=False)

Set the authentication threshold of a subject.

Parameters:

• subject (hashable) – Subject identity.

• threshold (int, float) – Threshold value.

• ready (bool, optional) – If True, subject is the internal classifier label.

set_id_thr(subject, threshold, ready=False)

Set the identification threshold of a subject.

Parameters:

• subject (hashable) – Subject identity.

• threshold (int, float) – Threshold value.

• ready (bool, optional) – If True, subject is the internal classifier label.

update_thresholds(fraction=1.0)

Update subject-specific thresholds based on the enrolled data.

Parameters:

fraction (float, optional) – Fraction of samples to select from training data.

exception biosppy.biometrics.CombinationError

Bases: Exception

Exception raised when the combination method fails.

class biosppy.biometrics.KNN(k=3, metric='euclidean', metric_args=None)

Bases: BaseClassifier

K Nearest Neighbors (k-NN) biometric classifier.

Parameters:

• k (int, optional) – Number of neighbors.

• metric (str, optional) – Distance metric.

• metric_args (dict, optional) – Additional keyword arguments are passed to the distance function.

EER_IDX

Reference index for the Equal Error Rate.

Type:

int

EER_IDX = 0

class biosppy.biometrics.SVM(C=1.0, kernel='linear', degree=3, gamma='auto', coef0=0.0, shrinking=True, tol=0.001, cache_size=200, max_iter=-1, random_state=None)

Bases: BaseClassifier

Support Vector Machines (SVM) biometric classifier.

Wraps the ‘OneClassSVM’ and ‘SVC’ classes from ‘scikit-learn’.

Parameters:

• C (float, optional) – Penalty parameter C of the error term.

• kernel (str, optional) – Specifies the kernel type to be used in the algorithm. It must be one of ‘linear’, ‘poly’, ‘rbf’, ‘sigmoid’, ‘precomputed’ or a callable. If none is given, ‘rbf’ will be used. If a callable is given it is used to precompute the kernel matrix.

• degree (int, optional) – Degree of the polynomial kernel function (‘poly’). Ignored by all other kernels.

• gamma (float, optional) – Kernel coefficient for ‘rbf’, ‘poly’ and ‘sigmoid’. If gamma is ‘auto’ then 1/n_features will be used instead.

• coef0 (float, optional) – Independent term in kernel function. It is only significant in ‘poly’ and ‘sigmoid’.

• shrinking (bool, optional) – Whether to use the shrinking heuristic.

• tol (float, optional) – Tolerance for stopping criterion.

• cache_size (float, optional) – Specify the size of the kernel cache (in MB).

• max_iter (int, optional) – Hard limit on iterations within solver, or -1 for no limit.

• random_state (int, RandomState, optional) – The seed of the pseudo random number generator to use when shuffling the data for probability estimation.

EER_IDX

Reference index for the Equal Error Rate.

Type:

int

EER_IDX = -1

exception biosppy.biometrics.SubjectError(subject=None)

Bases: Exception

Exception raised when the subject is unknown.

exception biosppy.biometrics.UntrainedError

Bases: Exception

Exception raised when classifier is not trained.

biosppy.biometrics.assess_classification(results=None, thresholds=None)

Assess the performance of a biometric classification test.

Parameters:

• results (dict) – Classification results.

• thresholds (array) – Classifier thresholds.

Returns:

assessment (dict) – Classification assessment.

biosppy.biometrics.assess_runs(results=None, subjects=None)

Assess the performance of multiple biometric classification runs.

Parameters:

• results (list) – Classification assessment for each run.

• subjects (list) – Common target subject classes.

Returns:

assessment (dict) – Global classification assessment.

biosppy.biometrics.combination(results=None, weights=None)

Combine results from multiple classifiers.

Parameters:

• results (dict) – Results for each classifier.

• weights (dict, optional) – Weight for each classifier.

Returns:

• decision (object) – Consensus decision.

• confidence (float) – Confidence estimate of the decision.

• counts (array) – Weight for each possible decision outcome.

• classes (array) – List of possible decision outcomes.

biosppy.biometrics.cross_validation(labels, n_iter=10, test_size=0.1, train_size=None, random_state=None)

Return a Cross Validation (CV) iterator.

Wraps the StratifiedShuffleSplit iterator from sklearn.model_selection. This iterator returns stratified randomized folds, which preserve the percentage of samples for each class.

Parameters:

• labels (list, array) – List of class labels for each data sample.

• n_iter (int, optional) – Number of splitting iterations.

• test_size (float, int, optional) – If float, represents the proportion of the dataset to include in the test split; if int, represents the absolute number of test samples.

• train_size (float, int, optional) – If float, represents the proportion of the dataset to include in the train split; if int, represents the absolute number of train samples.

• random_state (int, RandomState, optional) – The seed of the pseudo random number generator to use when shuffling the data.

Returns:

cv (CV iterator) – Cross Validation iterator.

biosppy.biometrics.get_auth_rates(TP=None, FP=None, TN=None, FN=None, thresholds=None)

Compute authentication rates from the confusion matrix.

Parameters:

• TP (array) – True Positive counts for each classifier threshold.

• FP (array) – False Positive counts for each classifier threshold.

• TN (array) – True Negative counts for each classifier threshold.

• FN (array) – False Negative counts for each classifier threshold.

• thresholds (array) – Classifier thresholds.

Returns:

• Acc (array) – Accuracy at each classifier threshold.

• TAR (array) – True Accept Rate at each classifier threshold.

• FAR (array) – False Accept Rate at each classifier threshold.

• FRR (array) – False Reject Rate at each classifier threshold.

• TRR (array) – True Reject Rate at each classifier threshold.

• EER (array) – Equal Error Rate points, with format (threshold, rate).

• Err (array) – Error rate at each classifier threshold.

• PPV (array) – Positive Predictive Value at each classifier threshold.

• FDR (array) – False Discovery Rate at each classifier threshold.

• NPV (array) – Negative Predictive Value at each classifier threshold.

• FOR (array) – False Omission Rate at each classifier threshold.

• MCC (array) – Matthrews Correlation Coefficient at each classifier threshold.

biosppy.biometrics.get_id_rates(H=None, M=None, R=None, N=None, thresholds=None)

Compute identification rates from the confusion matrix.

Parameters:

• H (array) – Hit counts for each classifier threshold.

• M (array) – Miss counts for each classifier threshold.

• R (array) – Reject counts for each classifier threshold.

• N (int) – Number of test samples.

• thresholds (array) – Classifier thresholds.

Returns:

• Acc (array) – Accuracy at each classifier threshold.

• Err (array) – Error rate at each classifier threshold.

• MR (array) – Miss Rate at each classifier threshold.

• RR (array) – Reject Rate at each classifier threshold.

• EID (array) – Error of Identification points, with format (threshold, rate).

• EER (array) – Equal Error Rate points, with format (threshold, rate).

biosppy.biometrics.get_subject_results(results=None, subject=None, thresholds=None, subjects=None, subject_dict=None, subject_idx=None)

Compute authentication and identification performance metrics for a given subject.

Parameters:

• results (dict) – Classification results.

• subject (hashable) – True subject label.

• thresholds (array) – Classifier thresholds.

• subjects (list) – Target subject classes.

• subject_dict (bidict) – Subject-label conversion dictionary.

• subject_idx (list) – Subject index.

Returns:

assessment (dict) – Authentication and identification results.

biosppy.biometrics.majority_rule(labels=None, random=True)

Determine the most frequent class label.

Parameters:

• labels (array, list) – List of clas labels.

• random (bool, optional) – If True, will choose randomly in case of tied classes, otherwise the first element is chosen.

Returns:

• decision (object) – Consensus decision.

• count (int) – Number of elements of the consensus decision.