Mapping implementations for matching groups of elements.
For and introduction to mapping, see Mapping primer.
Classes
|
Enumeration type for cardinality relationships. |
|
Callable wrapper for computing heuristic scores. |
|
A two-way mapping between hashable elements. |
|
Optimal value-candidate matching. |
Bases: Enum
Enumeration type for cardinality relationships.
Cardinalities are comparable using numerical operators, and can be thought of as comparing “preciseness”. The less
ambiguity there is for a given cardinality, the smaller it is in comparison to the others. The hierarchy is given by
1:1 < 1:N = N:1 < M:N. Note that 1:N and N:1 are considered equally precise.
Examples
Comparing cardinalities
>>> from rics.mapping import Cardinality
>>> Cardinality.ManyToOne
<Cardinality.ManyToOne: 'N:1'>
>>> Cardinality.OneToOne
<Cardinality.OneToOne: '1:1'>
>>> Cardinality.ManyToOne < Cardinality.OneToOne
False
Types that may be interpreted as a Cardinality.
alias of Union[str, Cardinality]
One-to-one relationship.
One-to-many relationship.
Many-to-one relationship.
Many-to-many relationship.
Inverse cardinality. For symmetric cardinalities, self.inverse == self.
Inverse cardinality.
See also
Symmetry flag. For symmetric cardinalities, self.inverse == self.
Symmetry flag.
See also
Derive a Cardinality from counts.
left_count – Number of elements on the left-hand side.
right_count – Number of elements on the right-hand side.
A Cardinality.
ValueError – For counts < 1.
Convert to cardinality.
arg – Argument to parse.
strict – If True, arg must match exactly when it is given as a string.
A Cardinality.
ValueError – If the argument could not be converted.
Bases: Generic[ValueType, CandidateType, ContextType]
Callable wrapper for computing heuristic scores.
Instances are callable. Signature is given by ScoreFunction.
A mechanism for forced matching. Score is set to +∞ for short-circuited candidates, and -∞ for the rest. No further matching will be performed after this point, so ensure that all desired candidates are returned by chosen filters.
Trigger short-circuiting if there is an exact value-candidate match.
All heuristics are applied and scores are computed.
If no short-circuiting is triggered in step 2, yield max score for each candidate.
score_function – A ScoreFunction to wrap.
heuristics – Iterable of heuristics or tuples (heuristic, kwargs) to apply to the (value, candidates)
inputs of score_function.
An AliasFunction, which accepts and returns a tuple
(value, candidates) to be evaluated.
A FilterFunction, which accepts a tuple (value, candidates) and
returns a subset of candidates. If any candidates are returned, short-circuiting is triggered.
Notes
Heuristic function input order = application order.
You may add mutate=True to the heuristics kwargs to forward to the modifications made by that function.
Return the underlying likeness score function.
Add a new heuristic.
A two-way mapping between hashable elements.
cardinality – Explicit cardinality. Derive if None.
left_to_right – A left-to-right mapping of elements.
right_to_left – A right-to-left mapping of elements.
_verify – If False, input checks are disabled. Intended for internal use.
ValueError – If both of left_to_right and right_to_left are None.
ValueError – If verification of two-sided input fails, and verify=True.
CardinalityError – If explicit cardinality < cardinality, and verify=True.
Cardinality with which this mapping was created.
Cardinality with which this mapping was created.
Reverse the mapping by swapping the sides.
A copy with data identical to the calling instance, but with sides inversed compared to the caller.
Return a flattened version of self as a dict.
A dict {left: right}.
CardinalityError – If cardinality is not OneToOne or ManyToOne.
Perform a selection on left-side elements.
elements – Elements to select.
exclude – If True, return everything except the given elements.
A new Mapping for the selection.
KeyError – If any of the chosen elements do not exist and exclude=False.
Perform a selection on right-side elements.
elements – Elements to select.
exclude – If True, return everything except the given elements.
A new instance for the selection.
KeyError – If any of the chosen elements do not exist and exclude=False.
Bases: Generic[ValueType, CandidateType, ContextType]
Optimal value-candidate matching.
For an introduction to mapping, see the Mapping primer page.
score_function – A callable which accepts a value k and an ordered collection of candidates c, returning a
score s_i for each candidate c_i in c. Default: s_i = float(k == c_i). Higher=better match.
score_function_kwargs – Keyword arguments for score_function.
filter_functions – Function-kwargs pairs of filters to apply before scoring.
min_score – Minimum score s_i, as given by score(k, c_i), to consider k a match for c_i.
overrides – If a dict, assumed to be 1:1 mappings (value to candidate) which override the scoring logic. If
InheritedKeysDict, the context passed to apply() is used to retrieve specific overrides.
unmapped_values_action – Action to take if mapping fails for any values.
unknown_user_override_action – Action to take if a UserOverrideFunction returns an
unknown candidate. Unknown candidates, i.e. candidates not in the input candidates collection, will not be
used unless ‘ignore’ is chosen. As such, ‘ignore’ should rather be interpreted as ‘allow’.
cardinality – Desired cardinality for mapped values. Derive for each matching if None.
enable_verbose_logging – If True, enable verbose logging for the apply() function. Has no effect when
the log level is above logging.DEBUG.
Map values to candidates.
values – Iterable of elements to match to candidates.
candidates – Iterable of candidates to match with value. Duplicate elements will be discarded.
context – Context in which mapping is being done. Required when using context-sensitive overrides.
override_function – A callable that takes inputs (value, candidates, context) that returns either
None (let the regular mapping logic decide) or one of the candidates. How non-candidates returned
is handled is determined by the unknown_user_override_action property.
**kwargs – Runtime keyword arguments for score and filter functions. May be used to add information which is
not known when the Mapper is initialized.
A DirectionalMapping on the form {value: [matched_candidates, ...]}. May be turned into a
plain dict {value: candidate} by using the DirectionalMapping.flatten() function (only if
DirectionalMapping.cardinality is of type Cardinality.one_right).
MappingError – If any values failed to match and unmapped_values_action='raise'.
BadFilterError – If a filter returns candidates that are not a subset of the original candidates.
UserMappingError – If override_function returns an unknown candidate and
unknown_user_override_action != 'ignore'
ValueError – If passing context=None (the default) when context_sensitive_overrides is True.
Compute likeness scores.
values – Iterable of elements to match to candidates.
candidates – Iterable of candidates to match with value. Duplicate elements will be discarded.
context – Context in which mapping is being done.
override_function – A callable that takes inputs (value, candidates, context) that returns either
None (let the regular mapping logic decide) or one of the candidates. How non-candidates returned
is handled is determined by the unknown_user_override_action property.
**kwargs – Runtime keyword arguments for score and filter functions. May be used to add information which is
not known when the Mapper is initialized.
A DataFrame of value-candidate match scores, with DataFrame.index=values and
DataFrame.columns=candidates.
BadFilterError – If a filter returns candidates that are not a subset of the original candidates.
UserMappingError – If override_function returns an unknown candidate and
unknown_user_override_action != 'ignore'
Create a DirectionalMapping from match scores.
scores – A score matrix, where scores.index are values and score.columns are treated as the
candidates.
A DirectionalMapping.
See also
Return upper cardinality bound during mapping.
Return the action to take if mapping fails for any values.
Return the action to take if an override function returns an unknown candidate.
Unknown candidates, i.e. candidates not in the input candidates collection, will not be used unless ‘ignore’ is chosen. As such, ‘ignore’ should rather be interpreted as ‘allow’.
Action to take if a user-defined override function returns an unknown candidate.
Make a copy of this Mapper.
Modules
Mapping errors. |
|
Functions that remove candidates. |
|
Functions which perform heuristics for score functions. |
|
Functions which return a likeness score. |
|
Functions and classes used by the |
|
Types used for mapping. |