agarie / measurable

Various distance and similarity measures for machine learning.

Hey!

I'm a Software Engineer initially trained in Electrical Engineering and Control Systems.

• I currently work at Tarmac, a software consultancy from Minneapolis, US, as a Senior Software Engineer. I deal mainly with Rails and React.
• 🔭 Up until 2022 I worked at Mercúrio, a company I co-founded in Brazil that specializes in digital repositories and digitization projects for Cultural Heritage Institutions. I wrote most of our internal tools and customized open source repository software—like AtoM, Archivematica, DSpace, Collective Access—to our client's needs.
• 🌱 I’m currently:
  • Studying PostgreSQL internals and optimization strategies 📇
  • Rebuilding my home office and personal workshop 🛠️

---

• ⚡ Fun facts:
  1. I studied Control Engineering at the University of São Paulo but ended up working in software development. Turns out the knowledge I developed there was useful when I designed and built a scanner for large maps while working at Mercúrio.
  2. I spent one year as a Computer Engineering exchange student in Arizona, USA (at ERAU). Due to the lower amount of coursework there compared to Brazil, I spent a lot of time reading and studying about computers, programming and contributing to open source communities. I still have notes written during that time that come in handy.
  3. Most of my early social life started as part of a Pokémon community in Brazil, and I joined the local league as a Tournament Organizer from 2007 up until 2018. I met my wife in one of these tournaments—she ended up becoming a National Champion.
  4. Between 2016 and 2018 I was invited by The Pokémon Company as a Judge for several international tournaments. Thus I can say I visited Australia, Europe and some parts of the US on Pikachu's dime.

measurable's Issues

It is not possible to implement "Normalized" distance.

In my work I need to use distance function which needs to be initialized with some data. As an example of such distance I can name https://en.wikipedia.org/wiki/Mahalanobis_distance . It needs to be initialized with covariance matrix. Since distances in your lib is just functions, it is impossible to do. Can you suggest any ideas to implement such initialization? Or, if you are interested in, can I offer my assistance with object reimplementation of distance functions?

Documentation

Each metric must have one or two examples and links to articles or, at the very least, a Wikipedia entry explaining what it's about.

A short explanation for each one, maybe with examples of where it's mainly used, is a good idea as well.

License missing from gemspec

Some companies will only use gems with a certain license.
The canonical and easy way to check is via the gemspec,

via e.g.

spec.license = 'MIT'
# or
spec.licenses = ['MIT', 'GPL-2']

Even for projects that already specify a license, including a license in your gemspec is a good practice, since it is easily
discoverable there without having to check the readme or for a license file. For example, it is the field that rubygems.org uses to display a gem's license.

For example, there is a License Finder gem to help companies ensure all gems they use
meet their licensing needs. This tool depends on license information being available in the gemspec. This is an important enough
issue that even Bundler now generates gems with a default 'MIT' license.

If you need help choosing a license (sorry, I haven't checked your readme or looked for a license file), github has created a license picker tool.

In case you're wondering how I found you and why I made this issue, it's because I'm collecting stats on gems (I was originally looking for download data) and decided to collect license metadata,too, and make issues for gemspecs not specifying a license as a public service :).

I hope you'll consider specifying a license in your gemspec. If not, please just close the issue and let me know. In either case, I'll follow up. Thanks!

p.s. I've written a blog post about this project

Specs for all metrics

Each metric should be tested on arrays and nvectors and show some calculations (preferably with "real" inputs). Also, whenever possible, one or more specs confirming some mathematical property.

Possibly revisit implementation of jaccard index

The output of Measurable.jaccard_index appears to be inconsistent with what I might expect coming from other implementations:

$ pry --gem
[1] pry(main)> u = [1, 0, 1]
=> [1, 0, 1]
[2] pry(main)> v = [1, 1, 1]
=> [1, 1, 1]
[3] pry(main)> Measurable.jaccard_index(u, v)
=> 0.6666666666666666
[4] pry(main)> Measurable.jaccard_index(v, u)
=> 0.6666666666666666
[5] pry(main)> require 'distance_measures'
=> true
[6] pry(main)> u.jaccard_index(v)
=> 0.5
[7] pry(main)> v.jaccard_index(u)
=> 0.5
[8] pry(main)> require 'jaccard'
=> true
from (pry):9:in `__pry__'
[9] pry(main)> Jaccard.coefficient(u, v)
=> 0.5
[10] pry(main)> Jaccard.coefficient(v, u)
=> 0.5

$ python
>>> import distance
>>> u = [1, 0, 1]
>>> v = [1, 1, 1]
>>> 1 - distance.jaccard(u, v)
0.5

Am I misunderstanding the intent of Measurable.jaccard_index?, Otherwise, I could provide a patch with a fix.

Add new, more specific exceptions

Create exceptions for when the vectors have different sizes (e.g. DiffLengthException).

Is there any other case?

measurable future

@agarie,

I was thinking about the library for metrics as well and found your repo. I guess that it would be cool to make this gem look like it should be.

As I see, the development cycle of NMatrix is not as short as in case of this gem. The demand for this gem is pretty high. Nobody cares about NMatrix. People care about tasty Array mixin with C bindings. There should be a product like this.

Please, tell me if you plan to support this library. It seems strange for me to make a new gem with similar features. As far as I work with ML issues in the context of Ajaila. I'd like to make it a part of family of Ajaila extensions.

Would you like to make this gem a part of Ajaila ecosystem? Or I can make a fork and continue on my own. Both variants are fine.

Best,
Max

Allow "family of methods" to be required separately

It'd be pretty cool to require specific methods, e.g. require 'measurable/cosine'.

It's easy to do this now because it's equivalent to requiring specific Ruby files. However, when C bindings to optimized methods are added, I don't know how I'll handle this.

Anyway.