vowpalwabbit.pyvw

Python binding for pylibvw class

class vowpalwabbit.pyvw.SearchTask(vw, sch, num_actions)

Bases: object

Search task class

__init__(vw, sch, num_actions)
Parameters
vwvw object
schsearch object
num_actionsinteger

The number of actions with the object can be initialized with

Returns
selfSearchTask

See also

pyvw.vw
example(initStringOrDict=None, labelType=0)

Create an example initStringOrDict can specify example as VW formatted string, or a dictionary labelType can specify the desire label type

Parameters
initStringOrDictstr/dict

Example in either string or dictionary form

labelTypeinteger
  • 0 : lDEFAULT

  • 1 : lBINARY

  • 2 : lMULTICLASS

  • 3 : lCOST_SENSITIVE

  • 4 : lCONTEXTUAL_BANDIT

  • 5 : lMAX

  • 6 : lCONDITIONAL_CONTEXTUAL_BANDIT

  • 7 : lSLATES

  • 8 : lCONTINUOUS

The integer is used to map the corresponding labelType using the above available options

Returns
outExample
learn(data_iterator)

Train search task by providing an iterator of examples.

Parameters
data_iterator: iterable objects

Consists of examples to be learned

Returns
selfSearchTask
predict(my_example, useOracle=False)

Predict on the example

Parameters
my_exampleExample

example used for prediction

useOraclebool
Returns
outinteger

Prediction on the example

class vowpalwabbit.pyvw.VWOption(name, help_str, short_name, keep, necessary, allow_override, value, value_supplied, default_value, default_value_supplied)

Bases: object

__init__(name, help_str, short_name, keep, necessary, allow_override, value, value_supplied, default_value, default_value_supplied)
property allow_override
property default_value
property default_value_supplied
property help_str
is_flag()
property keep
property name
property necessary
property short_name
property value
property value_supplied
class vowpalwabbit.pyvw.abstract_label

Bases: object

An abstract class for a VW label.

__init__()
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.cbandits_label(costs=[], prediction=0)

Bases: vowpalwabbit.pyvw.abstract_label

Class for contextual bandits VW label

__init__(costs=[], prediction=0)
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.cost_sensitive_label(costs=[], prediction=0)

Bases: vowpalwabbit.pyvw.abstract_label

Class for cost sensative VW label

__init__(costs=[], prediction=0)
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.example(vw, initStringOrDictOrRawExample=None, labelType=0)

Bases: pylibvw.example

The example class is a (non-trivial) wrapper around pylibvw.example. Most of the wrapping is to make the interface easier to use (by making the types safer via namespace_id) and also with added python-specific functionality.

__init__(vw, initStringOrDictOrRawExample=None, labelType=0)

Construct a new example from vw.

Parameters
vwvw

vw model

initStringOrDictOrRawExampledict/string/None

If initString is None, you get an “empty” example which you can construct by hand (see, eg, example.push_features). If initString is a string, then this string is parsed as it would be from a VW data file into an example (and “setup_example” is run). if it is a dict, then we add all features in that dictionary. finally, if it’s a function, we (repeatedly) execute it fn() until it’s not a function any more(for lazy feature computation). By default is None

labelTypeinteger
  • 0 : lDEFAULT

  • 1 : lBINARY

  • 2 : lMULTICLASS

  • 3 : lCOST_SENSITIVE

  • 4 : lCONTEXTUAL_BANDIT

  • 5 : lMAX

  • 6 : lCONDITIONAL_CONTEXTUAL_BANDIT

  • 7 : lSLATES

  • 8 : lCONTINUOUS

The integer is used to map the corresponding labelType using the above available options

Returns
selfExample

See also

pyvw.vw
ensure_namespace_exists(ns)

Check to see if a namespace already exists.

Parameters
nsnamespace

If namespace exists does, do nothing. If it doesn’t, add it.

feature(ns, i)

Get the i-th hashed feature id in a given namespace

Parameters
nsnamespace

namespace used to get the feature

iinteger

to get i-th hashed feature id in a given ns. It must range from 0 to self.num_features_in(ns)-1

Returns
finteger

i-th hashed feature-id in a given ns

feature_weight(ns, i)

Get the value(weight) associated with a given feature id

Parameters
nsnamespace

namespace used to get the feature id

iinteger

to get the weight of i-th feature in the given ns. It must range from 0 to self.num_features_in(ns)-1

Returns
outfloat

weight(value) of the i-th feature of given ns

get_feature_id(ns, feature, ns_hash=None)

Get the hashed feature id for a given feature in a given namespace. feature can either be an integer (already a feature id) or a string, in which case it is hashed.

Parameters
nsnamespace

namespace used to get the feature

featureinteger/string

If integer the already a feature else will be hashed

ns_hashOptional, by default is None

The hash of the namespace

Returns
outinteger

Hashed feature id

Note

If –hash all is on, then get_feature_id(ns,”5”) !=
get_feature_id(ns, 5). If you’ve already hashed the namespace,
you can optionally provide that value to avoid re-hashing it.
get_label(label_class=<class 'vowpalwabbit.pyvw.simple_label'>)

Given a known label class (default is simple_label), get the corresponding label structure for this example.

Parameters
label_classlabel classes

Get the label of the example of label_class type, by default is simple_label

get_ns(id)

Construct a namespace_id

Parameters
idnamespace_id/str/integer

id used to create namespace

Returns
outnamespace_id

namespace_id created using parameter passed(if id was namespace_id, just return it directly)

iter_features()

Iterate over all feature/value pairs in this example (all namespace included).

learn()

Learn on this example (and before learning, automatically call setup_example if the example hasn’t yet been setup).

num_features_in(ns)

Get the total number of features in a given namespace

Parameters
nsnamespace

Get the total features of this namespace

Returns
num_featuresinteger

Total number of features in the given ns

pop_feature(ns)

Remove the top feature from a given namespace

Parameters
nsnamespace

namespace from which feature is popped

Returns
outbool

True if feature was removed else False as no feature was there to pop

pop_namespace()

Remove the top namespace from an example

Returns
outbool

True if namespace was removed else False as no namespace was there to pop

push_feature(ns, feature, v=1.0, ns_hash=None)

Add an unhashed feature to a given namespace

Parameters
nsnamespace

namespace in which the feature is to be pushed

finteger

feature

vfloat

The value of the feature, be default is 1.0

ns_hashOptional, by default is None

The hash of the namespace

push_features(ns, featureList)

Push a list of features to a given namespace.

Parameters
nsnamespace

namespace in which the features are pushed

featureListlist

Each feature in the list can either be an integer (already hashed) or a string (to be hashed) and may be paired with a value or not (if not, the value is assumed to be 1.0

Examples

>>> from vowpalwabbit import pyvw
>>> vw = pyvw.vw(quiet=True)
>>> ex = vw.example('1 |a two features |b more features here')
>>> ex.push_features('x', ['a', 'b'])
>>> ex.push_features('y', [('c', 1.), 'd'])
>>> space_hash = vw.hash_space('x')
>>> feat_hash  = vw.hash_feature('a', space_hash)
>>> ex.push_features('x', [feat_hash]) #'x' should match the space_hash!
>>> ex.num_features_in('x')
3
>>> ex.num_features_in('y')
2
push_hashed_feature(ns, f, v=1.0)

Add a hashed feature to a given namespace.

Parameters
nsnamespace

namespace in which the feature is to be pushed

finteger

feature

vfloat

The value of the feature, be default is 1.0

push_namespace(ns)

Push a new namespace onto this example. You should only do this if you’re sure that this example doesn’t already have the given namespace

Parameters
nsnamespace

namespace which is to be pushed onto example

set_label_string(string)

Give this example a new label

Parameters
stringstr

a new label to this example, formatted as a string (ala the VW data file format)

setup_example()

If this example hasn’t already been setup (ie, quadratic features constructed, etc.), do so.

sum_feat_sq(ns)

Get the total sum feature-value squared for a given namespace

Parameters
nsnamespace

Get the total sum feature-value squared of this namespace

Returns
sum_sqfloat

Total sum feature-value squared of the given ns

unsetup_example()

If this example has been setup, reverse that process so you can continue editing the examples.

class vowpalwabbit.pyvw.example_namespace(ex, ns, ns_hash=None)

Bases: object

The example_namespace class is a helper class that allows you to extract namespaces from examples and operate at a namespace level rather than an example level. Mainly this is done to enable indexing like ex[‘x’][0] to get the 0th feature in namespace ‘x’ in example ex.

__init__(ex, ns, ns_hash=None)

Construct an example_namespace

Parameters
exExample

examples from which namespace is to be extracted

nsnamespace_id

Target namespace

ns_hashOptional, by default is None

The hash of the namespace

Returns
selfexample_namespace
iter_features()

iterate over all feature/value pairs in this namespace.

num_features_in()

Return the total number of features in this namespace.

pop_feature()

Remove the top feature from the current namespace; returns True if a feature was removed, returns False if there were no features to pop.

push_feature(feature, v=1.0)

Add an unhashed feature to the current namespace (fails if setup has already run on this example).

Parameters
featureinteger/str

Feature to be pushed to current namespace

vfloat

Feature value, by default is 1.0

push_features(ns, featureList)

Push a list of features to a given namespace.

Parameters
nsnamespace

namespace to which feature list is to be pushed

featureListlist

Each feature in the list can either be an integer (already hashed) or a string (to be hashed) and may be paired with a value or not (if not, the value is assumed to be 1.0).

See example.push_features for examples.
vowpalwabbit.pyvw.get_all_vw_options()
vowpalwabbit.pyvw.get_prediction(ec, prediction_type)

Get specified type of prediction from example

Parameters
ecExample
prediction_typeinteger
  • 0: pSCALAR

  • 1: pSCALARS

  • 2: pACTION_SCORES

  • 3: pACTION_PROBS

  • 4: pMULTICLASS

  • 5: pMULTILABELS

  • 6: pPROB

  • 7: pMULTICLASSPROBS

  • 8: pDECISION_SCORES

  • 9: pACTION_PDF_VALUE

  • 10: pPDF

Returns
outinteger/list

Prediction according to parameter prediction_type

Examples

>>> from vowpalwabbit import pyvw
>>> import pylibvw
>>> vw = pyvw.vw(quiet=True)
>>> ex = vw.example('1 |a two features |b more features here')
>>> pyvw.get_prediction(ex, pylibvw.vw.pSCALAR)
0.0
class vowpalwabbit.pyvw.log_forward

Bases: object

__init__()
log(msg)
class vowpalwabbit.pyvw.multiclass_label(label=1, weight=1.0, prediction=1)

Bases: vowpalwabbit.pyvw.abstract_label

Class for multiclass VW label with prediction

__init__(label=1, weight=1.0, prediction=1)
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.multiclass_probabilities_label(label, prediction=None)

Bases: vowpalwabbit.pyvw.abstract_label

Class for multiclass VW label with probabilities

__init__(label, prediction=None)
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.namespace_id(ex, id)

Bases: object

The namespace_id class is simply a wrapper to convert between hash spaces referred to by character (eg ‘x’) versus their index in a particular example. Mostly used internally, you shouldn’t really need to touch this.

__init__(ex, id)

Given an example and an id, construct a namespace_id.

Parameters
exExample

example used to create a namespace id

idinteger/str

The id can either be an integer (in which case we take it to be an index into ex.indices[]) or a string (in which case we take the first character as the namespace id).

Returns
selfnamespace_id
class vowpalwabbit.pyvw.simple_label(label=0.0, weight=1.0, initial=0.0, prediction=0.0)

Bases: vowpalwabbit.pyvw.abstract_label

Class for simple VW label

__init__(label=0.0, weight=1.0, initial=0.0, prediction=0.0)
from_example(ex)

grab a label from a given VW example

class vowpalwabbit.pyvw.vw(arg_str=None, enable_logging=False, **kw)

Bases: pylibvw.vw

The pyvw.vw object is a (trivial) wrapper around the pylibvw.vw object; you’re probably best off using this directly and ignoring the pylibvw.vw structure entirely.

__init__(arg_str=None, enable_logging=False, **kw)

Initialize the vw object.

Parameters
arg_strstr

The command line arguments to initialize VW with, for example “–audit”. By default is None.

**kwUsing key/value pairs for different options available
Returns
selfvw

Examples

>>> from vowpalwabbit import pyvw
>>> vw1 = pyvw.vw('--audit')
>>> vw2 = pyvw.vw(audit=True, b=24, k=True, c=True, l2=0.001)
>>> vw3 = pyvw.vw("--audit", b=26)
>>> vw4 = pyvw.vw(q=["ab", "ac"])
example(stringOrDict=None, labelType=0)

Create an example initStringOrDict can specify example as VW formatted string, or a dictionary labelType can specify the desire label type

Parameters
initStringOrDictstr/dict

Example in either string or dictionary form

labelTypeinteger
  • 0 : lDEFAULT

  • 1 : lBINARY

  • 2 : lMULTICLASS

  • 3 : lCOST_SENSITIVE

  • 4 : lCONTEXTUAL_BANDIT

  • 5 : lMAX

  • 6 : lCONDITIONAL_CONTEXTUAL_BANDIT

  • 7 : lSLATES

  • 8 : lCONTINUOUS

The integer is used to map the corresponding labelType using the above available options

Returns
outExample
finish()

stop VW by calling finish (and, eg, write weights to disk)

finish_example(ex)

Should only be used in conjunction with the parse method

Parameters
exExample

example to be finished

finished = False
get_config(filtered_enabled_reductions_only=True)
get_log()
get_weight(index, offset=0)

Get the weight at a particular position in the (learned) weight vector.

Parameters
indexinteger

position in the learned weight vector

offsetinteger

By default is 0

Returns
weightfloat

Weight at the given index

get_weight_from_name(feature_name, namespace_name=' ')

Get the weight based on the feature name and the namespace name.

Parameters
feature_namestr

The name of the feature

namespace_namestr, by default is “”

The name of the namespace where the feature lives

Returns
weightfloat

Weight for the given feature and namespace name

init = False
init_search_task(search_task, task_data=None)
learn(ec)

Perform an online update

Parameters
ecexample/str/list

examples on which the model gets updated

log_fwd = None
log_wrapper = None
num_weights()

Get length of weight vector.

parse(str_ex, labelType=0)

Returns a collection of examples for a multiline example learner or a single example for a single example learner.

Parameters
str_exstr/list of str

string representing examples. If the string is multiline then each line is considered as an example. In case of list, each string element is considered as an example

labelTypeinteger
  • 0 : lDEFAULT

  • 1 : lBINARY

  • 2 : lMULTICLASS

  • 3 : lCOST_SENSITIVE

  • 4 : lCONTEXTUAL_BANDIT

  • 5 : lMAX

  • 6 : lCONDITIONAL_CONTEXTUAL_BANDIT

  • 7 : lSLATES

  • 8 : lCONTINUOUS

The integer is used to map the corresponding labelType using the above available options

Returns
eclist

list of examples parsed

Examples

>>> from vowpalwabbit import pyvw
>>> model = pyvw.vw(quiet=True)
>>> ex = model.parse("0:0.1:0.75 | a:0.5 b:1 c:2")
>>> type(ex)
<class 'vowpalwabbit.pyvw.example'>
>>> model = pyvw.vw(quiet=True, cb_adf=True)
>>> ex = model.parse(["| a:1 b:0.5", "0:0.1:0.75 | a:0.5 b:1 c:2"])
>>> type(ex)
<class 'list'>
>>> len(ex) # Shows the multiline example is parsed
2
parser_ran = False
predict(ec, prediction_type=None)

Just make a prediction on the example

Parameters
ecExample/list/str

examples to be predicted

prediction_typeoptional, by default is None

if provided then the matching return type is used otherwise the the learner’s prediction type will determine the output.

Returns
predictionPrediction made on each examples
save(filename)

save model to disk