pandas.Series.loc#

property Series.loc[source]#

Access a group of rows and columns by label(s) or a boolean array.

.loc[] is primarily label based, but may also be used with a boolean array.

Allowed inputs are:

A single label, e.g. 5 or 'a', (note that 5 is interpreted as a label of the index, and never as an integer position along the index).
A list or array of labels, e.g. ['a', 'b', 'c'].
A slice object with labels, e.g. 'a':'f'.

Warning

Note that contrary to usual python slices, both the start and the stop are included
A boolean array of the same length as the axis being sliced, e.g. [True, False, True].
An alignable boolean Series. The index of the key will be aligned before masking.
An alignable Index. The Index of the returned selection will be the input.
A callable function with one argument (the calling Series or DataFrame) and that returns valid output for indexing (one of the above)

See more at Selection by Label.

Raises:

KeyError: If any items are not found.
IndexingError: If an indexed key is passed and its index is unalignable to the frame index.

See also

DataFrame.at: Access a single value for a row/column label pair.
DataFrame.iloc: Access group of rows and columns by integer position(s).
DataFrame.xs: Returns a cross-section (row(s) or column(s)) from the Series/DataFrame.
Series.loc: Access group of values using labels.

Examples

Getting values

>>> df = pd.DataFrame(
...     [[1, 2], [4, 5], [7, 8]],
...     index=["cobra", "viper", "sidewinder"],
...     columns=["max_speed", "shield"],
... )
>>> df
            max_speed  shield
cobra               1       2
viper               4       5
sidewinder          7       8

Single label. Note this returns the row as a Series.

>>> df.loc["viper"]
max_speed    4
shield       5
Name: viper, dtype: int64

List of labels. Note using [[]] returns a DataFrame.

>>> df.loc[["viper", "sidewinder"]]
            max_speed  shield
viper               4       5
sidewinder          7       8

Single label for row and column

>>> df.loc["cobra", "shield"]
2

Slice with labels for row and single label for column. As mentioned above, note that both the start and stop of the slice are included.

>>> df.loc["cobra":"viper", "max_speed"]
cobra    1
viper    4
Name: max_speed, dtype: int64

Boolean list with the same length as the row axis

>>> df.loc[[False, False, True]]
            max_speed  shield
sidewinder          7       8

Alignable boolean Series:

>>> df.loc[
...     pd.Series([False, True, False], index=["viper", "sidewinder", "cobra"])
... ]
                     max_speed  shield
sidewinder          7       8

Index (same behavior as df.reindex)

>>> df.loc[pd.Index(["cobra", "viper"], name="foo")]
       max_speed  shield
foo
cobra          1       2
viper          4       5

Conditional that returns a boolean Series

>>> df.loc[df["shield"] > 6]
            max_speed  shield
sidewinder          7       8

Conditional that returns a boolean Series with column labels specified

>>> df.loc[df["shield"] > 6, ["max_speed"]]
            max_speed
sidewinder          7

Multiple conditional using & that returns a boolean Series

>>> df.loc[(df["max_speed"] > 1) & (df["shield"] < 8)]
            max_speed  shield
viper          4       5

Multiple conditional using | that returns a boolean Series

>>> df.loc[(df["max_speed"] > 4) | (df["shield"] < 5)]
            max_speed  shield
cobra               1       2
sidewinder          7       8

Please ensure that each condition is wrapped in parentheses (). See the user guide for more details and explanations of Boolean indexing.

Note

If you find yourself using 3 or more conditionals in .loc[], consider using advanced indexing.

See below for using .loc[] on MultiIndex DataFrames.

Callable that returns a boolean Series

>>> df.loc[lambda df: df["shield"] == 8]
            max_speed  shield
sidewinder          7       8

Setting values

Set value for all items matching the list of labels

>>> df.loc[["viper", "sidewinder"], ["shield"]] = 50
>>> df
            max_speed  shield
cobra               1       2
viper               4      50
sidewinder          7      50

Set value for an entire row

>>> df.loc["cobra"] = 10
>>> df
            max_speed  shield
cobra              10      10
viper               4      50
sidewinder          7      50

Set value for an entire column

>>> df.loc[:, "max_speed"] = 30
>>> df
            max_speed  shield
cobra              30      10
viper              30      50
sidewinder         30      50

Set value for rows matching callable condition

>>> df.loc[df["shield"] > 35] = 0
>>> df
            max_speed  shield
cobra              30      10
viper               0       0
sidewinder          0       0

Add value matching location

>>> df.loc["viper", "shield"] += 5
>>> df
            max_speed  shield
cobra              30      10
viper               0       5
sidewinder          0       0

Setting using a Series or a DataFrame sets the values matching the index labels, not the index positions.

>>> shuffled_df = df.loc[["viper", "cobra", "sidewinder"]]
>>> df.loc[:] += shuffled_df
>>> df
            max_speed  shield
cobra              60      20
viper               0      10
sidewinder          0       0

Getting values on a DataFrame with an index that has integer labels

Another example using integers for the index

>>> df = pd.DataFrame(
...     [[1, 2], [4, 5], [7, 8]],
...     index=[7, 8, 9],
...     columns=["max_speed", "shield"],
... )
>>> df
   max_speed  shield
7          1       2
8          4       5
9          7       8

Slice with integer labels for rows. As mentioned above, note that both the start and stop of the slice are included.

>>> df.loc[7:9]
   max_speed  shield
7          1       2
8          4       5
9          7       8

Getting values with a MultiIndex

A number of examples using a DataFrame with a MultiIndex

>>> tuples = [
...     ("cobra", "mark i"),
...     ("cobra", "mark ii"),
...     ("sidewinder", "mark i"),
...     ("sidewinder", "mark ii"),
...     ("viper", "mark ii"),
...     ("viper", "mark iii"),
... ]
>>> index = pd.MultiIndex.from_tuples(tuples)
>>> values = [[12, 2], [0, 4], [10, 20], [1, 4], [7, 1], [16, 36]]
>>> df = pd.DataFrame(values, columns=["max_speed", "shield"], index=index)
>>> df
                     max_speed  shield
cobra      mark i           12       2
           mark ii           0       4
sidewinder mark i           10      20
           mark ii           1       4
viper      mark ii           7       1
           mark iii         16      36

Single label. Note this returns a DataFrame with a single index.

>>> df.loc["cobra"]
         max_speed  shield
mark i          12       2
mark ii          0       4

Single index tuple. Note this returns a Series.

>>> df.loc[("cobra", "mark ii")]
max_speed    0
shield       4
Name: (cobra, mark ii), dtype: int64

Single label for row and column. Similar to passing in a tuple, this returns a Series.

>>> df.loc["cobra", "mark i"]
max_speed    12
shield        2
Name: (cobra, mark i), dtype: int64

Single tuple. Note using [[]] returns a DataFrame.

>>> df.loc[[("cobra", "mark ii")]]
               max_speed  shield
cobra mark ii          0       4

Single tuple for the index with a single label for the column

>>> df.loc[("cobra", "mark i"), "shield"]
2

Slice from index tuple to single label

>>> df.loc[("cobra", "mark i") : "viper"]
                     max_speed  shield
cobra      mark i           12       2
           mark ii           0       4
sidewinder mark i           10      20
           mark ii           1       4
viper      mark ii           7       1
           mark iii         16      36

Slice from index tuple to index tuple

>>> df.loc[("cobra", "mark i") : ("viper", "mark ii")]
                    max_speed  shield
cobra      mark i          12       2
           mark ii          0       4
sidewinder mark i          10      20
           mark ii          1       4
viper      mark ii          7       1

Please see the user guide for more details and explanations of advanced indexing.