aliases 0.3.0

Keeping track of aliases

A very small Python package for keeping track of aliases.

Installation

$ pip install aliases

Getting Started

Keeping track of aliases in your data can be annoying. This small packages provides three small classes than can help you in the bookkeeping associated with the occurrences of aliases in your data.

The AliasSpace objects keeps track of existing aliases. As input is accepts a dictionary where a string (the “preferred” form) points to a list of all its aliases. Using the str method on the space, we can transform regular strings into AliasAwareString objects.

>>> from aliases import AliasSpace
>>>
>>> s = AliasSpace(
>>>     {"The Netherlands": ["NL", "Netherlands", "Holland"]},
>>>     case_sensitive=False
>>> )
>>>
>>> s.str("nl")
<'nl' in AliasSpace>

The preferred form of an AliasAwareString is called its representative (because it represents the equivalance class of the string under the equivalance relation of being aliases).

>>> s.str("nl").representative
'The Netherlands'

AliasAwareString objects with the same representative are considered equal and have the same hash.

>>> s.str("holland") == s.str("NL")
True
>>>
>>> data = {s.str("holland"): 12345}
>>> data[s.str("nl")]
12345

The example above already shows how alias aware strings can be used to store data without worrying too much about the different aliases around. However, it is still annoying to cast to an AliasAwareString every time manually. To solve this you can use the AliasAwareDict. This object can be created using the dict method on the space.

>>> data = s.dict(holland=12345)
>>> data['nl']
12345

Finally, the AliasAwareSpace object has a map method which can be used to find the representatives of a list of strings easily. The following example was the original motivation for building this package:

>>> import pandas as pd
>>> df = pd.DataFrame(
>>>    {"Country": ["NL", "Netherlands", "Belgium"], "SomeData": [10, 11, 12]}
>>> )
>>> df
           Country  SomeData
0               NL        10
1      Netherlands        11
2          Belgium        12
>>>
>>> df.assign(Country=s.map(df.Country, return_list=True))
          Country  SomeData
0  The Netherlands        10
1  The Netherlands        11
2          Belgium        12
>>>
>>> df.assign(Country=s.map(df.Country, return_list=True, missing=pd.NA))
           Country  SomeData
0  The Netherlands        10
1  The Netherlands        11
2             <NA>        12

Documentation

Coming soon…