Source code for h2o.estimators.word2vec

#!/usr/bin/env python
# -*- encoding: utf-8 -*-
#
# This file is auto-generated by h2o-3/h2o-bindings/bin/gen_python.py
# Copyright 2016 H2O.ai;  Apache License Version 2.0 (see LICENSE for details)
#
from __future__ import absolute_import, division, print_function, unicode_literals

from h2o.estimators.estimator_base import H2OEstimator
from h2o.exceptions import H2OValueError
from h2o.frame import H2OFrame
from h2o.utils.typechecks import assert_is_type, Enum, numeric


[docs]class H2OWord2vecEstimator(H2OEstimator): """ Word2Vec """ algo = "word2vec" supervised_learning = False _options_ = {'requires_training_frame': False} def __init__(self, model_id=None, # type: Optional[Union[None, str, H2OEstimator]] training_frame=None, # type: Optional[Union[None, str, H2OFrame]] min_word_freq=5, # type: int word_model="skip_gram", # type: Literal["skip_gram", "cbow"] norm_model="hsm", # type: Literal["hsm"] vec_size=100, # type: int window_size=5, # type: int sent_sample_rate=0.001, # type: float init_learning_rate=0.025, # type: float epochs=5, # type: int pre_trained=None, # type: Optional[Union[None, str, H2OFrame]] max_runtime_secs=0.0, # type: float export_checkpoints_dir=None, # type: Optional[str] ): """ :param model_id: Destination id for this model; auto-generated if not specified. Defaults to ``None``. :type model_id: Union[None, str, H2OEstimator], optional :param training_frame: Id of the training data frame. Defaults to ``None``. :type training_frame: Union[None, str, H2OFrame], optional :param min_word_freq: This will discard words that appear less than <int> times Defaults to ``5``. :type min_word_freq: int :param word_model: The word model to use (SkipGram or CBOW) Defaults to ``"skip_gram"``. :type word_model: Literal["skip_gram", "cbow"] :param norm_model: Use Hierarchical Softmax Defaults to ``"hsm"``. :type norm_model: Literal["hsm"] :param vec_size: Set size of word vectors Defaults to ``100``. :type vec_size: int :param window_size: Set max skip length between words Defaults to ``5``. :type window_size: int :param sent_sample_rate: Set threshold for occurrence of words. Those that appear with higher frequency in the training data will be randomly down-sampled; useful range is (0, 1e-5) Defaults to ``0.001``. :type sent_sample_rate: float :param init_learning_rate: Set the starting learning rate Defaults to ``0.025``. :type init_learning_rate: float :param epochs: Number of training iterations to run Defaults to ``5``. :type epochs: int :param pre_trained: Id of a data frame that contains a pre-trained (external) word2vec model Defaults to ``None``. :type pre_trained: Union[None, str, H2OFrame], optional :param max_runtime_secs: Maximum allowed runtime in seconds for model training. Use 0 to disable. Defaults to ``0.0``. :type max_runtime_secs: float :param export_checkpoints_dir: Automatically export generated models to this directory. Defaults to ``None``. :type export_checkpoints_dir: str, optional """ super(H2OWord2vecEstimator, self).__init__() self._parms = {} self._id = self._parms['model_id'] = model_id self.training_frame = training_frame self.min_word_freq = min_word_freq self.word_model = word_model self.norm_model = norm_model self.vec_size = vec_size self.window_size = window_size self.sent_sample_rate = sent_sample_rate self.init_learning_rate = init_learning_rate self.epochs = epochs self.pre_trained = pre_trained self.max_runtime_secs = max_runtime_secs self.export_checkpoints_dir = export_checkpoints_dir @property def training_frame(self): """ Id of the training data frame. Type: ``Union[None, str, H2OFrame]``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator() >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("tutor", 3) >>> print(synonyms) """ return self._parms.get("training_frame") @training_frame.setter def training_frame(self, training_frame): self._parms["training_frame"] = H2OFrame._validate(training_frame, 'training_frame') @property def min_word_freq(self): """ This will discard words that appear less than <int> times Type: ``int``, defaults to ``5``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=1, min_word_freq=4) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("teacher", 3) >>> print(synonyms) """ return self._parms.get("min_word_freq") @min_word_freq.setter def min_word_freq(self, min_word_freq): assert_is_type(min_word_freq, None, int) self._parms["min_word_freq"] = min_word_freq @property def word_model(self): """ The word model to use (SkipGram or CBOW) Type: ``Literal["skip_gram", "cbow"]``, defaults to ``"skip_gram"``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=3, word_model="skip_gram") >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("assistant", 3) >>> print(synonyms) """ return self._parms.get("word_model") @word_model.setter def word_model(self, word_model): assert_is_type(word_model, None, Enum("skip_gram", "cbow")) self._parms["word_model"] = word_model @property def norm_model(self): """ Use Hierarchical Softmax Type: ``Literal["hsm"]``, defaults to ``"hsm"``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=1, norm_model="hsm") >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("teacher", 3) >>> print(synonyms) """ return self._parms.get("norm_model") @norm_model.setter def norm_model(self, norm_model): assert_is_type(norm_model, None, Enum("hsm")) self._parms["norm_model"] = norm_model @property def vec_size(self): """ Set size of word vectors Type: ``int``, defaults to ``100``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=3, vec_size=50) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("tutor", 3) >>> print(synonyms) """ return self._parms.get("vec_size") @vec_size.setter def vec_size(self, vec_size): assert_is_type(vec_size, None, int) self._parms["vec_size"] = vec_size @property def window_size(self): """ Set max skip length between words Type: ``int``, defaults to ``5``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=3, window_size=2) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("teacher", 3) >>> print(synonyms) """ return self._parms.get("window_size") @window_size.setter def window_size(self, window_size): assert_is_type(window_size, None, int) self._parms["window_size"] = window_size @property def sent_sample_rate(self): """ Set threshold for occurrence of words. Those that appear with higher frequency in the training data will be randomly down-sampled; useful range is (0, 1e-5) Type: ``float``, defaults to ``0.001``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=1, sent_sample_rate=0.01) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("teacher", 3) >>> print(synonyms) """ return self._parms.get("sent_sample_rate") @sent_sample_rate.setter def sent_sample_rate(self, sent_sample_rate): assert_is_type(sent_sample_rate, None, float) self._parms["sent_sample_rate"] = sent_sample_rate @property def init_learning_rate(self): """ Set the starting learning rate Type: ``float``, defaults to ``0.025``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=3, init_learning_rate=0.05) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("assistant", 3) >>> print(synonyms) """ return self._parms.get("init_learning_rate") @init_learning_rate.setter def init_learning_rate(self, init_learning_rate): assert_is_type(init_learning_rate, None, float) self._parms["init_learning_rate"] = init_learning_rate @property def epochs(self): """ Number of training iterations to run Type: ``int``, defaults to ``5``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(sent_sample_rate = 0.0, epochs = 10) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("teacher", count = 5) >>> print(synonyms) >>> >>> w2v_model2 = H2OWord2vecEstimator(sent_sample_rate = 0.0, epochs = 1) >>> w2v_model2.train(training_frame=words) >>> synonyms2 = w2v_model2.find_synonyms("teacher", 3) >>> print(synonyms2) """ return self._parms.get("epochs") @epochs.setter def epochs(self, epochs): assert_is_type(epochs, None, int) self._parms["epochs"] = epochs @property def pre_trained(self): """ Id of a data frame that contains a pre-trained (external) word2vec model Type: ``Union[None, str, H2OFrame]``. :examples: >>> words = h2o.create_frame(rows=1000,cols=1, ... string_fraction=1.0, ... missing_fraction=0.0) >>> embeddings = h2o.create_frame(rows=1000,cols=100, ... real_fraction=1.0, ... missing_fraction=0.0) >>> word_embeddings = words.cbind(embeddings) >>> w2v_model = H2OWord2vecEstimator(pre_trained=word_embeddings) >>> w2v_model.train(training_frame=word_embeddings) >>> model_id = w2v_model.model_id >>> model = h2o.get_model(model_id) """ return self._parms.get("pre_trained") @pre_trained.setter def pre_trained(self, pre_trained): pt = self._parms["pre_trained"] = H2OFrame._validate(pre_trained, 'pre_trained') if pt is not None: self.vec_size = H2OWord2vecEstimator._determine_vec_size(pt) @property def max_runtime_secs(self): """ Maximum allowed runtime in seconds for model training. Use 0 to disable. Type: ``float``, defaults to ``0.0``. :examples: >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=1, max_runtime_secs=10) >>> w2v_model.train(training_frame=words) >>> synonyms = w2v_model.find_synonyms("tutor", 3) >>> print(synonyms) """ return self._parms.get("max_runtime_secs") @max_runtime_secs.setter def max_runtime_secs(self, max_runtime_secs): assert_is_type(max_runtime_secs, None, numeric) self._parms["max_runtime_secs"] = max_runtime_secs @property def export_checkpoints_dir(self): """ Automatically export generated models to this directory. Type: ``str``. :examples: >>> import tempfile >>> from os import listdir >>> job_titles = h2o.import_file(("https://s3.amazonaws.com/h2o-public-test-data/smalldata/craigslistJobTitles.csv"), ... col_names = ["category", "jobtitle"], ... col_types = ["string", "string"], ... header = 1) >>> checkpoints_dir = tempfile.mkdtemp() >>> words = job_titles.tokenize(" ") >>> w2v_model = H2OWord2vecEstimator(epochs=1, ... max_runtime_secs=10, ... export_checkpoints_dir=checkpoints_dir) >>> w2v_model.train(training_frame=words) >>> len(listdir(checkpoints_dir)) """ return self._parms.get("export_checkpoints_dir") @export_checkpoints_dir.setter def export_checkpoints_dir(self, export_checkpoints_dir): assert_is_type(export_checkpoints_dir, None, str) self._parms["export_checkpoints_dir"] = export_checkpoints_dir
[docs] @staticmethod def from_external(external=H2OFrame): """ Creates new H2OWord2vecEstimator based on an external model. :param external: H2OFrame with an external model :return: H2OWord2vecEstimator instance representing the external model :examples: >>> words = h2o.create_frame(rows=10, cols=1, ... string_fraction=1.0, ... missing_fraction=0.0) >>> embeddings = h2o.create_frame(rows=10, cols=100, ... real_fraction=1.0, ... missing_fraction=0.0) >>> word_embeddings = words.cbind(embeddings) >>> w2v_model = H2OWord2vecEstimator.from_external(external=word_embeddings) """ w2v_model = H2OWord2vecEstimator(pre_trained=external) w2v_model.train() return w2v_model
@staticmethod def _determine_vec_size(pre_trained): """ Determines vec_size for a pre-trained model after basic model verification. """ first_column = pre_trained.types[pre_trained.columns[0]] if first_column != 'string': raise H2OValueError("First column of given pre_trained model %s is required to be a String", pre_trained.frame_id) if list(pre_trained.types.values()).count('string') > 1: raise H2OValueError("There are multiple columns in given pre_trained model %s with a String type.", pre_trained.frame_id) return pre_trained.dim[1] - 1