IdMap

class rectools.dataset.identifiers.IdMap(external_ids: ndarray)

Bases: object

Mapping between external and internal object ids.

External ids may be any unique hashable values, internal - always integers from 0 to n_objects-1.

Usually you do not need to create this object directly, use from_values class method instead.

When creating directly you have to pass unique external ids.

Parameters

external_ids (np.ndarray) – Array of unique external ids.

Inherited-members

Methods

add_ids(values[, raise_if_already_present])	Add new external ids to current IdMap and return new IdMap.
convert_to_external()	Convert any sequence of internal ids to array of external ids (map internal -> external).
convert_to_internal()	Convert any sequence of external ids to array of internal ids (map external -> internal).
from_dict(mapping)	Create IdMap from dict of external id -> internal id mappings.
from_values(values)	Create IdMap from list of external ids (possibly not unique).
get_external_sorted_by_internal()	Return array of external ids sorted by internal ids.
get_sorted_internal()	Return array of sorted internal ids.

Attributes

external_ids
external_dtype	Return dtype of external ids.
internal_ids	Array of internal ids.
size	Return number of ids in map.
to_external	Map internal->external.
to_internal	Map internal->external.

add_ids(values: Union[Sequence[Hashable], ndarray], raise_if_already_present: bool = False) → IdMap

Add new external ids to current IdMap and return new IdMap. Mapping for old ids does not change. New ids are added to the end of list of external ids.

Parameters

• values (iterable(hashable)) – List of new external ids (may be not unique).

• raise_if_already_present (bool, default False) – If True and some of given ids are already present in the map ValueError will be raised.

Return type

IdMap

Raises

ValueError – If some of given ids are already present in the map and raise_if_already_present flag is True.

convert_to_external(internal: Union[Sequence[int], ndarray], strict: bool = True, return_missing: Literal[False] = False) → ndarray

convert_to_external(internal: Union[Sequence[int], ndarray], strict: bool = True, *, return_missing: Literal[True]) → Tuple[ndarray, ndarray]

Convert any sequence of internal ids to array of external ids (map internal -> external).

Parameters

• internal (sequence(int)) – Sequence of internal ids to convert.

• strict (bool, default True) –

  Defines behaviour when some of given internal ids do not exist in mapping.

  • If True, KeyError will be raised;

  • If False, nonexistent ids will be skipped.

• return_missing (bool, default False) – If True, return a tuple of 2 arrays: external ids and missing ids (that are not in map). Works only if strict is False.

Returns

• np.ndarray – Array of external ids.

• np.ndarray, np.ndarray – Tuple of 2 arrays: external ids and missing ids. Only if strict is False and return_missing is True.

Raises

• KeyError – If some of given internal ids do not exist in mapping and strict flag is True.

• ValueError – If strict and return_missing are both True.

convert_to_internal(external: Union[Sequence[Hashable], ndarray], strict: bool = True, return_missing: Literal[False] = False) → ndarray

convert_to_internal(external: Union[Sequence[Hashable], ndarray], strict: bool = True, *, return_missing: Literal[True]) → Tuple[ndarray, ndarray]

Convert any sequence of external ids to array of internal ids (map external -> internal).

Parameters

• external (sequence(hashable)) – Sequence of external ids to convert.

• strict (bool, default True) –

  Defines behaviour when some of given external ids do not exist in mapping.

  • If True, KeyError will be raised;

  • If False, nonexistent ids will be skipped.

• return_missing (bool, default False) – If True, return a tuple of 2 arrays: internal ids and missing ids (that are not in map). Works only if strict is False.

Returns

• np.ndarray – Array of internal ids.

• np.ndarray, np.ndarray – Tuple of 2 arrays: internal ids and missing ids. Only if strict is False and return_missing is True.

Raises

• KeyError – If some of given external ids do not exist in mapping and strict flag is True.

• ValueError – If strict and return_missing are both True.

property external_dtype: Type

Return dtype of external ids.

classmethod from_dict(mapping: Dict[Hashable, int]) → IdMap

Create IdMap from dict of external id -> internal id mappings. Could be used if mappings were previously defined somewhere else.

Parameters

mapping (dict(hashable, int) :) – Dict of mappings from external ids to internal ids. Internal ids must be integers from 0 to n_objects-1.

Return type

IdMap

classmethod from_values(values: Union[Sequence[Hashable], ndarray]) → IdMap

Create IdMap from list of external ids (possibly not unique).

Parameters

values (iterable(hashable) :) – List of all external ids (may be not unique).

Return type

IdMap

get_external_sorted_by_internal() → ndarray

Return array of external ids sorted by internal ids.

Return type

ndarray

get_sorted_internal() → ndarray

Return array of sorted internal ids.

Return type

ndarray

property internal_ids: ndarray

Array of internal ids.

property size: int

Return number of ids in map.

property to_external: Series

Map internal->external.

property to_internal: Series

Map internal->external.