1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
|
.. _internals:
{{ header }}
*********
Internals
*********
This section will provide a look into some of pandas internals. It's primarily
intended for developers of pandas itself.
Indexing
--------
In pandas there are a few objects implemented which can serve as valid
containers for the axis labels:
* ``Index``: the generic "ordered set" object, an ndarray of object dtype
assuming nothing about its contents. The labels must be hashable (and
likely immutable) and unique. Populates a dict of label to location in
Cython to do ``O(1)`` lookups.
* ``Int64Index``: a version of ``Index`` highly optimized for 64-bit integer
data, such as time stamps
* ``Float64Index``: a version of ``Index`` highly optimized for 64-bit float data
* ``MultiIndex``: the standard hierarchical index object
* ``DatetimeIndex``: An Index object with ``Timestamp`` boxed elements (impl are the int64 values)
* ``TimedeltaIndex``: An Index object with ``Timedelta`` boxed elements (impl are the in64 values)
* ``PeriodIndex``: An Index object with Period elements
There are functions that make the creation of a regular index easy:
* ``date_range``: fixed frequency date range generated from a time rule or
DateOffset. An ndarray of Python datetime objects
* ``period_range``: fixed frequency date range generated from a time rule or
DateOffset. An ndarray of ``Period`` objects, representing timespans
The motivation for having an ``Index`` class in the first place was to enable
different implementations of indexing. This means that it's possible for you,
the user, to implement a custom ``Index`` subclass that may be better suited to
a particular application than the ones provided in pandas.
From an internal implementation point of view, the relevant methods that an
``Index`` must define are one or more of the following (depending on how
incompatible the new object internals are with the ``Index`` functions):
* ``get_loc``: returns an "indexer" (an integer, or in some cases a
slice object) for a label
* ``slice_locs``: returns the "range" to slice between two labels
* ``get_indexer``: Computes the indexing vector for reindexing / data
alignment purposes. See the source / docstrings for more on this
* ``get_indexer_non_unique``: Computes the indexing vector for reindexing / data
alignment purposes when the index is non-unique. See the source / docstrings
for more on this
* ``reindex``: Does any pre-conversion of the input index then calls
``get_indexer``
* ``union``, ``intersection``: computes the union or intersection of two
Index objects
* ``insert``: Inserts a new label into an Index, yielding a new object
* ``delete``: Delete a label, yielding a new object
* ``drop``: Deletes a set of labels
* ``take``: Analogous to ndarray.take
MultiIndex
~~~~~~~~~~
Internally, the ``MultiIndex`` consists of a few things: the **levels**, the
integer **codes** (until version 0.24 named *labels*), and the level **names**:
.. ipython:: python
index = pd.MultiIndex.from_product(
[range(3), ["one", "two"]], names=["first", "second"]
)
index
index.levels
index.codes
index.names
You can probably guess that the codes determine which unique element is
identified with that location at each layer of the index. It's important to
note that sortedness is determined **solely** from the integer codes and does
not check (or care) whether the levels themselves are sorted. Fortunately, the
constructors ``from_tuples`` and ``from_arrays`` ensure that this is true, but
if you compute the levels and codes yourself, please be careful.
Values
~~~~~~
pandas extends NumPy's type system with custom types, like ``Categorical`` or
datetimes with a timezone, so we have multiple notions of "values". For 1-D
containers (``Index`` classes and ``Series``) we have the following convention:
* ``cls._values`` refers is the "best possible" array. This could be an
``ndarray`` or ``ExtensionArray``.
So, for example, ``Series[category]._values`` is a ``Categorical``.
.. _ref-subclassing-pandas:
Subclassing pandas data structures
----------------------------------
This section has been moved to :ref:`extending.subclassing-pandas`.
|
