streamlining most_similar_cosmul and evaluate_word_analogies

[n3hrox]

Closes: #2535

This is my first PR for gensim so all comments are welcome.
To be honest I have no idea how to test restrict_vocab for most_similar_cosmul or most_similar for evaluate_word_analogies. I wanted to write something similar to already existing tests for these keywords but did not find any (nor tests for restrict_vocab keyword in case of most_similar function and nor most_similar keyword in case of accuracy function)

Summary:

• Added new restrict_vocab parameter to most_similar_cosmul
• Improved most_similar_cosmul shorthand to handle both positive and negative cases
• Parameterized similarity function in evaluate_word_analogies

[gojomo]

+1 (having looked over code, but not tested functionality)

[mpenkov]

Thank you for your contribution. I left you some minor comments. Please have a look.

[mpenkov]

If I understand correctly, this enables behavior like:

most_similar_cosmul('dog', 'cat')

where dog is positive and cat is negative. That's helpful shorthand, but without documentation, people won't find out about it.

Can you please add a paragraph to the docstring explaining the above shorthand?

[gojomo]

Note that this just makes the special type-testing treatment of negative match that of positive (in both most_similar() and most_similar_cosmul()) – but that special treatment, while used extensively in examples, isn't currently documented even in the most_similar() case! I'd suggest that treating negative symmetrically with positive is a good idea, and should also be done in most_similar() for consistency, and both of their doc-comments should be improved/harmonized to explain this behavior.

[n3hrox]

@mpenkov added shorthand in docstring for clarity, is it okay or is there some other place for docs as well that this should be added?

[mpenkov]

@n3hrox Ping! Are you able to finish this PR?

[n3hrox]

@mpenkov I will try to come back to this during weekend. I waited really long for this to be reviewed, started new job and had completely no time during Dec/Jan

[n3hrox]

@mpenkov I adjusted PR accordingly, please re-review

[piskvorky]

@mpenkov what happened here? PR was marked Stale, but it looks like @n3hrox did respond (2 years ago…). Was this good to merge, should I reopen?

[mpenkov]

Yeah, looks like they responded right after we marked it as stale, and then we didn't follow up.

[mpenkov]

I think the correct action is to reopen and push this over the line ourselves.

@n3hrox Sorry for the delay. This fell off our radar.

[codecov]

Codecov Report

Merging #2656 (719bd0e) into develop (a936521) will decrease coverage by 0.01%.
The diff coverage is 71.42%.

@@             Coverage Diff             @@
##           develop    #2656      +/-   ##
===========================================
- Coverage    79.53%   79.52%   -0.02%     
===========================================
  Files           68       68              
  Lines        11781    11785       +4     
===========================================
+ Hits          9370     9372       +2     
- Misses        2411     2413       +2     

Impacted Files	Coverage Δ
gensim/models/keyedvectors.py	82.73% <71.42%> (+0.09%)	⬆️
gensim/utils.py	71.54% <0.00%> (-0.33%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a936521...719bd0e. Read the comment docs.

[mpenkov]

Merging. Thank you for your contribution and your patience @n3hrox !