cdZddlZddlZddlmZddlZddlZddlmZm Z ddl Z ddl m Z mZddlmZ ddlmZddlm Zd Zn #e$rd ZYnwxYwdd lmZmZdd lmZejeZGd dejZ GddZ!GddeZ"GddZ#GddZ$GddZ%GddZ&GddZ'dS)uPython implementation of Poincaré Embeddings. These embeddings are better at capturing latent hierarchical information than traditional Euclidean embeddings. The method is described in detail in `Maximilian Nickel, Douwe Kiela - "Poincaré Embeddings for Learning Hierarchical Representations" `_. The main use-case is to automatically learn hierarchical representations of nodes from a tree-like structure, such as a Directed Acyclic Graph (DAG), using a transitive closure of the relations. Representations of nodes in a symmetric graph can also be learned. This module allows training Poincaré Embeddings from a training file containing relations of graph in a csv-like format, or from a Python iterable of relations. Examples -------- Initialize and train a model from a list .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel >>> relations = [('kangaroo', 'marsupial'), ('kangaroo', 'mammal'), ('gib', 'cat')] >>> model = PoincareModel(relations, negative=2) >>> model.train(epochs=50) Initialize and train a model from a file containing one relation per line .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel, PoincareRelations >>> from gensim.test.utils import datapath >>> file_path = datapath('poincare_hypernyms.tsv') >>> model = PoincareModel(PoincareRelations(file_path), negative=2) >>> model.train(epochs=50) N)Integral) defaultdictCounter)randomfloat32) spearmanr)grad)numpyTF)utilsmatutils) KeyedVectorsc eZdZdZddddddddd ejd f d Zd"d ZdZdZ dZ dZ dZ e d#dZe dZfdZefdZd"dZd$dZdZd"dZe dZdZd%d Zd%d!ZxZS)& PoincareModelaTrain, use and evaluate Poincare Embeddings. The model can be stored/loaded via its :meth:`~gensim.models.poincare.PoincareModel.save` and :meth:`~gensim.models.poincare.PoincareModel.load` methods, or stored/loaded in the word2vec format via `model.kv.save_word2vec_format` and :meth:`~gensim.models.poincare.PoincareKeyedVectors.load_word2vec_format`. Notes ----- Training cannot be resumed from a model loaded via `load_word2vec_format`, if you wish to train further, use :meth:`~gensim.models.poincare.PoincareModel.save` and :meth:`~gensim.models.poincare.PoincareModel.load` methods instead. An important attribute (that provides a lot of additional functionality when directly accessed) are the keyed vectors: self.kv : :class:`~gensim.models.poincare.PoincareKeyedVectors` This object essentially contains the mapping between nodes and embeddings, as well the vocabulary of the model (set of unique nodes seen by the model). After training, it can be used to perform operations on the vectors such as vector lookup, distance and similarity calculations etc. See the documentation of its class for usage examples. 2g? gh㈵>?{Gz?)gMbPgMbP?rc ||_t|d|_g|_t t |_tg|_d|_ ||_ ||_ | |_ ||_ ||_||_||_||_||_d|_| |_| |_t-j| |_| |_d|_||dS)a{ Initialize and train a Poincare embedding model from an iterable of relations. Parameters ---------- train_data : {iterable of (str, str), :class:`gensim.models.poincare.PoincareRelations`} Iterable of relations, e.g. a list of tuples, or a :class:`gensim.models.poincare.PoincareRelations` instance streaming from a file. Note that the relations are treated as ordered pairs, i.e. a relation (a, b) does not imply the opposite relation (b, a). In case the relations are symmetric, the data should contain both relations (a, b) and (b, a). size : int, optional Number of dimensions of the trained model. alpha : float, optional Learning rate for training. negative : int, optional Number of negative samples to use. workers : int, optional Number of threads to use for training the model. epsilon : float, optional Constant used for clipping embeddings below a norm of one. regularization_coeff : float, optional Coefficient used for l2-regularization while training (0 effectively disables regularization). burn_in : int, optional Number of epochs to use for burn-in initialization (0 means no burn-in). burn_in_alpha : float, optional Learning rate for burn-in initialization, ignored if `burn_in` is 0. init_range : 2-tuple (float, float) Range within which the vectors are randomly initialized. dtype : numpy.dtype The numpy dtype to use for the vectors in the model (numpy.float64, numpy.float32 etc). Using lower precision floats may be useful in increasing training speed and reducing memory usage. seed : int, optional Seed for random to ensure reproducibility. Examples -------- Initialize a model from a list: .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel >>> relations = [('kangaroo', 'marsupial'), ('kangaroo', 'mammal'), ('gib', 'cat')] >>> model = PoincareModel(relations, negative=2) Initialize a model from a file containing one relation per line: .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel, PoincareRelations >>> from gensim.test.utils import datapath >>> file_path = datapath('poincare_hypernyms.tsv') >>> model = PoincareModel(PoincareRelations(file_path), negative=2) See :class:`~gensim.models.poincare.PoincareRelations` for more options. riFN) train_dataPoincareKeyedVectorskv all_relationsrsetnode_relationsNegativesBuffer_negatives_buffer_negatives_buffer_sizesize train_alpha burn_in_alphaalphanegativeworkersepsilonregularization_coeffburn_in _burn_in_donedtypeseed np_random RandomState _np_random init_range _loss_grad build_vocab) selfrrr"r#r$r%r&r'r!r.r)r*s 6lib/python3.11/site-packages/gensim/models/poincare.py__init__zPoincareModel.__init__\sr%&tQ//)#..!0!4!4&*#  *     $8! "  #/55$ $$$$$Fc t|jj}td|D]I}t|dkrt dt |z|D]}||jjvr9|j|d|j |ddzIt|jj|jj|<|jj ||j|dd|\}}|jj||jj|} }|j | | || f}|j |Ktdt|j t|jttt|jj|_t#jtt|jjt&|_||s|dS||dS) amBuild the model's vocabulary from known relations. Parameters ---------- relations : {iterable of (str, str), :class:`gensim.models.poincare.PoincareRelations`} Iterable of relations, e.g. a list of tuples, or a :class:`gensim.models.poincare.PoincareRelations` instance streaming from a file. Note that the relations are treated as ordered pairs, i.e. a relation (a, b) does not imply the opposite relation (b, a). In case the relations are symmetric, the data should contain both relations (a, b) and (b, a). update : bool, optional If true, only new nodes's embeddings are initialized. Use this when the model already has an existing vocabulary and you want to update it. If false, all node's embeddings are initialized. Use this when you're creating a new vocabulary from scratch. Examples -------- Train a model and update vocab for online training: .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel >>> >>> # train a new model from initial data >>> initial_relations = [('kangaroo', 'marsupial'), ('kangaroo', 'mammal')] >>> model = PoincareModel(initial_relations, negative=1) >>> model.train(epochs=50) >>> >>> # online training: update the vocabulary and continue training >>> online_relations = [('striped_skunk', 'mammal')] >>> model.build_vocab(online_relations, update=True) >>> model.train(epochs=50) z#loading relations from train data..z0Relation pair "%s" should have exactly two itemscountrz-loaded %d relations from train data, %d nodesr)N)lenr index_to_keyloggerinfo ValueErrorrepr key_to_index set_vecattr get_vecattrappendraddrrrange indices_setnpfromiterint indices_array_init_node_probabilities_init_embeddings_update_embeddings) r1 relationsupdateold_index_to_key_lenrelationitemnode_1node_2 node_1_index node_2_indexs r2r0zPoincareModel.build_vocabsJF #47#788 9:::! 0 0H8}}! f !SVZ[cVdVd!deee  : :47//:G''gtw7J7J4QX7Y7Y\]7]^^^^14TW5I1J1JDG(.G(//555G''gq9999%NFF)-)=f)EtwG[\bGc,L   - 1 1, ? ? ?$l3H   % %h / / / / CSI[E\E\^abfbi^j^jkkkuS)=%>%>??@@[s473G/H/H)I)IQTUUU %%''' :  ! ! # # # # #  # #$8 9 9 9 9 9r4ct|jj|jf}|j|jd|jd||j|j_ dS)z7Randomly initialize vectors for the items in the vocab.rrN) r9rr:rr-uniformr.astyper)vectors)r1shapes r2rKzPoincareModel._init_embeddingss^TW)**DI6/11$/!2DdoVWFXZ_``gghlhrssr4c4t|jj|z |jf}|j|jd|jd||j}tj |jj |g|j_ dS)zBRandomly initialize vectors for the items in the additional vocab.rrN) r9rr:rr-rWr.rXr)rF concatenaterY)r1rOrZvs r2rLz PoincareModel._update_embeddingsszTW)**-AA49M O # #DOA$68JE R R Y YZ^Zd e e.$'/1)=>>r4c|jjdtj}tj||_||z |_dS)z"Initialize a-priori probabilities.r7N) rexpandosrXrFfloat64cumsum_node_counts_cumsumsum_node_probabilities)r1countss r2rJz&PoincareModel._init_node_probabilitiessN!'*11"*==#%9V#4#4 #)FJJLL#8   r4cB|j|jkr_|jd}|jd|dz|j}tj|j|}t||_|j |jS)zGet candidate negatives of size `self.negative` from the negative examples buffer. Returns ------- numpy.array Array of shape (`self.negative`,) containing indices of negative nodes. r) r num_itemsr#rbr-randintrrF searchsortedr get_items)r1max_cumsum_valueuniform_numberscumsum_table_indicess r2_get_candidate_negativesz&PoincareModel._get_candidate_negativess  ! + + - - = K $7; "o55a9IA9MtOjkkO#%?43K_#]#] %45I%J%JD "%// >>>r4c|j|}t|jt|z }||jkr*t d|j||jj|fzt t|t|jz }|dkr|}t|}d}t|t|ks||zrM|dz }|}t|}t|t|kH||zM|dkrt d||nptj t|j|z }|j|} | | z} |j||j| d}t|S)amGet a sample of negatives for the given node. Parameters ---------- node_index : int Index of the positive node for which negative samples are to be returned. Returns ------- numpy.array Array of shape (self.negative,) containing indices of negative nodes for the given node index. zFCannot sample %d negative nodes from a set of %d negative nodes for %srrz(sampled %d times, positive fraction %.5fF)rpreplace)rr9rr#r=r:floatrorr;debugrFarraylistrErdrcr-choice) r1 node_indexrnum_remaining_nodespositive_fractionindicesunique_indices times_sampledvalid_negativesprobss r2_sample_negativeszPoincareModel._sample_negativess,Z8!$'llS-@-@@  . X 3TW5I*5UVW  "#n"5"566TWE t # j3355G \\NMw<<3~#6#66 .N^<[ ." 7799!$Ww<<3~#6#66 .N^<[ .q  k GXijjj!htD,<~,M'N'NOOO,_=E UYY[[ Eo,,_4=TYch,iiGG}}r4c 2|d}|dd}tj||z d}tj|}tj|d}tjdd|dzd|dzz d|dzz zz zz}tj| }|tj|ddzz} tj|d|z  | zS)aComputes loss value. Parameters ---------- matrix : numpy.array Array containing vectors for u, v and negative samples, of shape (2 + negative_size, dim). regularization_coeff : float, optional Coefficient to use for l2-regularization Returns ------- float Computed loss value. Warnings -------- Only used for autograd gradients, since autograd requires a specific function signature. rrNaxisr6)grad_nplinalgnormarccoshexplogrc) matrixr&vector_u vectors_veuclidean_distsr all_normspoincare_distsexp_negative_distancesregularization_terms r2_loss_fnzPoincareModel._loss_fn=s*!9122J !.--h.B-KK~""8,,N'' '::    A%1tqy=Qa=O*PQ    ")n_!=!=2W^5H5HST5V5VZ[5[[ 2159O9S9S9U9UVWWWZmmmr4ct|jdk}d|z }|rDtj|}||kr|S||z tj||zz Stj|d}||kr|S|||kxx||||kz ddtjfzcc<|||kxxtj|||k|zzcc<|S)aClip vectors to have a norm of less than one. Parameters ---------- vectors : numpy.array Can be 1-D, or 2-D (in which case the norm for each row is checked). epsilon : float Parameter for numerical stability, each dimension of the vector is reduced by `epsilon` if the norm of the vector is greater than or equal to 1. Returns ------- numpy.array Array with norms clipped below 1. rrN)r9rZrFrrsignallnewaxis)rYr%one_d thresholdrnormss r2 _clip_vectorszPoincareModel._clip_vectors`s'$GM""a'K  9>>'**Di E~)9)9G)CDDINN7N33E !&&(( *+++ E%9BTc ts6tdtddS|jt t j|_d}tt||D]\}\}}|\} } |tj |j j | |j j | g|zf|j } tj |jdd|f|jdddd|ff} tj| | z } | |kr| }td|||ksJd||fzdS)aiCompare computed gradients for batch to autograd gradients. Parameters ---------- relations : list of tuples List of tuples of positive examples of the form (node_1_index, node_2_index). all_negatives : list of lists List of lists of negative samples for each node_1 in the positive examples. batch : :class:`~gensim.models.poincare.PoincareBatch` Batch for which computed gradients are to be checked. tol : float, optional The maximum error between our computed gradients and the reference ones from autograd. z;autograd could not be imported, cannot do gradient checkingz3please install autograd to enable gradient checkingNzGmax difference between computed gradients and autograd gradients: %.10fzdMax difference between computed gradients and autograd gradients %.10f, greater than tolerance %.10f)AUTOGRAD_PRESENTr;warningr/r rr enumeraterrFvstackrrYr& gradients_u gradients_vabsmaxr<)r1rMrrtolmax_diffirPrrr]auto_gradientscomputed_gradientsdiffs r2rzPoincareModel._check_gradientss   NNX Y Y Y NNP Q Q Q F ? ;"=#9::DO(1#i2O2O(P(P  $A$)DAq!__ 47?1-twsY/OPQQSWSlnnN!#E,=aaad,CUEVWXWXWXZ[Z[Z[]^W^E_+`!a!a 6.+==>>BBDDDh  ]_ghhh#~ > > +.6_ = > > > > >r4c$fd|D}|S)a_Get negative examples for each node. Parameters ---------- nodes : iterable of int Iterable of node indices for which negative samples are to be returned. Returns ------- list of lists Each inner list is a list of negative samples for a single node in the input list. c:g|]}|S)r.0noder1s r2 z9PoincareModel._sample_negatives_batch..s'FFFt--d33FFFr4r)r1nodes all_indicess` r2_sample_negatives_batchz%PoincareModel._sample_negatives_batchs%GFFFFFF r4c|d|D}||||}|||S)aPerform training for a single training batch. Parameters ---------- relations : list of tuples of (int, int) List of tuples of positive examples of the form (node_1_index, node_2_index). check_gradients : bool, optional Whether to compare the computed gradients to autograd gradients for this batch. Returns ------- :class:`~gensim.models.poincare.PoincareBatch` The batch that was just trained on, contains computed loss for the batch. c3&K|] }|dV dS)rNr)rrPs r2 z0PoincareModel._train_on_batch..s&4[4[XXa[4[4[4[4[4[4[r4)rr_update_vectors_batch)r1rMrrrs r2_train_on_batchzPoincareModel._train_on_batch sW 444[4[QZ4[4[4[[[ ,,Y WW ""5))) r4cbt|}tt}t|D] \}}|||!|D]F\}}|dkr ||}||d||d<d||dd<GdS)aAHandle occurrences of multiple updates to the same node in a batch of vector updates. Parameters ---------- vector_updates : numpy.array Array with each row containing updates to be performed on a certain node. node_indices : list of int Node indices on which the above updates are to be performed on. Notes ----- Mutates the `vector_updates` array. Required because vectors[[2, 1, 2]] += np.array([-0.5, 1.0, 0.5]) performs only the last update on the row at index 2. rrrrgN)rrrvrrBitemsrc)vector_updates node_indicesre node_dictrrxr7 positionss r2_handle_duplicatesz PoincareModel._handle_duplicates s&&&%% &|44 , ,MAz j ! ( ( + + + +!' / / Jz !*-I,:9,E,I,Iq,I,Q,QN9R= )-.N9SbS> * *  / /r4c0|j|j}}|j|j}}t |}|j|jdzzdz |zj}||||jj |xx|zcc<| |jj ||j |jj |<|j|j dzddtjfzdz |z}|dddd}|d|jz|z|jf}||||jj |xx|zcc<| |jj ||j |jj |<dS)a Update vectors for nodes in the given batch. Parameters ---------- batch : :class:`~gensim.models.poincare.PoincareBatch` Batch containing computed gradients and node indices of the batch for which updates are to be done. r6Nrr)rrrrr9r"TrrrYrr%betarFrrrr#r) r1rgrad_ugrad_vrrr u_updates v_updatess r2rz#PoincareModel._update_vectors_batch?s*E,=$9 ^^ Z5;!#34q86AD   9555  """i/"""%)%7%7 8RTXT`%a%a "J%*/111bj=!AAAEN &&q!,,55a;; %%DM(9Z'G&STT   9555  """i/"""%)%7%7 8RTXT`%a%a """r4Nc |jdkrtdtjdd}td|j|jt|j||j |j |j |j |j dkrr|j sktd|j |j |_ ||j |||d |_ td |j|_ td ||||||td tjdi|d S)aTrain Poincare embeddings using loaded data and model parameters. Parameters ---------- epochs : int Number of iterations (epochs) over the corpus. batch_size : int, optional Number of examples to train on in a single batch. print_every : int, optional Prints progress and average loss after every `print_every` batches. check_gradients_every : int or None, optional Compares computed gradients and autograd gradients after every `check_gradients_every` batches. Useful for debugging, doesn't compare by default. Examples -------- .. sourcecode:: pycon >>> from gensim.models.poincare import PoincareModel >>> relations = [('kangaroo', 'marsupial'), ('kangaroo', 'mammal'), ('gib', 'cat')] >>> model = PoincareModel(relations, negative=2) >>> model.train(epochs=50) r*Multi-threaded version not implemented yetr)divideinvalidztraining model of size %d with %d workers on %d relations for %d epochs and %d burn-in epochs, using lr=%.5f burn-in lr=%.5f negative=%drzDstarting burn-in (%d epochs)----------------------------------------)epochsr print_everycheck_gradients_everyTzburn-in finishedzEstarting training (%d epochs)----------------------------------------ztraining finishedNr)r$NotImplementedErrorrFseterrr;r<rr9rr'r"r!r#r(_train_batchwiser )r1rrrr old_settingss r2trainzPoincareModel.trainZsx4 .s!NNNT/4NNNr4)rz2training on epoch %d, examples #%d-#%d, loss: %.2fz5time taken for %d examples: %.2f s, %.2f examples / sN)r$rrDrvr9rr-shuffletimerboolrlossr;r<)r1rrrrepochr{avg_loss last_time batch_numr should_printr batch_indicesrMresult time_takenspeeds` r2rzPoincareModel._train_batchwises ?@@@KKO&3ZGHIII!% I"H% #  # #r4)Fr)r)rrN)__name__ __module__ __qualname____doc__rFr`r3r0rKrLrJror staticmethodrrr classmethodrrrrrrrrr __classcell__rs@r2rrEs,)+#AW[ru4OSUS]deN%N%N%N%`>:>:>:>:@ttt ??? 999 ???&+++Z n n n\ nD  \ D99999([0####J#>#>#>#>J"*//\/<bbb66"6"6"6"p)#)#)#)#)#)#)#)#r4rc8eZdZdZd dZdZdZdZdZdZ d S) rzCompute Poincare distances, gradients and loss for a training batch. Store intermediate state to avoid recomputing multiple times. rcd|jtjddddf|_||_||_||_||_d|_d|_ d|_ d|_ d|_ d|_ d|_d|_d|_d|_d|_d|_d|_d|_d|_d|_dS)ac Initialize instance with sets of vectors for which distances are to be computed. Parameters ---------- vectors_u : numpy.array Vectors of all nodes `u` in the batch. Expected shape (batch_size, dim). vectors_v : numpy.array Vectors of all positively related nodes `v` and negatively sampled nodes `v'`, for each node `u` in the batch. Expected shape (1 + neg_size, dim, batch_size). indices_u : list of int List of node indices for each of the vectors in `vectors_u`. indices_v : list of lists of int Nested list of lists, each of which is a list of node indices for each of the vectors in `vectors_v` for a specific node `u`. regularization_coeff : float, optional Coefficient to use for l2-regularization NF)rrFrrrrrr&rrnorms_unorms_vr"rgammardistance_gradients_urdistance_gradients_vr_distances_computed_gradients_computed_distance_gradients_computed_loss_computed)r1rrrrr&s r2r3zPoincareBatch.__init__s(#RZAAA%56"""$8!"#     $(!$(! #( #( ,1)#r4c||||dS)z/Convenience method to perform all computations.N)compute_distancescompute_distance_gradientscompute_gradients compute_lossr1s r2rzPoincareBatch.compute_allsP     '')))     r4cf|jrdStj|j|jz d}tj|jd}tj|jd}d|dzz }d|dzz }dd|dz||zz zz}tj|}tj| }|d} ||_ ||_ ||_ | |_ ||_ ||_||_||_||_||_ d|_dS)zZCompute and store norms, euclidean distances and poincare distances between input vectors.Nrrr6rT)rrFrrrrrrrcrrrZrrrr"r) r1rrrr"rrrrr#s r2rzPoincareBatch.compute_distancess2  #  F)..$.)Hq.QQ)..a.88)..a.88GqL 7a<A A%%$,7E**!#!8!8 " & &A & . ..,&<#      #'   r4c|jrdS|||jddtjddf |jz}||jz}|dxx|jdz cc<|dxx|jdz|j dzz cc<|jddtjddf |j z}||jz}| d}||j dz }t j | rJt j | rJ||_||_d|_dS)zCCompute and store gradients of loss function for all input vectors.Nrr6rT)rrrrrFrrr#r&rrrcisnananyrr)r1rrs r2rzPoincareBatch.compute_gradientsss  #  F     '')))2111bj!!!3CDDtG`` tv A$3A66A$3a7$.:KKK2111bj!!!3CDDtG`` tv !oo1o-- t033 8K((,,.....8K((,,.....&&#'   r4c|jrdS||jdz}d|j|jzt j|jdzdz zz ddt jddf}||jz|jz ddt jddf}||j z|j z }||z}|jdk}| rd| dd|<||_ ||jz|jz ddt jddf}||j z|j z }||z}| rd| dd|<||_d|_dS)zYCompute and store partial derivatives of poincare distance d(u, v) w.r.t all u and all v.Nr6rrrT)rrrr"rrFsqrtrrrrr&rrr)r1euclidean_dists_squaredc_u_coeffsr nan_gradientsv_coeffsrs r2rz(PoincareBatch.compute_distance_gradients1s  ,  F    "&"6!";4: )BGDJ!Oa4G,H,HHI111bjZ[Z[Z[K[ \,tz9TZGBJXYXYXYIYZ'$.84>I" a      CAB ) )!Q / / >$8!-ty8DIEqqq"*VWVWVWGWX'$.84>I"      CAB ) )!Q / / >$8!,0)))r4c|jrdS|tj|jd|jz  |_d|_dS)z=Compute and store loss value for the given batch of examples.NrT)rrrFrrr#rcrr!s r2r zPoincareBatch.compute_lossOsa    F    VD7:TVCDDHHJJJ "r4Nr) r r r r r3rrrrr rr4r2rrs~ -$-$-$-$^(((:(((4111<#####r4rceZdZdZeffd ZfdZedZedZ dZ dZ dd Z d Z d Zd ZddZddZdZdZxZS)ra4Vectors and vocab for the :class:`~gensim.models.poincare.PoincareModel` training class. Used to perform operations on the vectors such as vector lookup, distance calculations etc. (May be used to save/load final vectors in the plain word2vec format, via the inherited methods save_word2vec_format() and load_word2vec_format().) Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # Query the trained model. >>> wv = model.kv.get_vector('kangaroo.n.01') cltt||||d|_dS)Nr8r)rrr3 max_distance)r1 vector_size vector_countr)rs r2r3zPoincareKeyedVectors.__init__ps8 "D))22; TY2ZZZr4ctt|j|i|t|ds!|jd|_dSdS)NrYsyn0)rr_load_specialshasattr__dict__poprY)r1rrrs r2r6z#PoincareKeyedVectors._load_specialsts]8"D))8$I&IIItY'' 5=,,V44DLLL 5 5r4clt||tjddfdS)a~Compute poincare distance between two input vectors. Convenience method over `vector_distance_batch`. Parameters ---------- vector_1 : numpy.array Input vector. vector_2 : numpy.array Input vector. Returns ------- numpy.float Poincare distance between `vector_1` and `vector_2`. Nr)rvector_distance_batchrFr)vector_1vector_2s r2vector_distancez$PoincareKeyedVectors.vector_distancezs2"$99(HRZYZYZYZ]D[\\]^__r4c (tj||z d}tj|}tj|d}tjdd|dzd|dzz d|dzz zz zzS)a"Compute poincare distances between one vector and a set of other vectors. Parameters ---------- vector_1 : numpy.array vector from which Poincare distances are to be computed, expected shape (dim,). vectors_all : numpy.array for each row in vectors_all, distance from vector_1 is computed, expected shape (num_vectors, dim). Returns ------- numpy.array Poincare distance between `vector_1` and each row in `vectors_all`, shape (num_vectors,). rrr6)rFrrr)r< vectors_allrrrs r2r;z*PoincareKeyedVectors.vector_distance_batchs")..K)?a.HHy~~h''INN;QN77 z  A%1tqy=Qa=O*PQ    r4c||}tj|jd}|||}||k}|rdStj||}tj |}|j |S)aGet the node closest to `node` that is lower in the hierarchy than `node`. Parameters ---------- node : {str, int} Key for node for which closest child is to be found. Returns ------- {str, None} Node closest to `node` that is lower in the hierarchy than `node`. If there are no nodes lower in the hierarchy, None is returned. rrNmask distancesrFrrrY get_indexrmaruargminr:r1r all_distancesr node_normrCclosest_child_indexs r2 closest_childz"PoincareKeyedVectors.closest_childt,, INN4>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # What is the distance between the words 'mammal' and 'carnivore'? >>> model.kv.distance('mammal.n.01', 'carnivore.n.01') 2.9742298803339304 Raises ------ KeyError If either of `w1` and `w2` is absent from vocab. ) get_vectorr>)r1w1w2r<r=s r2distancezPoincareKeyedVectors.distances=H??2&&??2&&##Hh777r4c:dd|||zz S)aSCompute similarity based on Poincare distance between vectors for nodes `w1` and `w2`. Parameters ---------- w1 : {str, int} Key for first node. w2 : {str, int} Key for second node. Returns ------- float Similarity between the between the vectors for nodes `w1` and `w2` (between 0 and 1). Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # What is the similarity between the words 'mammal' and 'carnivore'? >>> model.kv.similarity('mammal.n.01', 'carnivore.n.01') 0.25162107631176484 Raises ------ KeyError If either of `w1` and `w2` is absent from vocab. r)r^)r1r\r]s r2 similarityzPoincareKeyedVectors.similarity0s#HA b"---..r4rNct|tr|dkrgS|s|n%jd|}||t|tt fr|nd|stj}ntjd|z}fd|D}|r |d|}|S)aFind the top-N most similar nodes to the given node or vector, sorted in increasing order of distance. Parameters ---------- node_or_vector : {str, int, numpy.array} node key or vector for which similar nodes are to be found. topn : int or None, optional Number of top-N similar nodes to return, when `topn` is int. When `topn` is None, then distance for all nodes are returned. restrict_vocab : int or None, optional Optional integer which limits the range of vectors which are searched for most-similar values. For example, restrict_vocab=10000 would only check the first 10000 node vectors in the vocabulary order. This may be meaningful if vocabulary is sorted by descending frequency. Returns -------- list of (str, float) or numpy.array When `topn` is int, a sequence of (node, distance) is returned in increasing order of distance. When `topn` is None, then similarities for all words are returned as a one-dimensional numpy array with the size of the vocabulary. Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # Which words are most similar to 'kangaroo'? >>> model.kv.most_similar('kangaroo.n.01', topn=2) [(u'kangaroo.n.01', 0.0), (u'marsupial.n.01', 0.26524229460827725)] rN)topncdg|],}r|k j|t|f-Sr)r:rs)rindexrJrxr1s r2rz5PoincareKeyedVectors.most_similar..sU    ?D ?R  u %u]5-A'B'B C   r4) isinstancerrEr:strrHrFr argsort) r1node_or_vectorrbrestrict_vocab nodes_to_useclosest_indicesrrJrxs ` @@r2 most_similarz!PoincareKeyedVectors.most_similarVsL dH % % $( I I NN>::MM,_n_=L NN><HHM nsCk 2 2 77JJJ M&.}==OO&.}1t8LLLO      (     #ETE]F r4rct|tr|}n|}|sj}nfd|D}j|}||S)aCompute Poincare distances from given `node_or_vector` to all nodes in `other_nodes`. If `other_nodes` is empty, return distance between `node_or_vector` and all nodes in vocab. Parameters ---------- node_or_vector : {str, int, numpy.array} Node key or vector from which distances are to be computed. other_nodes : {iterable of str, iterable of int, None}, optional For each node in `other_nodes` distance from `node_or_vector` is computed. If None or empty, distance of `node_or_vector` from all nodes in vocab is computed (including itself). Returns ------- numpy.array Array containing distances to all nodes in `other_nodes` from input `node_or_vector`, in the same order as `other_nodes`. Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # Check the distances between a word and a list of other words. >>> model.kv.distances('mammal.n.01', ['carnivore.n.01', 'dog.n.01']) array([2.97422988, 2.83007402]) >>> # Check the distances between a word and every other word in the vocab. >>> all_distances = model.kv.distances('mammal.n.01') Raises ------ KeyError If either `node_or_vector` or any node in `other_nodes` is absent from vocab. c:g|]}|Sr)rFrs r2rz2PoincareKeyedVectors.distances..s%JJJdT^^D11JJJr4)rerfr[rYr;)r1rh other_nodes input_vector other_vectors other_indicess` r2rEzPoincareKeyedVectors.distancess|T nc * * *??>::LL)L 8 LMMJJJJkJJJM L7M)), FFFr4ct|tr||}n|}tj|S)aCompute absolute position in hierarchy of input node or vector. Values range between 0 and 1. A lower value indicates the input node or vector is higher in the hierarchy. Parameters ---------- node_or_vector : {str, int, numpy.array} Input node key or vector for which position in hierarchy is to be returned. Returns ------- float Absolute position in the hierarchy of the input vector or node. Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> # Get the norm of the embedding of the word `mammal`. >>> model.kv.norm('mammal.n.01') 0.6423008703542398 Notes ----- The position in hierarchy is based on the norm of the vector for the node. )rerfr[rFrr)r1rhrps r2rzPoincareKeyedVectors.normsCD nc * * *??>::LL)Ly~~l+++r4cX||||z S)axCompute relative position in hierarchy of `node_or_vector_1` relative to `node_or_vector_2`. A positive value indicates `node_or_vector_1` is higher in the hierarchy than `node_or_vector_2`. Parameters ---------- node_or_vector_1 : {str, int, numpy.array} Input node key or vector. node_or_vector_2 : {str, int, numpy.array} Input node key or vector. Returns ------- float Relative position in hierarchy of `node_or_vector_1` relative to `node_or_vector_2`. Examples -------- .. sourcecode:: pycon >>> from gensim.test.utils import datapath >>> >>> # Read the sample relations file and train the model >>> relations = PoincareRelations(file_path=datapath('poincare_hypernyms_large.tsv')) >>> model = PoincareModel(train_data=relations) >>> model.train(epochs=50) >>> >>> model.kv.difference_in_hierarchy('mammal.n.01', 'dog.n.01') 0.05382517902410999 >>> model.kv.difference_in_hierarchy('dog.n.01', 'mammal.n.01') -0.05382517902410999 Notes ----- The returned value can be positive or negative, depending on whether `node_or_vector_1` is higher or lower in the hierarchy than `node_or_vector_2`. )r)r1node_or_vector_1node_or_vector_2s r2difference_in_hierarchyz,PoincareKeyedVectors.difference_in_hierarchys*Nyy)**TYY7G-H-HHHr4)rQ)rN)r)r r r r REALr3r6r r>r;rMrPrUrXr^r`rlrErrwrrs@r2rrYsS,9=55555 ``\`$  \ 2666266622,&8&8&8P$/$/$/L====~3G3G3G3Gj&,&,&,P'I'I'I'I'I'I'Ir4rc eZdZdZddZdZdS)PoincareRelationsz:Stream relations for `PoincareModel` from a tsv-like file.utf8 c0||_||_||_dS)aInitialize instance from file containing a pair of nodes (a relation) per line. Parameters ---------- file_path : str Path to file containing a pair of nodes (a relation) per line, separated by `delimiter`. Since the relations are asymmetric, the order of `u` and `v` nodes in each pair matters. To express a "u is v" relation, the lines should take the form `u delimeter v`. e.g: `kangaroo mammal` is a tab-delimited line expressing a "`kangaroo is a mammal`" relation. For a full input file example, see `gensim/test/test_data/poincare_hypernyms.tsv `_. encoding : str, optional Character encoding of the input file. delimiter : str, optional Delimiter character for each relation. N) file_pathencoding delimiter)r1r~rrs r2r3zPoincareRelations.__init__s(#  "r4c#lKtjjd5}tjddkr|}nfd|D}t j|j}|D]7}tjddkrfd|D}t|V8 ddddS#1swxYwYdS)zStream relations from self.file_path decoded into unicode strings. Yields ------- (unicode, unicode) Relation from input file. rbrc3LK|]}|jVdSNdecoder)rliner1s r2rz-PoincareRelations.__iter__..Ds1IIT]33IIIIIIr4rcDg|]}|jSrr)rvaluer1s r2rz.PoincareRelations.__iter__..Is'HHH55<< 66HHHr4N) r openr~sys version_infocsvreaderrtuple)r1file_objlinesrrows` r2__iter__zPoincareRelations.__iter__7s"Z - - !"Q& J IIIIIIIZ@@@F ! !#A&*IHHHHCHHHCCjj     ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !sA=B))B-0B-N)r{r|)r r r r r3rrr4r2rzrzs=DD####0!!!!!r4rzc$eZdZdZdZdZdZdS)rz#Buffer and return negative samples.c"||_d|_dS)zInitialize instance from list or numpy array of samples. Parameters ---------- items : list/numpy.array List or array containing negative samples. rN)_items_current_index)r1rs r2r3zNegativesBuffer.__init__Ps r4c:t|j|jz S)zGet the number of items remaining in the buffer. Returns ------- int Number of items in the buffer that haven't been consumed yet. )r9rrr!s r2rhzNegativesBuffer.num_items\s4;$"555r4cX|j}||z}|xj|z c_|j||S)aGet the next `num_items` from buffer. Parameters ---------- num_items : int Number of items to fetch. Returns ------- numpy.array or list Slice containing `num_items` items from the original data. Notes ----- No error is raised if less than `num_items` items are remaining, simply all the remaining items are returned. )rr)r1rh start_index end_indexs r2rkzNegativesBuffer.get_itemsgs<&) )+  y({;y011r4N)r r r r r3rhrkrr4r2rrMsG--     6 6 622222r4rc>eZdZdZdZedZddZddZdS)ReconstructionEvaluation=Evaluate reconstruction on given network for given embedding.ct}tt}tj|d5}t j|d}|D]}t |dks Jd||d}||d} ||| | || g dddn #1swxYwY||_ ||_ ||_ dS) aWInitialize evaluation instance with tsv file containing relation pairs and embedding to be evaluated. Parameters ---------- file_path : str Path to tsv file containing relation pairs. embedding : :class:`~gensim.models.poincare.PoincareKeyedVectors` Embedding to be evaluated. rr|rr6%Hypernym pair has more than two itemsrrN) rrr rrrr9rFrCrNrrM embedding) r1r~rrrMfrr item_1_index item_2_indexs r2r3z!ReconstructionEvaluation.__init__sA$$ Z 3 ' ' ;1ZT222F ; ;3xx1}MM&MMMM(223q6:: (223q6:: ,'++L999 lL9::::  ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ""sB!C&&C*-C*c||}tj|d}d|j|<||ddtjfkddz}tj|tjt|z}tjdt|dztj|z }t||fS)a:Compute ranks and Average Precision of positive relations. Parameters ---------- all_distances : numpy.array of float Array of all distances (floats) for a specific item. positive_relations : list List of indices of positive relations for the item. Returns ------- (list of int, float) The list contains ranks of positive relations in the same order as `positive_relations`. The float is the Average Precision of the ranking, e.g. ([1, 2, 3, 20], 0.610). FrBTNrr rFrGrurCrrcsortaranger9meanrv)rJpositive_relationspositive_relation_distancesnegative_relation_distancesranks map_ranks avg_precisions r2(get_positive_relation_ranks_and_avg_preczAReconstructionEvaluation.get_positive_relation_ranks_and_avg_precs$'44F&G#&(ekk-ek&L&L#?C#();<,/J111bj=/YY^^de^ffijjGENNRYs5zz%:%:: )As9~~'9::RWY=O=OOUUWW E{{M))r4Nc<||\}}||dS)arEvaluate all defined metrics for the reconstruction task. Parameters ---------- max_n : int, optional Maximum number of positive relations to evaluate, all if `max_n` is None. Returns ------- dict of (str, float) (metric_name, metric_value) pairs, e.g. {'mean_rank': 50.3, 'MAP': 0.31}.  mean_rankMAPevaluate_mean_rank_and_mapr1max_nrmap_s r2evaluatez!ReconstructionEvaluation.evaluate)99%@@ 4&t444r4cg}g}t|jdD]\}}||jvrt|j|}|jj|}|j|}|||\} } || z }|| |||krntj |tj |fS)a;Evaluate mean rank and MAP for reconstruction. Parameters ---------- max_n : int, optional Maximum number of positive relations to evaluate, all if `max_n` is None. Returns ------- (float, float) (mean_rank, MAP), e.g (50.3, 0.31). rr) rrrMrvrr:rErrBrFr) r1rravg_precision_scoresrrQitem_relations item_termitem_distancespositive_relation_ranksrs r2rz3ReconstructionEvaluation.evaluate_mean_rank_and_maps! 1555  GAt4>) !$."677N3D9I!^55i@@N==nn]] 3 #] , ,E ' ' 6 6 6 QY wu~~rw';<<<eZdZdZdZedZddZddZdS)LinkPredictionEvaluationrct}ttttd}||d}|D]\}}tj|d5} t j| d} | D]} t| dks Jd|| d} || d} |||  | | | | g d d d n #1swxYwY||_||_ ||_ d S) aInitialize evaluation instance with tsv file containing relation pairs and embedding to be evaluated. Parameters ---------- train_path : str Path to tsv file containing relation pairs used for training. test_path : str Path to tsv file containing relation pairs to evaluate. embedding : :class:`~gensim.models.poincare.PoincareKeyedVectors` Embedding to be evaluated. )knownunknownrr|rr6rrrN) rrrr rrrr9rFrCrNrMr)r1 train_path test_pathrrrM data_files relation_type data_filerrrrrs r2r3z!LinkPredictionEvaluation.__init__s)#..;s;K;KLL )i@@ (2(8(8(:(: ? ? $M9Is++ ?qA666!??Cs88q=QQ*QQQQ#,#6#6s1v#>#>L#,#6#6s1v#>#>Lm,\:>>|LLLLL, !=>>>> ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ""s+B'DD# &D# c||}tj|d}d|j|<d|j|<||ddtjfkddz}tj|tjt|z}tjdt|dztj|z }t||fS)aCompute ranks and Average Precision of unknown positive relations. Parameters ---------- all_distances : numpy.array of float Array of all distances for a specific item. unknown_relations : list of int List of indices of unknown positive relations. known_relations : list of int List of indices of known positive relations. Returns ------- tuple (list of int, float) The list contains ranks of positive relations in the same order as `positive_relations`. The float is the Average Precision of the ranking, e.g. ([1, 2, 3, 20], 0.610). FrBTNrrr)rJunknown_relationsknown_relationsunknown_relation_distancesrrrrs r2'get_unknown_relation_ranks_and_avg_precz@LinkPredictionEvaluation.get_unknown_relation_ranks_and_avg_precs(&33D%E"&(ekk-ek&L&L#>B#():;<@#(9,/I!!!RZ-/XX]]cd]eehiiGENNRYs5zz%:%:: )As9~~'9::RWY=O=OOUUWW E{{M))r4Nc<||\}}||dS)asEvaluate all defined metrics for the link prediction task. Parameters ---------- max_n : int, optional Maximum number of positive relations to evaluate, all if `max_n` is None. Returns ------- dict of (str, float) (metric_name, metric_value) pairs, e.g. {'mean_rank': 50.3, 'MAP': 0.31}. rrrs r2rz!LinkPredictionEvaluation.evaluate%rr4cg}g}t|jdD]\}}||jdvrt|jd|}t|jd|}|jj|}|j|} || ||\} } || z }|| |||krntj |tj |fS)aBEvaluate mean rank and MAP for link prediction. Parameters ---------- max_n : int, optional Maximum number of positive relations to evaluate, all if `max_n` is None. Returns ------- tuple (float, float) (mean_rank, MAP), e.g (50.3, 0.31). rrrr) rrrMrvrr:rErrBrFr) r1rrrrrQrrrrunknown_relation_ranksrs r2rz3LinkPredictionEvaluation.evaluate_mean_rank_and_map6s! 1555  GAt4>)44  $T^I%>t%D E E "4>'#:4#@AAO3D9I!^55i@@N<<^M^`opp 2 "M + +E ' ' 6 6 6 QY wu~~rw';<<<>(3K3KQv778<GGs ,/ AcN|d|z}d|D}|S)aZFind terms in the `trie` beginning with the `word`. Parameters ---------- trie : :class:`pygtrie.Trie` Trie to use for finding matching terms. word : str Input word to use for prefix search. Returns ------- list of str List of matching terms. z%s.c>g|]\}}d|S))join)r key_charsrs r2rzCLexicalEntailmentEvaluation.find_matching_terms..s)MMM1AE"''),,MMMr4)r)rwordmatchesmatching_termss r2rz/LexicalEntailmentEvaluation.find_matching_termss2"**UT\**MMWMMMr4c ddlm}n#t$rtdwxYw|}|jD]}d||<|S)aCreate trie with vocab terms of the given embedding to enable quick prefix searches. Parameters ---------- embedding : :class:`~gensim.models.poincare.PoincareKeyedVectors` Embedding for which trie is to be created. Returns ------- :class:`pygtrie.Trie` Trie containing vocab terms of the input embedding. r)Triezapygtrie could not be imported, please install pygtrie in order to use LexicalEntailmentEvaluationT)pygtrier ImportErrorr?)rr vocab_triekeys r2create_vocab_triez-LexicalEntailmentEvaluation.create_vocab_tries u $ $ $ $ $ $ $ u u usuu u uTVV ) # #C"JsOOs #cg}g}d}d}||}|jD]f\\}}} |||||} n#t$r|dz }Y3wxYw|dz }|| || gt d|t|jfzt||} | j S)aqEvaluate spearman scores for lexical entailment for given embedding. Parameters ---------- embedding : :class:`~gensim.models.poincare.PoincareKeyedVectors` Embedding for which evaluation is to be done. Returns ------- float Spearman correlation score for the task for input embedding. rrzskipped pairs: %d out of %d) rrrrr=rBr;r<r9r correlation) r1rpredicted_scoresrskippedr7rrrexpected_scorepredicted_scorespearmans r2evaluate_spearmanz-LexicalEntailmentEvaluation.evaluate_spearmans++I66 04 0A0A0C0C 3 3 , VVn "&"5"5iVU["\"\   1   QJE  # #O 4 4 4  " "> 2 2 2 2 1Wc$+>N>N4OOPPP_.>??##sAA+*A+N) r r r r r3rr rrr rr4r2rrVsEE$$H$H$HL\(\2$$$$$r4r)(r rloggingnumbersrrr collectionsrrr rFrr+rrx scipy.statsrautogradr rrrgensimr r gensim.models.keyedvectorsr getLoggerr r;SaveLoadrrrrzrrrrrr4r2rs##J  ,,,,,,,,66666666!!!!!!))))))#"""""""333333  8 $ $v #v #v #v #v #ENv #v #v #rX#X#X#X#X#X#X#X#v@I@I@I@I@I<@I@I@IF.!.!.!.!.!.!.!.!b0202020202020202fd=d=d=d=d=d=d=d=Nl=l=l=l=l=l=l=l=^H$H$H$H$H$H$H$H$H$H$sAA  A