vowpalwabbit.pyvw

This is the implementation module for core package functionality. There are a couple of advanced usage classes available here, but for the most part classes in vowpalwabbit should be used directly.

Python binding for pylibvw class

class vowpalwabbit.pyvw.AbstractLabel

Bases: object

An abstract class for a VW label.

__init__()
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.ActionScore(action: int, score: float)

Bases: object

__init__(action: int, score: float)
class vowpalwabbit.pyvw.CBContinuousLabel(costs: List[vowpalwabbit.pyvw.CBContinuousLabelElement] = [])

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for cb_continuous VW label

__init__(costs: List[vowpalwabbit.pyvw.CBContinuousLabelElement] = [])
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.CBContinuousLabelElement(action: Optional[int] = None, cost: float = 0.0, pdf_value: float = 0.0)

Bases: object

__init__(action: Optional[int] = None, cost: float = 0.0, pdf_value: float = 0.0)
class vowpalwabbit.pyvw.CBEvalLabel(action: int, cb_label: vowpalwabbit.pyvw.CBLabel)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for contextual bandits eval VW label

__init__(action: int, cb_label: vowpalwabbit.pyvw.CBLabel)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.CBLabel(costs: List[vowpalwabbit.pyvw.CBLabelElement] = [], weight: float = 1.0)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for contextual bandits VW label

__init__(costs: List[vowpalwabbit.pyvw.CBLabelElement] = [], weight: float = 1.0)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.CBLabelElement(action: Optional[int] = None, cost: float = 0.0, partial_prediction: float = 0.0, probability: float = 0.0, **kwargs)

Bases: object

__init__(action: Optional[int] = None, cost: float = 0.0, partial_prediction: float = 0.0, probability: float = 0.0, **kwargs)
class vowpalwabbit.pyvw.CCBLabel(type: vowpalwabbit.pyvw.CCBLabelType = CCBLabelType.UNSET, explicit_included_actions: Optional[List[int]] = None, weight: float = 1, has_outcome: bool = False, outcome: Optional[vowpalwabbit.pyvw.CCBSlotOutcome] = None)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for conditional contextual bandits VW label

__init__(type: vowpalwabbit.pyvw.CCBLabelType = CCBLabelType.UNSET, explicit_included_actions: Optional[List[int]] = None, weight: float = 1, has_outcome: bool = False, outcome: Optional[vowpalwabbit.pyvw.CCBSlotOutcome] = None)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.CCBLabelType(value)

Bases: enum.IntEnum

An enumeration.

ACTION = 1
SHARED = 0
SLOT = 2
UNSET = 3
class vowpalwabbit.pyvw.CCBSlotOutcome(cost: Optional[float] = None, action_probs: Optional[List[vowpalwabbit.pyvw.ActionScore]] = None)

Bases: object

__init__(cost: Optional[float] = None, action_probs: Optional[List[vowpalwabbit.pyvw.ActionScore]] = None)
class vowpalwabbit.pyvw.CostSensitiveElement(label: int, cost: float = 0.0, partial_prediction: float = 0.0, wap_value: float = 0.0)

Bases: object

__init__(label: int, cost: float = 0.0, partial_prediction: float = 0.0, wap_value: float = 0.0)
class vowpalwabbit.pyvw.CostSensitiveLabel(costs: List[vowpalwabbit.pyvw.CostSensitiveElement] = [], prediction: float = 0.0)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for cost sensative VW label

__init__(costs: List[vowpalwabbit.pyvw.CostSensitiveElement] = [], prediction: float = 0.0)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.Example(vw, initStringOrDictOrRawExample=None, labelType: Optional[Union[int, vowpalwabbit.pyvw.LabelType]] = None)

Bases: pylibvw.example

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

__init__(vw, initStringOrDictOrRawExample=None, labelType: Optional[Union[int, vowpalwabbit.pyvw.LabelType]] = None)

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

labelTypeThe direct integer value of the LabelType enum can be used or the enum directly. Supplying 0 or None means to use the default label type based on the setup VW learner.
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.SimpleLabel'>)

Given a known label class (default is Simplelabel), 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 Simplelabel

get_ns(id)

Construct a NamespaceId

Parameters
idNamespaceId/str/integer

id used to create namespace

Returns
outNamespaceId

NamespaceId created using parameter passed(if id was NamespaceId, 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.Workspace(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.ExampleNamespace(ex, ns, ns_hash=None)

Bases: object

The ExampleNamespace 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 ExampleNamespace

Parameters
exExample

examples from which namespace is to be extracted

nsNamespaceId

Target namespace

ns_hashOptional, by default is None

The hash of the namespace

Returns
selfExampleNamespace
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.
class vowpalwabbit.pyvw.LabelType(value)

Bases: enum.IntEnum

An enumeration.

BINARY = 1
CONDITIONAL_CONTEXTUAL_BANDIT = 6
CONTEXTUAL_BANDIT = 4
CONTEXTUAL_BANDIT_EVAL = 9
CONTINUOUS = 8
COST_SENSITIVE = 3
DEFAULT = 0
MAX = 5
MULTICLASS = 2
MULTILABEL = 10
SIMPLE = 1
SLATES = 7
class vowpalwabbit.pyvw.MulticlassLabel(label: int = 1, weight: float = 1.0, prediction: int = 1)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for multiclass VW label with prediction

__init__(label: int = 1, weight: float = 1.0, prediction: int = 1)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.MulticlassProbabilitiesLabel(prediction: Optional[float] = None)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for multiclass VW label with probabilities

__init__(prediction: Optional[float] = None)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.NamespaceId(ex, id)

Bases: object

The NamespaceId 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 NamespaceId.

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
selfNamespaceId
class vowpalwabbit.pyvw.PredictionType(value)

Bases: enum.IntEnum

An enumeration.

ACTION_PDF_VALUE = 9
ACTION_PROBS = 3
ACTION_SCORES = 2
ACTIVE_MULTICLASS = 11
DECISION_SCORES = 8
MULTICLASS = 4
MULTICLASSPROBS = 7
MULTILABELS = 5
NOPRED = 12
PDF = 10
PROB = 6
SCALAR = 0
SCALARS = 1
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: Optional[Union[int, vowpalwabbit.pyvw.LabelType]] = None)

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

labelTypeThe direct integer value of the LabelType enum can be used or the enum directly. Supplying 0 or None means to use the default label type based on the setup VW learner.
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.SimpleLabel(label: float = 0.0, weight: float = 1.0, initial: float = 0.0, prediction: float = 0.0)

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for simple VW label

__init__(label: float = 0.0, weight: float = 1.0, initial: float = 0.0, prediction: float = 0.0)
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.SlatesLabel(type: vowpalwabbit.pyvw.SlatesLabelType = SlatesLabelType.UNSET, weight: float = 1.0, labeled: bool = False, cost: float = 0.0, slot_id: int = 0, probabilities: List[vowpalwabbit.pyvw.ActionScore] = [])

Bases: vowpalwabbit.pyvw.AbstractLabel

Class for slates VW label

__init__(type: vowpalwabbit.pyvw.SlatesLabelType = SlatesLabelType.UNSET, weight: float = 1.0, labeled: bool = False, cost: float = 0.0, slot_id: int = 0, probabilities: List[vowpalwabbit.pyvw.ActionScore] = [])
static from_example(ex: vowpalwabbit.pyvw.Example)

grab a label from a given VW example

class vowpalwabbit.pyvw.SlatesLabelType(value)

Bases: enum.IntEnum

An enumeration.

ACTION = 1
SHARED = 0
SLOT = 2
UNSET = 3
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.Workspace(arg_str=None, enable_logging=False, **kw)

Bases: pylibvw.vw

Workspace exposes most of the library functionality. It wraps the native code. The Workspace Python class should always be used instead of the binding glue class.

__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
selfWorkspace

Examples

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

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

labelTypeThe direct integer value of the LabelType enum can be used or the enum directly. Supplying 0 or None means to use the default label type based on the setup VW learner.
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_label_type((vw)arg1) int :

return parse label type

get_log() List[str]

Get all log messages produced. One line per item in the list. To get the complete log including run results, this should be called after finish()

Raises:

Exception: Raises an exception if this function is called but the init function was called without setting enable_logging to True

Returns: A list of strings, where each item is a line in the log

get_prediction_type((vw)arg1) int :

return prediction type

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

num_weights()

Get length of weight vector.

parse(str_ex, labelType: Optional[Union[int, vowpalwabbit.pyvw.LabelType]] = None)

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

labelTypeThe direct integer value of the LabelType enum can be used or the enum directly. Supplying 0 or None means to use the default label type based on the setup VW learner.
Returns
eclist

list of examples parsed

Examples

>>> from vowpalwabbit import pyvw
>>> model = pyvw.Workspace(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.Workspace(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: Optional[Union[int, vowpalwabbit.pyvw.PredictionType]] = 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

class vowpalwabbit.pyvw.abstract_label(*args, **kwargs)

Bases: object

This has been renamed to AbstractLabel. abstract_label is now deprecated.

class vowpalwabbit.pyvw.cbandits_label(*args, **kwargs)

Bases: object

This has been renamed to CBLabel. cbandits_label is now deprecated.

class vowpalwabbit.pyvw.cost_sensitive_label(*args, **kwargs)

Bases: object

This has been renamed to CostSensitiveLabel. cost_sensitive_label is now deprecated.

class vowpalwabbit.pyvw.example(*args, **kwargs)

Bases: object

This has been renamed to Example. example is now deprecated.

class vowpalwabbit.pyvw.example_namespace(*args, **kwargs)

Bases: object

This has been renamed to ExampleNamespace. example_namespace is now deprecated.

vowpalwabbit.pyvw.get_all_vw_options()
vowpalwabbit.pyvw.get_prediction(ec, prediction_type: Union[int, vowpalwabbit.pyvw.PredictionType])

Get specified type of prediction from example

Parameters
ecExample
prediction_typeeither the integer value of the PredictionType enum or the enum itself
Returns
outinteger/list

Prediction according to parameter prediction_type

Examples

>>> from vowpalwabbit import pyvw
>>> vw = pyvw.Workspace(quiet=True)
>>> ex = vw.example('1 |a two features |b more features here')
>>> pyvw.get_prediction(ex, pyvw.PredictionType.SCALAR)
0.0
class vowpalwabbit.pyvw.multiclass_label(*args, **kwargs)

Bases: object

This has been renamed to MulticlassLabel. multiclass_label is now deprecated.

class vowpalwabbit.pyvw.multiclass_probabilities_label(*args, **kwargs)

Bases: object

This has been renamed to MulticlassProbabilitiesLabel. multiclass_probabilities_label is now deprecated.

class vowpalwabbit.pyvw.namespace_id(*args, **kwargs)

Bases: object

This has been renamed to NamespaceId. namespace_id is now deprecated.

class vowpalwabbit.pyvw.simple_label(*args, **kwargs)

Bases: object

This has been renamed to SimpleLabel. simple_label is now deprecated.

class vowpalwabbit.pyvw.vw(*args, **kwargs)

Bases: object

This has been renamed to Workspace. vw is now deprecated.