Python API

This section includes information about the Python API of bob.db.avspoof.verification and bob.db.avspoof.spoofing database interfaces.

bob.db.avspoof.verification	AVspoof database implementation of bob.db.verification.utils.Database interface.
bob.db.avspoof.spoofing	AVspoof database implementation of antispoofing.utils.db.Database interface.

API for verification experiments

AVspoof database implementation of bob.db.verification.utils.Database interface. It is an extension of an SQL-based database interface, which directly talks to AVspoof database, for verification experiments (good to use in bob.bio.base framework).

class bob.db.avspoof.verification.File(f)

Bases: bob.db.verification.utils.file.File

Initializes this File object with an File equivalent from the underlying SQl-based interface for AVspoof database.

load(directory=None, extension='.hdf5')

Loads the data at the specified location and using the given extension.

Keyword parameters:

data

The data blob to be saved (normally a numpy.ndarray).

directory

[optional] If not empty or None, this directory is prefixed to the final file destination

extension

[optional] The extension of the filename - this will control the type of output and the codec for saving the input blob.

get_client_id()

Get ID of the client that this file belongs to.

make_path(directory=None, extension=None)

Wraps the current path so that a complete path is formed

Keyword parameters:

directory : str or None

An optional directory name that will be prefixed to the returned result.

extension : str or None

An optional extension that will be suffixed to the returned filename. The extension normally includes the leading . character as in .jpg or .hdf5.

Returns a string containing the newly generated file path.

save(data, directory=None, extension='.hdf5', create_directories=True)

Saves the input data at the specified location and using the given extension.

Keyword parameters:

data : various types

The data blob to be saved (normally a numpy.ndarray).

directory : str or None

If not empty or None, this directory is prefixed to the final file destination

extension : str or None

The extension of the filename. This extension will control the type of output and the codec for saving the input blob.

create_directories : bool

Should the directory structure be created (if necessary) before writing the data?

class bob.db.avspoof.verification.Database(original_directory=None, original_extension=None)

Bases: bob.db.verification.utils.database.Database

The AVspoof Database access methods for Bob

groups(protocol=None)

Returns the names of all registered groups

genders()

Returns the list of genders

protocols()

Returns all registered protocols

protocol_names()

Returns all registered protocol names

has_protocol(name)

Tells if a certain protocol is available

protocol(name)

Returns the protocol object in the database given a certain name. Raises an error if that does not exist.

models(groups=None, protocol=None, gender=None)

Returns a set of models for the specific query by the user.

Keyword Parameters:

protocol

Protocol is ignored in this context, since its choice has no influence on models.

groups

The groups to which the subjects attached to the models belong (‘dev’, ‘eval’, ‘world’)

gender

The gender to consider (‘male’, ‘female’)

Returns: A list containing the ids of all models belonging to the given group.

model_ids(groups=None, protocol=None, gender=None)

Returns a set of models ids for the specific query by the user.

Keyword Parameters:

protocol

Protocol is ignored in this context, since its choice has no influence on models.

groups

The groups to which the subjects attached to the models belong (‘dev’, ‘eval’, ‘world’)

gender

The gender to consider (‘male’, ‘female’)

Returns: A list containing the ids of all models belonging to the given group.

clients(protocol=None, groups=None, gender=None)

Returns a list of Clients for the specific query by the user.

If no parameters are specified - return all clients.

Keyword Parameters:

protocol

Protocol is ignored in this context, since its choice has no influence on clients.

groups

The groups to which the subjects attached to the models belong (‘dev’, ‘eval’, ‘world’)

gender

The gender to consider (‘male’, ‘female’)

Returns: A list containing the ids of all models belonging to the given group.

has_client_id(id)

Returns True if we have a client with a certain integer identifier

client(id)

Returns the Client object in the database given a certain id. Raises an error if that does not exist.

get_client_id_from_model_id(model_id, **kwargs)

Returns the client_id attached to the given model_id

Keyword Parameters:

model_id

The model_id to consider

Returns: The client_id attached to the given model_id

annotations(file)

Currently, there is no support for annotations in AVspoof database

objects(protocol=None, purposes=None, model_ids=None, groups=None, gender=None, device=None)

Returns a set of Files for the specific query by the user.

Keyword Parameters:

protocol

Only two protocols are implemented: ‘licit’ and ‘spoof’. Any other protocol’s name will be assumed to be and converted to ‘licit’.

purposes

The purposes can be either ‘enroll’, ‘probe’, or their tuple. If ‘None’ is given (this is the default), it is considered the same as a tuple with both possible values.

model_ids

Only retrieves the files for the provided list of model ids (claimed client id). If ‘None’ is given (this is the default), no filter over the model_ids is performed.

groups

One of the groups (‘dev’, ‘eval’, ‘world’) or a tuple with several of them. If ‘None’ is given (this is the default), it is considered the same as a tuple with all possible values.

gender

The gender to consider (‘male’, ‘female’)

device

The device to consider (‘laptop’, ‘mobile’). In case of ‘licit’ protocol, device is recording device, and for ‘attack’ protocol - device is the device of attack.

Returns: A set of Files with the specified properties.

all_files(**kwargs)

Returns the list of all File objects that satisfy your query. For possible keyword arguments, please check the objects() function.

check_parameter_for_validity(parameter, parameter_description, valid_parameters, default_parameter=None)

Checks the given parameter for validity, i.e., if it is contained in the set of valid parameters. If the parameter is ‘None’ or empty, the default_parameter will be returned, in case it is specified, otherwise a ValueError will be raised.

This function will return the parameter after the check tuple or list of parameters, or raise a ValueError.

Keyword parameters:

parameter : str

The single parameter to be checked. Might be a string or None.

parameter_description : str

A short description of the parameter. This will be used to raise an exception in case the parameter is not valid.

valid_parameters : [str]

A list/tuple of valid values for the parameters.

default_parameters : [str] or None

The default parameter that will be returned in case parameter is None or empty. If omitted and parameter is empty, a ValueError is raised.

check_parameters_for_validity(parameters, parameter_description, valid_parameters, default_parameters=None)

Checks the given parameters for validity, i.e., if they are contained in the set of valid parameters. It also assures that the parameters form a tuple or a list. If parameters is ‘None’ or empty, the default_parameters will be returned (if default_parameters is omitted, all valid_parameters are returned).

This function will return a tuple or list of parameters, or raise a ValueError.

Keyword parameters:

parameters : str, [str] or None

The parameters to be checked. Might be a string, a list/tuple of strings, or None.

parameter_description : str

A short description of the parameter. This will be used to raise an exception in case the parameter is not valid.

valid_parameters : [str]

A list/tuple of valid values for the parameters.

default_parameters : [str] or None

The list/tuple of default parameters that will be returned in case parameters is None or empty. If omitted, all valid_parameters are used.

enroll_files(protocol=None, model_id=None, groups='dev', **kwargs)

Returns the list of enrollment File objects from the given model id of the given protocol for the given groups that satisfy your query. If the model_id is None (the default), enrollment files for all models are returned. For possible keyword arguments, please check the objects() function.

file_names(files, directory, extension)

This function returns the list of original file names for the given list of File objects.

Keyword parameters:

files : [File]

The list of File objects for which the file names should be retrieved

directory : str

The base directory where the files are stored

extension : str

The file name extension of the files

Return value : [str]

The file names for the given File objects, in the same order.

original_file_name(file, check_existence=True)

This function returns the original file name for the given File object.

Keyword parameters:

file : File or a derivative

The File objects for which the file name should be retrieved

check_existence : bool

Check if the original file exists?

Return value : str

The original file name for the given File object

original_file_names(files, check_existence=True)

This function returns the list of original file names for the given list of File objects.

Keyword parameters:

files : [File]

The list of File objects for which the file names should be retrieved

check_existence : bool

Check if the original files exists?

Return value : [str]

The original file names for the given File objects, in the same order.

probe_files(protocol=None, model_id=None, groups='dev', **kwargs)

Returns the list of probe File objects to probe the model with the given model id of the given protocol for the given groups that satisfy your query. If the model_id is None (the default), all possible probe files are returned. For possible keyword arguments, please check the objects() function.

provides_file_set_for_protocol(protocol=None)

Returns True if the given protocol specifies file sets for probes, instead of a single probe file. In this default implementation, False is returned, throughout. If you need different behavior, please overload this function in your derived class.

test_files(protocol=None, groups='dev', **kwargs)

Returns the list of all test File objects of the given groups that satisfy your query. Test objects are all File objects that serve either for enrollment or probing. For possible keyword arguments, please check the objects() function.

training_files(protocol=None, **kwargs)

Returns the list of all training (world) File objects that satisfy your query. For possible keyword arguments, please check the objects() function.

uniquify(file_list)

Sorts the given list of File objects and removes duplicates from it.

Keyword parameters:

file_list : [File]

A list of File objects to be handled. Also other objects can be handled, as long as they are sortable.

Returns

A sorted copy of the given file_list with the duplicates removed.

API for anti-spoofing experiments

AVspoof database implementation of antispoofing.utils.db.Database interface. This interface is useful in anti-spoofing experiments. It is an extension of an SQL-based interface, which deals with AVspoof database directly.

class bob.db.avspoof.spoofing.File(f)

Bases: antispoofing.utils.db.database.File

Initializes this File object with an File equivalent from the underlying SQl-based interface for AVspoof database

videofile(directory=None)

This method is used to return an audio file (at the moment, AVspoof contains audio files only). We use ‘videofile’ method here because antispoofing.utils.db.File interface does not define an audiofile, which makes things a little ugly.

Returns:Audio file from AVspoof database.

facefile(directory=None)

A legacy method from antispoofing.utils.db.File interface. Since there are no faces in AVspoof, this method returns None. :return: None

bbx(directory=None)

A legacy method from antispoofing.utils.db.File interface. Since there are no bounding boxes in AVspoof, this method returns None. :return: None

load(directory=None, extension='.hdf5')

Loads the data at the specified location and using the given extension.

Keyword Parameters:

data

The data blob to be saved (normally a numpy.ndarray).

directory

[optional] If not empty or None, this directory is prefixed to the final file destination

extension

[optional] The extension of the filename - this will control the type of output and the codec for saving the input blob.

save(data, directory=None, extension='.hdf5')

Saves the input data at the specified location and using the given extension.

Keyword Parameters:

data

The data blob to be saved (normally a numpy.ndarray).

directory

[optional] If not empty or None, this directory is prefixed to the final file destination

extension

[optional] The extension of the filename - this will control the type of output and the codec for saving the input blob.

make_path(directory=None, extension=None)

Wraps the current path so that a complete path is formed

Keyword Parameters:

directory

An optional directory name that will be prefixed to the returned result.

extension

An optional extension that will be suffixed to the returned filename. The extension normally includes the leading . character as in .jpg or .hdf5.

Returns a string containing the newly generated file path.

get_client_id()

The client identifier to which this file is bound to

is_real()

Returns True if the file belongs to a real access, False otherwise

class bob.db.avspoof.spoofing.Database(args=None)

Bases: antispoofing.utils.db.database.Database

Implements API of antispoofing interface for AVspoof database

Initializes an instanced of the Database with argparse parsed arguments.

set_kwargs(params)

Set internal __kwargs variable, since it is used as a filter to retrieve data from the database :param params: dictionary of pairs {“param”:”value”} that are accepted by the database as filters, for instance, it can be “protocol”:”specific_protocol_name”. :return: None

get_protocols()

Get the protocols available for this database.

get_attack_types()

Get the attack types available for this database.

create_subparser(subparser, entry_point_name)

Creates a subparser for the central manager taking into consideration the options for every module that can provide those

Keyword parameters

subparser

The argparse subparser I’ll attach to

entry_point_name

My name, given on the setup of this package (or whatever I’m declared as an entry_point).

name()

Returns the name (string) of the database.

short_name()

Returns the short name (string) of the database.

version()

Returns the version (string) of the database.

short_description()

Returns a short (1 line) description about this database

long_description()

Returns a longer description about this database

implements_any_of(propname)

Only support for audio files is implemented/ :param propname: The type of data-support, which is checked if it contains ‘audio’ :return: True if propname is None, it is equal to or contains ‘audio’, otherwise False.

get_clients(group=None)

Will return the ids of the clients in this database, based on the group (train, devel or test)

get_data(group)

Returns either all objects or objects for a specific group

Parameters:group – The groups corresponds to the subset of the AVspoof data that is used for either training, development, or evaluation tasks. It can be ‘train’, ‘devel’, ‘test’, or their tuple. Returns:Two lists of File objects (antispoofing.utils.db.File) in the form of [real, attack]. The first list - real or genuine data and the second list is attacks or spoofed data.

get_enroll_data(group=None)

Will return the enrollment File objects (antispoofing.utils.db.files.File) for the specified group (or for all groups)

get_train_data()

Will return the real access and the attack File objects (antispoofing.utils.db.files.File) for training the antispoofing classifier

get_devel_data()

Will return the real access and the attack File objects (antispoofing.utils.db.files.File) for development (supposed to tune the antispoofing classifier)

get_test_data()

Will return the real access and the attack File objects (antispoofing.utils.db.files.File) for test (supposed to report the results)

get_test_filters()

Will return a list with the valid filter strings that can be used during test, to organize the data in sub-categories instead of returning a whole set of real-accesses and attacks.

get_filtered_test_data(filter)

Will return a dictionary with keys corresponding to the filtered categories defined by filter and the values corresponding to the real-access and attack objects that should be considered for testing your classification for that sub-category.

get_filtered_devel_data(filter)

Will return a dictionary with keys corresponding to the filtered categories defined by filter and the values corresponding to the real-access and attack objects that should be considered for development of your method for that sub-category.

create_parser(parser, implements_any_of=None)

Defines a sub parser for each database, with optional properties.

Keyword Parameters:

parser

The argparse.ArgumentParser to which I’ll attach the subparsers to

implements_any_of

A string or an interable over strings that determine at least one property that the given database has to fullfill so that it gets included in the parser. This method will call the instance’s implements() to find if the instance implements or not the given access protocol.

get_all_data()

Will return the real access and the attack File objects (antispoofing.utils.db.files.File) for ALL group sets