EasyMunk Python add-on for Munkres
EasyMunk provides a versatile interface alternative and pre-processing handler to the Munkres module for score-based (Hungarian algorithm) assignments.
Purpose
The EasyMunk module interfaces with the Munkres module to:
- Provide an easy and adaptable method of pair assignment.
- Reduce the amount of pre-processing required for munkres.
- Automatically account for some special-case munkres decisions.
- Do all of the above without reducing munkres' functionality.
See this module's easymunk.py for use instructions, or the munkres documentation for more algorithm details.
Installation
- Ensure Python and Pip are in the environment path variable.
- Inside a terminal; enter the command "pip install easymunk"
Currently only tested compatible with Python 3.
Use
- At the top of your .py file, add "from easymunk import EasyMunk"
- Although EasyMunk is a class, self is never used. You can call easymunk.EasyMunk class methods without creating an instance.
- The two public methods are EasyMunk.print_info() and EasyMunk.sort()
EasyMunk.print_info()
Prints the most recent .sort() method's profit (if it exists) and cost matrices using munkres.print_matrix() for readability, the chosen indices in the (primary objects, secondary objects) array created by EasyMunk, and the sum total cost & profit for the chosen solution.
EasyMunk.sort()
Please see this module's Documentation at the top of ./easymunk/easymunk.py for further explanation & examples, and at the top of the EasyMunk.score() method definition for further details on parameters and functions.
External Functions
All external function parameters passed as positional, excluding **kwargs. Optional parameters (such as list of lists of dicts containing pair score / primary object / secondary object, or *args) which conflict with an external function's call are removed starting with *args, then **kwargs; at which point the least likely optional parameter is removed and *args and **kwargs are introduced again before continuing the cull cycle to just the minimum parameters. The working function parameter syntax is cached, but this process will always run a full cycle starting with the last cached syntax if a TypeError is met - meaning you can have dynamic method parameters or methods.
Parameters
- list primary_objects: List of anything you wish to assign an object/task/etc.
- list secondary_objects: List of anything you wish to assign primary_objects to.
- function score_function: Score function for each possible pair; must return a numeric metric.
- score_function input: primary_object, secondary_object.
- dynamically-detected optional input: *args, **kwargs.
- score_function return float: Your cost function's return should be an int or float or long int or munkres.DISALLOWED representing that match's cost or profit.
- function assignment_function: Function for operating on pair assignments externally.
- assignment_function input: primary_object, secondary_object.
- dynamically-detected optional input: *args, **kwargs.
- assignment_function return None: Your assignment function should not return anything.
- optional bool convert_profit_to_cost: Determine if profit to cost function is used. Default is False.
-
optional function profit_to_cost_function: Run after score_function if convert_profit_to_cost is True.
- A default conversion function of (cost_index_value = max(profit_array) - profit_index_value) is used if left as None.
- profit_to_cost_function input: single profit value.
- dynamically-detected optional input: value's primary object, value's secondary object, entire list of lists of profit dicts as {"score": profit, "primary": primary_object, "secondary": secondary_object}, *args, **kwargs.
- profit_to_cost_function return float: Your conversion function's return should be the same type as the cost_function's return; in other words, a numeric value for pair score.
- optional tuple *args: Optional arguments passed to score_function, assignment_function, and profit_to_cost_function.
- optional dict **kwargs: Optional keyword arguments passed to score_function, assignment_function, and profit_to_cost_function.
Class Variables
- Recommendations on using the provided EasyMunk class attributes to change different operations such as dict key names and first-attempt function syntax / syntax attempt order to be completed. However, documentation on what each class variable is responsible for is available within the EasyMunk module.
Copyright
EasyMunk module by Andrew M. Hogan. (EasyMunk © 2018 Hogan Consulting Group)
License
Licensed under the Apache License.