matchzoo.engine package¶

Submodules¶

matchzoo.engine.base_metric module¶

Metric base class and some related utilities.

class matchzoo.engine.base_metric.BaseMetric¶

Bases: abc.ABC

Metric base class.

ALIAS = 'base_metric'¶

matchzoo.engine.base_metric.sort_and_couple(labels, scores)¶

Zip the labels with scores into a single list.

Return type: array

matchzoo.engine.base_model module¶

matchzoo.engine.base_preprocessor module¶

matchzoo.engine.base_task module¶

Base task.

class matchzoo.engine.base_task.BaseTask(loss=None, metrics=None)¶

Bases: abc.ABC

Base Task, shouldn’t be used directly.

abstract classmethod list_available_losses()¶

Return type: list
Returns: a list of available losses.

abstract classmethod list_available_metrics()¶

Return type: list
Returns: a list of available metrics.

property loss¶

Loss used in the task.

Type: return

property metrics¶

Metrics used in the task.

Type: return

abstract property output_dtype¶

output data type for specific task.

Type: return

abstract property output_shape: tuple¶

output shape of a single sample of the task.

Type: return
Return type: tuple

matchzoo.engine.callbacks module¶

matchzoo.engine.hyper_spaces module¶

Hyper parameter search spaces wrapping hyperopt.

class matchzoo.engine.hyper_spaces.HyperoptProxy(hyperopt_func, **kwargs)¶

Bases: object

Hyperopt proxy class.

See hyperopt’s documentation for more details: https://github.com/hyperopt/hyperopt/wiki/FMin

Reason of these wrappers:

A hyper space in hyperopt requires a label to instantiate. This label is used later as a reference to original hyper space that is sampled. In matchzoo, hyper spaces are used in matchzoo.engine.Param. Only if a hyper space’s label matches its parent matchzoo.engine.Param’s name, matchzoo can correctly back-refrenced the parameter got sampled. This can be done by asking the user always use the same name for a parameter and its hyper space, but typos can occur. As a result, these wrappers are created to hide hyper spaces’ label, and always correctly bind them with its parameter’s name.

Examples::

>>> import matchzoo as mz
>>> from hyperopt.pyll.stochastic import sample

Basic Usage:

>>> model = mz.models.DenseBaseline()
>>> sample(model.params.hyper_space)  
 {'mlp_num_layers': 1.0, 'mlp_num_units': 274.0}

Arithmetic Operations:

>>> new_space = 2 ** mz.hyper_spaces.quniform(2, 6)
>>> model.params.get('mlp_num_layers').hyper_space = new_space
>>> sample(model.params.hyper_space)  
{'mlp_num_layers': 8.0, 'mlp_num_units': 292.0}

convert(name)¶

Attach name as hyperopt.hp’s label.

Parameters: name (str) –
Return type: Apply
Returns: a hyperopt ready search space

class matchzoo.engine.hyper_spaces.choice(options)¶

Bases: matchzoo.engine.hyper_spaces.HyperoptProxy

hyperopt.hp.choice() proxy.

class matchzoo.engine.hyper_spaces.quniform(low, high, q=1)¶

Bases: matchzoo.engine.hyper_spaces.HyperoptProxy

hyperopt.hp.quniform() proxy.

matchzoo.engine.hyper_spaces.sample(space)¶

Take a sample in the hyper space.

This method is stateless, so the distribution of the samples is different from that of tune call. This function just gives a general idea of what a sample from the space looks like.

Example

>>> import matchzoo as mz
>>> space = mz.models.Naive.get_default_params().hyper_space
>>> mz.hyper_spaces.sample(space)  
{'optimizer': ...}

class matchzoo.engine.hyper_spaces.uniform(low, high)¶

Bases: matchzoo.engine.hyper_spaces.HyperoptProxy

hyperopt.hp.uniform() proxy.

matchzoo.engine.param module¶

Parameter class.

class matchzoo.engine.param.Param(name, value=None, hyper_space=None, validator=None, desc=None)¶

Bases: object

Parameter class.

Basic usages with a name and value:

>>> param = Param('my_param', 10)
>>> param.name
'my_param'
>>> param.value
10

Use with a validator to make sure the parameter always keeps a valid value.

>>> param = Param(
...     name='my_param',
...     value=5,
...     validator=lambda x: 0 < x < 20
... )
>>> param.validator  
<function <lambda> at 0x...>
>>> param.value
5
>>> param.value = 10
>>> param.value
10
>>> param.value = -1
Traceback (most recent call last):
    ...
ValueError: Validator not satifised.
The validator's definition is as follows:
validator=lambda x: 0 < x < 20

Use with a hyper space. Setting up a hyper space for a parameter makes the parameter tunable in a matchzoo.engine.Tuner.

>>> from matchzoo.engine.hyper_spaces import quniform
>>> param = Param(
...     name='positive_num',
...     value=1,
...     hyper_space=quniform(low=1, high=5)
... )
>>> param.hyper_space  
<matchzoo.engine.hyper_spaces.quniform object at ...>
>>> from hyperopt.pyll.stochastic import sample
>>> hyperopt_space = param.hyper_space.convert(param.name)
>>> samples = [sample(hyperopt_space) for _ in range(64)]
>>> set(samples) == {1, 2, 3, 4, 5}
True

The boolean value of a Param instance is only True when the value is not None. This is because some default falsy values like zero or an empty list are valid parameter values. In other words, the boolean value means to be “if the parameter value is filled”.

>>> param = Param('dropout')
>>> if param:
...     print('OK')
>>> param = Param('dropout', 0)
>>> if param:
...     print('OK')
OK

A _pre_assignment_hook is initialized as a data type convertor if the value is set as a number to keep data type consistency of the parameter. This conversion supports python built-in numbers, numpy numbers, and any number that inherits numbers.Number.

>>> param = Param('float_param', 0.5)
>>> param.value = 10
>>> param.value
10.0
>>> type(param.value)
<class 'float'>

property desc: str¶

Parameter description.

Type: return
Return type: str

property hyper_space: Union[hyperopt.pyll.base.Apply, matchzoo.engine.hyper_spaces.HyperoptProxy]¶

Hyper space of the parameter.

Type: return
Return type: Union[Apply, HyperoptProxy]

property name: str¶

Name of the parameter.

Type: return
Return type: str

reset()¶

Set the parameter’s value to None, which means “not set”.

This method bypasses validator.

Example

>>> import matchzoo as mz
>>> param = mz.Param(
...     name='str', validator=lambda x: isinstance(x, str))
>>> param.value = 'hello'
>>> param.value = None
Traceback (most recent call last):
    ...
ValueError: Validator not satifised.
The validator's definition is as follows:
name='str', validator=lambda x: isinstance(x, str))
>>> param.reset()
>>> param.value is None
True

set_default(val, verbose=1)¶

Set default value, has no effect if already has a value.

Parameters

val – Default value to set.
verbose – Verbosity.

property validator: Callable[Any, bool]¶

Validator of the parameter.

Type: return
Return type: Callable[[Any], bool]

property value: Any¶

Value of the parameter.

Type: return
Return type: Any

matchzoo.engine.param_table module¶

Parameters table class.

class matchzoo.engine.param_table.ParamTable¶

Bases: object

Parameter table class.

Example

>>> params = ParamTable()
>>> params.add(Param('ham', 'Parma Ham'))
>>> params.add(Param('egg', 'Over Easy'))
>>> params['ham']
'Parma Ham'
>>> params['egg']
'Over Easy'
>>> print(params)
ham                           Parma Ham
egg                           Over Easy
>>> params.add(Param('egg', 'Sunny side Up'))
Traceback (most recent call last):
    ...
ValueError: Parameter named egg already exists.
To re-assign parameter egg value, use `params["egg"] = value` instead.

add(param)¶

Parameters: param (Param) – parameter to add.

completed()¶

Return type: bool
Returns: True if all params are filled, False otherwise.

Example

>>> import matchzoo
>>> model = matchzoo.models.Naive()
>>> model.params.completed()
False
>>> model.guess_and_fill_missing_params(verbose=0)
>>> model.params.completed()
True

get(key)¶

Return type: Param
Returns: The parameter in the table named key.

property hyper_space: dict¶

Hyper space of the table, a valid hyperopt graph.

Type: return
Return type: dict

keys()¶

Return type: KeysView
Returns: Parameter table keys.

set(key, param)¶: Set key to parameter param.

to_frame()¶

Convert the parameter table into a pandas data frame.

Return type: DataFrame
Returns: A pandas.DataFrame.

Example

>>> import matchzoo as mz
>>> table = mz.ParamTable()
>>> table.add(mz.Param(name='x', value=10, desc='my x'))
>>> table.add(mz.Param(name='y', value=20, desc='my y'))
>>> table.to_frame()
  Name Description  Value Hyper-Space
0    x        my x     10        None
1    y        my y     20        None

update(other)¶

Update self.

Update self with the key/value pairs from other, overwriting existing keys. Notice that this does not add new keys to self.

This method is usually used by models to obtain useful information from a preprocessor’s context.

Parameters: other (dict) – The dictionary used update.

Example

>>> import matchzoo as mz
>>> model = mz.models.DenseBaseline()
>>> model.params['input_shapes'] is None
True
>>> prpr = model.get_default_preprocessor()
>>> _ = prpr.fit(mz.datasets.toy.load_data(), verbose=0)
>>> model.params.update(prpr.context)
>>> model.params['input_shapes']
[(30,), (30,)]

matchzoo.engine.parse_metric module¶

matchzoo.engine.parse_metric.parse_metric(metric, task=None)¶

Parse input metric in any form into a BaseMetric instance.

Parameters

metric (Union[str, Type[BaseMetric], BaseMetric]) – Input metric in any form.
task (Optional[BaseTask]) – Task type for determining specific metric.

Return type

Union[BaseMetric, str]

Returns

A BaseMetric instance

Examples::

>>> from matchzoo import metrics
>>> from matchzoo.engine.parse_metric import parse_metric

Use str as keras native metrics:

>>> parse_metric('mse')
'mse'

Use str as MatchZoo metrics:

>>> mz_metric = parse_metric('map')
>>> type(mz_metric)
<class 'matchzoo.metrics.mean_average_precision.MeanAveragePrecision'>

Use matchzoo.engine.BaseMetric subclasses as MatchZoo metrics:

>>> type(parse_metric(metrics.AveragePrecision))
<class 'matchzoo.metrics.average_precision.AveragePrecision'>

Use matchzoo.engine.BaseMetric instances as MatchZoo metrics:

>>> type(parse_metric(metrics.AveragePrecision()))
<class 'matchzoo.metrics.average_precision.AveragePrecision'>

matchzoo.engine package¶

Submodules¶

matchzoo.engine.base_metric module¶

matchzoo.engine.base_model module¶

matchzoo.engine.base_preprocessor module¶

matchzoo.engine.base_task module¶

matchzoo.engine.callbacks module¶

matchzoo.engine.hyper_spaces module¶

matchzoo.engine.param module¶

matchzoo.engine.param_table module¶

matchzoo.engine.parse_metric module¶

Module contents¶