Base.merge¶

Base.merge(other, point='strict', feature='union', onFeature=None, force=False, *, useLog=None)¶

Combine data from another object with this object.

Merge can be based on point names or a common feature between the objects. How the data will be merged is based upon the string arguments provided to point and feature. If onFeature is None, the objects will be merged on the point names. Otherwise, onFeature must contain only unique values in one or both objects.

Parameters:

other (Base) – The nimble data object containing the data to merge.
point (str) –
The allowed strings for the point and feature arguments are as follows:
- ’strict’ - The points/features in the callee exactly match the points/features in the caller, however, they may be in a different order. If onFeature is None and no names are provided, it will be assumed the order is the same.
- ’union’ - Return all points/features from the caller and callee. If onFeature is None, unnamed points/features will be assumed to be unique. Any missing data from the caller and callee will be filled with np.NaN.
- ’intersection’: Return only points/features shared between the caller and callee. If onFeature is None, point / feature names are required.
- ’left’: Return only the points/features from the caller. Any missing data from the callee will be filled with np.NaN.
feature (str) –
The allowed strings for the point and feature arguments are as follows:
- ’strict’ - The points/features in the callee exactly match the points/features in the caller, however, they may be in a different order. If onFeature is None and no names are provided, it will be assumed the order is the same.
- ’union’ - Return all points/features from the caller and callee. If onFeature is None, unnamed points/features will be assumed to be unique. Any missing data from the caller and callee will be filled with np.NaN.
- ’intersection’: Return only points/features shared between the caller and callee. If onFeature is None, point / feature names are required.
- ’left’: Return only the points/features from the caller. Any missing data from the callee will be filled with np.NaN.
onFeature (identifier, None) – The name or index of the feature present in both objects to merge on. If None, the merge will be based on point names.
force (bool) – When True, the point or feature parameter set to ‘strict’ does not require names along that axis. The merge is forced to continue as True acknowledges that each index along that axis is equal between the two objects. Has no effect if neither parameter is set to ‘strict’.
useLog (bool, None) – Local control for whether to send object creation to the logger. If None (default), use the value as specified in the “logger” “enabledByDefault” configuration option. If True, send to the logger regardless of the global option. If False, do NOT send to the logger, regardless of the global option.

See also

Points.append, Features.append

Examples

A strict case. In this case we will merge using the point names, so point='strict' requires that the each object has the same point names (or one or both have default names) In this example, there is one shared feature between objects. If feature='union', all features (“f1”-“f5”) will be included, if feature='intersection', only the shared feature (“f3”) will be included, feature='left' will only use the features from the left object (not shown, in strict cases ‘left’ will not modify the left object at all).

>>> lstL = [["a", 1, 'X'], ["b", 2, 'Y'], ["c", 3, 'Z']]
>>> fNamesL = ["f1", "f2", "f3"]
>>> pNamesL = ["p1", "p2", "p3"]
>>> left = nimble.data(lstL, pointNames=pNamesL,
...                    featureNames=fNamesL)
>>> lstR = [['Z', "f", 6], ['Y', "e", 5], ['X', "d", 4]]
>>> fNamesR = ["f3", "f4", "f5"]
>>> pNamesR = ["p3", "p2", "p1"]
>>> right = nimble.data(lstR, pointNames=pNamesR,
...                     featureNames=fNamesR)
>>> left.merge(right, point='strict', feature='union')
>>> left
<DataFrame 3pt x 5ft
      f1  f2  f3  f4  f5
    ┌───────────────────
 p1 │ a   1   X   d   4
 p2 │ b   2   Y   e   5
 p3 │ c   3   Z   f   6
>
>>> left = nimble.data(lstL, pointNames=pNamesL,
...                    featureNames=fNamesL)
>>> left.merge(right, point='strict', feature='intersection')
>>> left
<DataFrame 3pt x 1ft
      f3
    ┌───
 p1 │ X
 p2 │ Y
 p3 │ Z
>

Additional merge combinations. In this example, the feature "id" contains a unique value for each point (just as point names do). In the example above we matched based on point names, here the "id" feature will be used to match points.

>>> lstL = [["a", 1, 'id1'], ["b", 2, 'id2'], ["c", 3, 'id3']]
>>> fNamesL = ["f1", "f2", "id"]
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> lstR = [['id3', "x", 7], ['id4', "y", 8], ['id5', "z", 9]]
>>> fNamesR = ["id", "f4", "f5"]
>>> right = nimble.data(lstR, featureNames=fNamesR)
>>> left.merge(right, point='union', feature='union',
...            onFeature="id")
>>> left
<DataFrame 5pt x 5ft
     f1    f2    id  f4    f5
   ┌──────────────────────────
 0 │ a   1.000  id1
 1 │ b   2.000  id2
 2 │ c   3.000  id3  x   7.000
 3 │            id4  y   8.000
 4 │            id5  z   9.000
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='union', feature='intersection',
...            onFeature="id")
>>> left
<DataFrame 5pt x 1ft
      id
   ┌────
 0 │ id1
 1 │ id2
 2 │ id3
 3 │ id4
 4 │ id5
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='union', feature='left',
...            onFeature="id")
>>> left
<DataFrame 5pt x 3ft
     f1    f2    id
   ┌───────────────
 0 │ a   1.000  id1
 1 │ b   2.000  id2
 2 │ c   3.000  id3
 3 │            id4
 4 │            id5
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='intersection', feature='union',
...            onFeature="id")
>>> left
<DataFrame 1pt x 5ft
     f1  f2   id  f4  f5
   ┌────────────────────
 0 │ c   3   id3  x   7
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='intersection',
...            feature='intersection', onFeature="id")
>>> left
<DataFrame 1pt x 1ft
      id
   ┌────
 0 │ id3
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='intersection', feature='left',
...            onFeature="id")
>>> left
<DataFrame 1pt x 3ft
     f1  f2   id
   ┌────────────
 0 │ c   3   id3
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='left', feature='union',
...            onFeature="id")
>>> left
<DataFrame 3pt x 5ft
     f1  f2   id  f4    f5
   ┌───────────────────────
 0 │ a   1   id1
 1 │ b   2   id2
 2 │ c   3   id3  x   7.000
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='left', feature='intersection',
...            onFeature="id")
>>> left
<DataFrame 3pt x 1ft
      id
   ┌────
 0 │ id1
 1 │ id2
 2 │ id3
>
>>> left = nimble.data(lstL, featureNames=fNamesL)
>>> left.merge(right, point='left', feature='left',
...            onFeature="id")
>>> left
<DataFrame 3pt x 3ft
     f1  f2   id
   ┌────────────
 0 │ a   1   id1
 1 │ b   2   id2
 2 │ c   3   id3
>

Keywords: combine, join, unite, group, fuse, consolidate, meld, union, intersection, inner, outer, full outer, left

Nimble

Navigation

Related Topics

Base.merge¶