c^ZdZddlZddlZddlZddlZddlZejddkrddlm Z nddl m Z  ddl m Z dZ n #e $rdZ YnwxYwGdd ZGd d eZGd d eZGddeZGddeZGddZGddZdS)aV Callbacks can be used to observe the training process. Since training in huge corpora can be time consuming, we want to offer the users some insight into the process, in real time. In this way, convergence issues or other potential problems can be identified early in the process, saving precious time and resources. The metrics exposed through this module can be used to construct Callbacks, which will be called at specific points in the training process, such as "epoch starts" or "epoch finished". These metrics can be used to assess mod's convergence or correctness, for example to save the model, visualize intermediate results, or anything else. Usage examples -------------- To implement a Callback, inherit from this base class and override one or more of its methods. Create a callback to save the training model after each epoch .. sourcecode:: pycon >>> from gensim.test.utils import get_tmpfile >>> from gensim.models.callbacks import CallbackAny2Vec >>> >>> >>> class EpochSaver(CallbackAny2Vec): ... '''Callback to save model after each epoch.''' ... ... def __init__(self, path_prefix): ... self.path_prefix = path_prefix ... self.epoch = 0 ... ... def on_epoch_end(self, model): ... output_path = get_tmpfile('{}_epoch{}.model'.format(self.path_prefix, self.epoch)) ... model.save(output_path) ... self.epoch += 1 ... Create a callback to print progress information to the console: .. sourcecode:: pycon >>> class EpochLogger(CallbackAny2Vec): ... '''Callback to log information about training''' ... ... def __init__(self): ... self.epoch = 0 ... ... def on_epoch_begin(self, model): ... print("Epoch #{} start".format(self.epoch)) ... ... def on_epoch_end(self, model): ... print("Epoch #{} end".format(self.epoch)) ... self.epoch += 1 ... >>> >>> epoch_logger = EpochLogger() >>> w2v_model = Word2Vec(common_texts, epochs=5, vector_size=10, min_count=0, seed=42, callbacks=[epoch_logger]) Epoch #0 start Epoch #0 end Epoch #1 start Epoch #1 end Epoch #2 start Epoch #2 end Epoch #3 start Epoch #3 end Epoch #4 start Epoch #4 end Create and bind a callback to a topic model. This callback will log the perplexity metric in real time: .. sourcecode:: pycon >>> from gensim.models.callbacks import PerplexityMetric >>> from gensim.models.ldamodel import LdaModel >>> from gensim.test.utils import common_corpus, common_dictionary >>> >>> # Log the perplexity score at the end of each epoch. >>> perplexity_logger = PerplexityMetric(corpus=common_corpus, logger='shell') >>> lda = LdaModel(common_corpus, id2word=common_dictionary, num_topics=5, callbacks=[perplexity_logger]) N)Queue)VisdomTFc$eZdZdZdZdZdZdS)MetricaQBase Metric class for topic model evaluation metrics. Concrete implementations include: * :class:`~gensim.models.callbacks.CoherenceMetric` * :class:`~gensim.models.callbacks.PerplexityMetric` * :class:`~gensim.models.callbacks.DiffMetric` * :class:`~gensim.models.callbacks.ConvergenceMetric` cV|j|jSt|jddS)zGet a string representation of Metric class. Returns ------- str Human readable representation of the metric. Ni)titletype__name__selfs 7lib/python3.11/site-packages/gensim/models/callbacks.py__str__zMetric.__str__xs. : ,: ::&ss+ +c \|D]\}}t|||dS)zSet the metric parameters. Parameters ---------- **parameters Keyword arguments to override the object's internal attributes. N)itemssetattr)r parameters parametervalues rset_parameterszMetric.set_parameterssC!+ 0 0 2 2 , , Iu D)U + + + + , ,rc td)a Get the metric's value at this point in time. Warnings -------- The user **must** provide a concrete implementation for this method for every subclass of this class. See Also -------- :meth:`gensim.models.callbacks.CoherenceMetric.get_value` :meth:`gensim.models.callbacks.PerplexityMetric.get_value` :meth:`gensim.models.callbacks.DiffMetric.get_value` :meth:`gensim.models.callbacks.ConvergenceMetric.get_value` Returns ------- object The metric's type depends on what exactly it measures. In the simplest case it might be a real number corresponding to an error estimate. It could however be anything else that is useful to report or visualize. zBPlease provide an implementation for `get_value` in your subclass.)NotImplementedErrorr s r get_valuezMetric.get_values.""fgggrN)r __module__ __qualname____doc__rrrrrrrmsP   , , , , , ,hhhhhrrc.eZdZdZ ddZfdZxZS)CoherenceMetriczMetric class for coherence evaluation. See Also -------- :class:`~gensim.models.coherencemodel.CoherenceModel` N c ||_||_||_||_||_||_||_||_| |_dS)a Parameters ---------- corpus : {iterable of list of (int, float), scipy.sparse.csc}, optional Stream of document vectors or sparse matrix of shape (`num_documents`, `num_terms`). texts : list of char (str of length 1), optional Tokenized texts needed for coherence models that use sliding window based probability estimator. dictionary : :class:`~gensim.corpora.dictionary.Dictionary`, optional Gensim dictionary mapping from integer IDs to words, needed to create corpus. If `model.id2word` is present, this is not needed. If both are provided, `dictionary` will be used. coherence : {'u_mass', 'c_v', 'c_uci', 'c_npmi'}, optional Coherence measure to be used. 'c_uci' is also known as 'c_pmi' in the literature. For 'u_mass', the corpus **MUST** be provided. If `texts` is provided, it will be converted to corpus using the dictionary. For 'c_v', 'c_uci' and 'c_npmi', `texts` **MUST** be provided. Corpus is not needed. window_size : int, optional Size of the window to be used for coherence measures using boolean sliding window as their probability estimator. For 'u_mass' this doesn't matter. If 'None', the default window sizes are used which are: * `c_v` - 110 * `c_uci` - 10 * `c_npmi` - 10 topn : int, optional Number of top words to be extracted from each topic. logger : {'shell', 'visdom'}, optional Monitor training process using one of the available methods. 'shell' will print the coherence value in the active shell, while 'visdom' will visualize the coherence value with increasing epochs using the Visdom visualization framework. viz_env : object, optional Visdom environment to use for plotting the graph. Unused. title : str, optional Title of the graph plot in case `logger == 'visdom'`. Unused. N) corpus dictionary coherencetexts window_sizetopnloggerviz_envr ) r r#r&r$r%r'r(r)r*r s r__init__zCoherenceMetric.__init__sIL $" &    rc &d|_d|_tt|jdi|t j|j|j|j|j |j |j |j |j }|S)aGet the coherence score. Parameters ---------- **kwargs Key word arguments to override the object's internal attributes. One of the following parameters are expected: * `model` - pre-trained topic model of type :class:`~gensim.models.ldamodel.LdaModel`. * `topics` - list of tokenized topics. Returns ------- float The coherence score. N)modeltopicsr&r#r$r'r%r(r)r-r.superr rgensimmodelsCoherenceModelr&r#r$r'r%r( get_coherence)r kwargscm __class__s rrzCoherenceMetric.get_values&  3ot$$3==f=== ] ) )*T[ 4;D4Dn49*   !!!r) NNNNNr!NNNr rrrr+r __classcell__r6s@rr r saLPMQ....`"""""""""rr c*eZdZdZddZfdZxZS)PerplexityMetricz'Metric class for perplexity evaluation.Nc>||_||_||_||_dS)a Parameters ---------- corpus : {iterable of list of (int, float), scipy.sparse.csc}, optional Stream of document vectors or sparse matrix of shape (`num_documents`, `num_terms`). logger : {'shell', 'visdom'}, optional Monitor training process using one of the available methods. 'shell' will print the perplexity value in the active shell, while 'visdom' will visualize the coherence value with increasing epochs using the Visdom visualization framework. viz_env : object, optional Visdom environment to use for plotting the graph. Unused. title : str, optional Title of the graph plot in case `logger == 'visdom'`. Unused. N)r#r)r*r )r r#r)r*r s rr+zPerplexityMetric.__init__s$"    rc tt|jdi|td|jD}|j|j|z }tj| S)aGet the coherence score. Parameters ---------- **kwargs Key word arguments to override the object's internal attributes. A trained topic model is expected using the 'model' key. This must be of type :class:`~gensim.models.ldamodel.LdaModel`. Returns ------- float The perplexity score. c3*K|]}|D] \}}|V dSNr).0document_cnts r z-PerplexityMetric.get_value..-s3RR8RRvq#3RRRRRRRrr) r/r;rsumr#r-boundnpexp2)r r4 corpus_words perwordboundr6s rrzPerplexityMetric.get_valuesu 5%%4>>v>>>RRt{RRRRR z'' 44|C w }%%%r)NNNNr7r9s@rr;r;sR11,&&&&&&&&&rr;c.eZdZdZ d dZfd ZxZS) DiffMetricz-Metric class for topic difference evaluation.jaccarddr!TFNc ||_||_||_||_||_||_||_||_| |_dS)ac Parameters ---------- distance : {'kullback_leibler', 'hellinger', 'jaccard'}, optional Measure used to calculate difference between any topic pair. num_words : int, optional The number of most relevant words used if `distance == 'jaccard'`. Also used for annotating topics. n_ann_terms : int, optional Max number of words in intersection/symmetric difference between topics. Used for annotation. diagonal : bool, optional Whether we need the difference between identical topics (the diagonal of the difference matrix). annotation : bool, optional Whether the intersection or difference of words between two topics should be returned. normed : bool, optional Whether the matrix should be normalized or not. logger : {'shell', 'visdom'}, optional Monitor training process using one of the available methods. 'shell' will print the coherence value in the active shell, while 'visdom' will visualize the coherence value with increasing epochs using the Visdom visualization framework. viz_env : object, optional Visdom environment to use for plotting the graph. Unused. title : str, optional Title of the graph plot in case `logger == 'visdom'`. Unused. N distance num_words n_ann_termsdiagonal annotationnormedr)r*r r rQrRrSrTrUrVr)r*r s rr+zDiffMetric.__init__4H8! "&  $    rc tt|jdi||j|j|j|j|j|j |j |j \}}|S)a@Get the difference between each pair of topics in two topic models. Parameters ---------- **kwargs Key word arguments to override the object's internal attributes. Two models of type :class:`~gensim.models.ldamodelLdaModel` are expected using the keys `model` and `other_model`. Returns ------- np.ndarray of shape (`model.num_topics`, `other_model.num_topics`) Matrix of differences between each pair of topics. np.ndarray of shape (`model.num_topics`, `other_model.num_topics`, 2), optional Annotation matrix where for each pair we include the word from the intersection of the two topics, and the word from the symmetric difference of the two topics. Only included if `annotation == True`. r) r/rLrr-diff other_modelrQrRrSrTrUrVr r4 diff_diagonalrBr6s rrzDiffMetric.get_valueZsj& /j$.88888:??  dmT^T=M M4?DK   qr rMrNr!TFTNNNr7r9s@rrLrL2sY77SWQU$$$$LrrLc.eZdZdZ d dZfd ZxZS) ConvergenceMetricz)Metric class for convergence evaluation. rMrNr!TFNc ||_||_||_||_||_||_||_||_| |_dS)ab Parameters ---------- distance : {'kullback_leibler', 'hellinger', 'jaccard'}, optional Measure used to calculate difference between any topic pair. num_words : int, optional The number of most relevant words used if `distance == 'jaccard'`. Also used for annotating topics. n_ann_terms : int, optional Max number of words in intersection/symmetric difference between topics. Used for annotation. diagonal : bool, optional Whether we need the difference between identical topics (the diagonal of the difference matrix). annotation : bool, optional Whether the intersection or difference of words between two topics should be returned. normed : bool, optional Whether the matrix should be normalized or not. logger : {'shell', 'visdom'}, optional Monitor training process using one of the available methods. 'shell' will print the coherence value in the active shell, while 'visdom' will visualize the coherence value with increasing epochs using the Visdom visualization framework. viz_env : object, optional Visdom environment to use for plotting the graph. Unused. title : str, optional Title of the graph plot in case `logger == 'visdom'`. Unused. NrPrWs rr+zConvergenceMetric.__init__wrXrc tt|jdi||j|j|j|j|j|j |j |j \}}tj |S)a:Get the sum of each element in the difference matrix between each pair of topics in two topic models. A small difference between the partially trained models produced by subsequent training iterations can indicate that the model has stopped significantly improving and has therefore converged to a local or global optimum. Parameters ---------- **kwargs Key word arguments to override the object's internal attributes. Two models of type :class:`~gensim.models.ldamodel.LdaModel` are expected using the keys `model` and `other_model`. Returns ------- float The sum of the difference matrix between two trained topic models (usually the same model after two subsequent training iterations). r)r/r`rr-rZr[rQrRrSrTrUrVrGrEr\s rrzConvergenceMetric.get_valuesu( 6&&5?????:??  dmT^T=M M4?DK   qvm$$$rr^r7r9s@rr`r`usY33SWQU$$$$L%%%%%%%%%rr`c&eZdZdZdZdZddZdS)Callbacka+A class representing routines called reactively at specific phases during trained. These can be used to log or visualize the training progress using any of the metric scores developed before. The values are stored at the end of each training epoch. The following metric scores are currently available: * :class:`~gensim.models.callbacks.CoherenceMetric` * :class:`~gensim.models.callbacks.PerplexityMetric` * :class:`~gensim.models.callbacks.DiffMetric` * :class:`~gensim.models.callbacks.ConvergenceMetric` c||_dS)z Parameters ---------- metrics : list of :class:`~gensim.models.callbacks.Metric` The list of metrics to be reported by the callback. N)metrics)r rfs rr+zCallback.__init__s rc||_d|_td|jDr,t j||_t |_td|jDr0tstdt|_ g|_ td|jDrtjd|_dSdS)aASave the model instance and initialize any required variables which would be updated throughout training. Parameters ---------- model : :class:`~gensim.models.basemodel.BaseTopicModel` The model for which the training will be reported (logged or visualized) by the callback. Nc3NK|] }t|ttfV!dSr? isinstancerLr`r@metrics rrDz%Callback.set_model..2^^vz&:/@"ABB^^^^^^rc3,K|]}|jdkVdS)visdomNr)rks rrDz%Callback.set_model..s)DDVv}(DDDDDDrz'Please install Visdom for visualizationc3,K|]}|jdkVdS)shellNrprks rrDz%Callback.set_model..s)CCFv}'CCCCCCrzgensim.models.ldamodel)r-previousanyrfcopydeepcopyrdiff_matVISDOM_INSTALLED ImportErrorrvizwindowslogging getLoggerlog_typer r-s r set_modelzCallback.set_models  ^^QUQ]^^^ ^ ^ $ M%00DM!GGDM DDt|DDD D D # M!"KLLLxxDHDL CCdlCCC C C H#-.FGGDMMM H HrNc Fi}t|jD]\}}t|}|||j|j}|||<|jdkr*|dkr%|jdkrtj |g}|j |j |j td||} |j||jt'j| n|j tj |gtj |g|j td||} |jt'j| n|jdkrtj|jtj |gf}|j |j |j |j|td|||j|nU|j tj |gtj |g|j |j|d |jd krOd d t|d|dt|f} |j| t7d|jDrt'j|j|_|S)aReport the current epoch's metric value. Called at the end of each training iteration. Parameters ---------- epoch : int The epoch that just ended. topics : list of list of str, optional List of tokenized topics. This is required for the coherence metric. Returns ------- dict of (str, object) Mapping from metric names to their values. The type of each value depends on the metric type, for example :class:`~gensim.models.callbacks.DiffMetric` computes a matrix while :class:`~gensim.models.callbacks.ConvergenceMetric` computes a float. )r.r-r[rorEpochs)xlabelylabelr )Xenvopts)Yrrr)rrwinrappend)rrrrupdaterrzEpoch z: z estimate: c3NK|] }t|ttfV!dSr?rirks rrDz(Callback.on_epoch_end..1rmr) enumeraterfstrrr-rsr)ndimrGarrayrzheatmapTr*dictrwputr{rrurvline concatenategetjoinr~infort) r epochr.current_metricsirllabelrrw viz_metric statements r on_epoch_endzCallback.on_epoch_ends*#4<00, ., .IAvKKE$$F$*RVR_$``E%*OE "}(" A:!zA~G#%8UG#4#4%)X%5%5&jfn4x`emrCsCsCs&6&&  ))(333 ++DM*,E,EFFFF%)X]] hw//28UG3D3D&.!%Xe5!Q!Q!Q&3&&  ++DM*,E,EFFFFzA~#%>4=3D3D3F3FRWQXHYHY2Z#[#[((&jfn$,q/!%Xe5!Q!Q!Q) ))(3333  hw// hw// & $ Q#+ &}' .GGXs5zz4 WZ[`WaWa$bcc  ""9--- ^^QUQ]^^^ ^ ^ 6 M$*55DMrr?)r rrrr+rrrrrrdrdsY     HHH4JJJJJJrrdc*eZdZdZdZdZdZdZdS)CallbackAny2VecaBase class to build callbacks for :class:`~gensim.models.word2vec.Word2Vec` & subclasses. Callbacks are used to apply custom functions over the model at specific points during training (epoch start, batch end etc.). This is a base class and its purpose is to be inherited by custom Callbacks that implement one or more of its methods (depending on the point during training where they want some action to be taken). See examples at the module level docstring for how to define your own callbacks by inheriting from this class. As of gensim 4.0.0, the following callbacks are no longer supported, and overriding them will have no effect: - on_batch_begin - on_batch_end cdS)zMethod called at the start of each epoch. Parameters ---------- model : :class:`~gensim.models.word2vec.Word2Vec` or subclass Current model. Nrrs ron_epoch_beginzCallbackAny2Vec.on_epoch_beginG  rcdS)zMethod called at the end of each epoch. Parameters ---------- model : :class:`~gensim.models.word2vec.Word2Vec` or subclass Current model. Nrrs rrzCallbackAny2Vec.on_epoch_endRrrcdS)zMethod called at the start of the training process. Parameters ---------- model : :class:`~gensim.models.word2vec.Word2Vec` or subclass Current model. Nrrs ron_train_beginzCallbackAny2Vec.on_train_begin]rrcdS)zMethod called at the end of the training process. Parameters ---------- model : :class:`~gensim.models.word2vec.Word2Vec` or subclass Current model. Nrrs r on_train_endzCallbackAny2Vec.on_train_endhrrN)r rrrrrrrrrrrr7sZ                  rr)rr0r|rusysnumpyrG version_infoqueuerrorrxryrr r;rLr`rdrrrrrsPPd  A!<h<h<h<h<h<h<h<h~U"U"U"U"U"fU"U"U"p+&+&+&+&+&v+&+&+&\@@@@@@@@FA%A%A%A%A%A%A%A%H{{{{{{{{|: : : : : : : : : : s?A A