Join arrays `r1` and `r2` on key `key`. The key should be either a string or a sequence of string corresponding to the fields used to join the array. An exception is raised if the `key` field cannot be found in the two input arrays. Neither `r1` nor `r2` should have any dupli
(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2',
defaults=None, usemask=True, asrecarray=False)
| 1473 | |
| 1474 | @array_function_dispatch(_join_by_dispatcher) |
| 1475 | def join_by(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2', |
| 1476 | defaults=None, usemask=True, asrecarray=False): |
| 1477 | """ |
| 1478 | Join arrays `r1` and `r2` on key `key`. |
| 1479 | |
| 1480 | The key should be either a string or a sequence of string corresponding |
| 1481 | to the fields used to join the array. An exception is raised if the |
| 1482 | `key` field cannot be found in the two input arrays. Neither `r1` nor |
| 1483 | `r2` should have any duplicates along `key`: the presence of duplicates |
| 1484 | will make the output quite unreliable. Note that duplicates are not |
| 1485 | looked for by the algorithm. |
| 1486 | |
| 1487 | Parameters |
| 1488 | ---------- |
| 1489 | key : {string, sequence} |
| 1490 | A string or a sequence of strings corresponding to the fields used |
| 1491 | for comparison. |
| 1492 | r1, r2 : arrays |
| 1493 | Structured arrays. |
| 1494 | jointype : {'inner', 'outer', 'leftouter'}, optional |
| 1495 | If 'inner', returns the elements common to both r1 and r2. |
| 1496 | If 'outer', returns the common elements as well as the elements of |
| 1497 | r1 not in r2 and the elements of not in r2. |
| 1498 | If 'leftouter', returns the common elements and the elements of r1 |
| 1499 | not in r2. |
| 1500 | r1postfix : string, optional |
| 1501 | String appended to the names of the fields of r1 that are present |
| 1502 | in r2 but absent of the key. |
| 1503 | r2postfix : string, optional |
| 1504 | String appended to the names of the fields of r2 that are present |
| 1505 | in r1 but absent of the key. |
| 1506 | defaults : {dictionary}, optional |
| 1507 | Dictionary mapping field names to the corresponding default values. |
| 1508 | usemask : {True, False}, optional |
| 1509 | Whether to return a MaskedArray (or MaskedRecords is |
| 1510 | `asrecarray==True`) or a ndarray. |
| 1511 | asrecarray : {False, True}, optional |
| 1512 | Whether to return a recarray (or MaskedRecords if `usemask==True`) |
| 1513 | or just a flexible-type ndarray. |
| 1514 | |
| 1515 | Notes |
| 1516 | ----- |
| 1517 | * The output is sorted along the key. |
| 1518 | * A temporary array is formed by dropping the fields not in the key for |
| 1519 | the two arrays and concatenating the result. This array is then |
| 1520 | sorted, and the common entries selected. The output is constructed by |
| 1521 | filling the fields with the selected entries. Matching is not |
| 1522 | preserved if there are some duplicates... |
| 1523 | |
| 1524 | """ |
| 1525 | # Check jointype |
| 1526 | if jointype not in ('inner', 'outer', 'leftouter'): |
| 1527 | raise ValueError( |
| 1528 | "The 'jointype' argument should be in 'inner', " |
| 1529 | "'outer' or 'leftouter' (got '%s' instead)" % jointype |
| 1530 | ) |
| 1531 | # If we have a single key, put it in a tuple |
| 1532 | if isinstance(key, str): |