Class MultiIndex (2.27.0) 

MultiIndex(data=None, dtype=None, *, name=None, session=None)

A multi-level, or hierarchical, index object for pandas objects.

Properties

T

Return the transpose, which is by definition self.

Examples:

>>> s = bpd.Series(['Ant', 'Bear', 'Cow'])
>>> s
0     Ant
1    Bear
2     Cow
dtype: string

>>> s.T
0     Ant
1    Bear
2     Cow
dtype: string

For Index:

>>> idx = bpd.Index([1, 2, 3])
>>> idx.T
Index([1, 2, 3], dtype='Int64')
Returns
Type Description
bigframes.pandas.Index Index

dtype

Return the dtype object of the underlying data.

Examples:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')

>>> idx.dtype
Int64Dtype()

dtypes

Return the dtypes as a Series for the underlying MultiIndex.

Returns
Type Description
Pandas.Series Pandas.Series of the MultiIndex dtypes.

empty

Returns True if the Index is empty, otherwise returns False.

has_duplicates

Check if the Index has duplicate values.

Examples:

>>> idx = bpd.Index([1, 5, 7, 7])
>>> bool(idx.has_duplicates)
True

>>> idx = bpd.Index([1, 5, 7])
>>> bool(idx.has_duplicates)
False
Returns
Type Description
bool Whether or not the Index has duplicate values.

is_monotonic_decreasing

Return a boolean if the values are equal or decreasing.

Examples:

>>> bool(bpd.Index([3, 2, 1]).is_monotonic_decreasing)
True

>>> bool(bpd.Index([3, 2, 2]).is_monotonic_decreasing)
True

>>> bool(bpd.Index([3, 1, 2]).is_monotonic_decreasing)
False
Returns
Type Description
bool True, if the values monotonically decreasing, otherwise False.

is_monotonic_increasing

Return a boolean if the values are equal or increasing.

Examples:

>>> bool(bpd.Index([1, 2, 3]).is_monotonic_increasing)
True

>>> bool(bpd.Index([1, 2, 2]).is_monotonic_increasing)
True

>>> bool(bpd.Index([1, 3, 2]).is_monotonic_increasing)
False
Returns
Type Description
bool True, if the values monotonically increasing, otherwise False.

is_unique

Return if the index has unique values.

Examples:

>>> idx = bpd.Index([1, 5, 7, 7])
>>> idx.is_unique
False

>>> idx = bpd.Index([1, 5, 7])
>>> idx.is_unique
True
Returns
Type Description
bool True if the index has unique values, otherwise False.

name

Returns Index name.

Examples:

>>> idx = bpd.Index([1, 2, 3], name='x')
>>> idx
Index([1, 2, 3], dtype='Int64', name='x')
>>> idx.name
'x'
Returns
Type Description
blocks.Label Index or MultiIndex name

names

Returns the names of the Index.

Returns
Type Description
Sequence[blocks.Label] A Sequence of Index or MultiIndex name

ndim

Number of dimensions of the underlying data, by definition 1.

Examples:

>>> s = bpd.Series(['Ant', 'Bear', 'Cow'])
>>> s
0     Ant
1    Bear
2     Cow
dtype: string

>>> s.ndim
1

For Index:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')

>>> idx.ndim
1
Returns
Type Description
int Number or dimensions.

nlevels

Integer number of levels in this MultiIndex

Examples:

>>> mi = bpd.MultiIndex.from_arrays([['a'], ['b'], ['c']])
>>> mi
MultiIndex([('a', 'b', 'c')],
           )
>>> mi.nlevels
3
Returns
Type Description
int Number of levels.

query_job

BigQuery job metadata for the most recent query.

shape

Return a tuple of the shape of the underlying data.

Examples:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')

>>> idx.shape
(3,)
Returns
Type Description
Tuple[int] A Tuple of integers representing the shape.

size

Return the number of elements in the underlying data.

Examples:

For Series:

>>> s = bpd.Series(['Ant', 'Bear', 'Cow'])
>>> s
0     Ant
1    Bear
2     Cow
dtype: string

For Index:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')
Returns
Type Description
int Number of elements

str

Vectorized string functions for Series and Index.

NAs stay NA unless handled otherwise by a particular method. Patterned after Python’s string methods, with some inspiration from R’s stringr package.

Examples:

>>> import bigframes.pandas as bpd
>>> s = bpd.Series(["A_Str_Series"])
>>> s
0    A_Str_Series
dtype: string

>>> s.str.lower()
0    a_str_series
dtype: string

>>> s.str.replace("_", "")
0    AStrSeries
dtype: string
Returns
Type Description
bigframes.operations.strings.StringMethods An accessor containing string methods.

values

Return an array representing the data in the Index.

Examples:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')

>>> idx.values
array([1, 2, 3])
Returns
Type Description
array Numpy.ndarray or ExtensionArray

Methods

__setitem__

__setitem__(key, value) -> None

Index objects are immutable. Use Index constructor to create modified Index.

all

all() -> bool

Return whether all elements are Truthy.

Examples:

True, because nonzero integers are considered True.

>>> bool(bpd.Index([1, 2, 3]).all())
True

False, because 0 is considered False.

>>> bool(bpd.Index([0, 1, 2]).all())
False
Exceptions
Type Description
TypeError MultiIndex with more than 1 level does not support all.
Returns
Type Description
bool A single element array-like may be converted to bool.

any

any() -> bool

Return whether any element is Truthy.

Examples:

>>> index = bpd.Index([0, 1, 2])
>>> bool(index.any())
True

>>> index = bpd.Index([0, 0, 0])
>>> bool(index.any())
False
Exceptions
Type Description
TypeError MultiIndex with more than 1 level does not support any.
Returns
Type Description
bool A single element array-like may be converted to bool.

argmax

argmax() -> int

Return int position of the largest value in the Series.

If the maximum is achieved in multiple locations, the first row position is returned.

Examples:

Consider dataset containing cereal calories

>>> s = bpd.Series({'Corn Flakes': 100.0, 'Almond Delight': 110.0,
...                'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0})
>>> s
Corn Flakes              100.0
Almond Delight           110.0
Cinnamon Toast Crunch    120.0
Cocoa Puff               110.0
dtype: Float64

>>> int(s.argmax())
2

>>> int(s.argmin())
0

The maximum cereal calories is the third element and the minimum cereal calories is the first element, since series is zero-indexed.

Returns
Type Description
int Row position of the maximum value.

argmin

argmin() -> int

Return int position of the smallest value in the series.

If the minimum is achieved in multiple locations, the first row position is returned.

Examples:

Consider dataset containing cereal calories

>>> s = bpd.Series({'Corn Flakes': 100.0, 'Almond Delight': 110.0,
...                'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0})
>>> s
Corn Flakes              100.0
Almond Delight           110.0
Cinnamon Toast Crunch    120.0
Cocoa Puff               110.0
dtype: Float64

>>> int(s.argmax())
2

>>> int(s.argmin())
0

The maximum cereal calories is the third element and the minimum cereal calories is the first element, since series is zero-indexed.

Returns
Type Description
int Row position of the minimum value.

astype

astype(
    dtype, *, errors: typing.Literal["raise", "null"] = "raise"
) -> bigframes.core.indexes.base.Index

Create an Index with values cast to dtypes.

The class of a new Index is determined by dtype. When conversion is impossible, a TypeError exception is raised.

Examples:

>>> idx = bpd.Index([1, 2, 3])
>>> idx
Index([1, 2, 3], dtype='Int64')
Parameters
Name Description
dtype str, data type, or pandas.ExtensionDtype

A dtype supported by BigQuery DataFrame include 'boolean', 'Float64', 'Int64', 'int64[pyarrow]', 'string', 'string[pyarrow]', 'timestamp[us, tz=UTC][pyarrow]', 'timestamp[us][pyarrow]', 'date32[day][pyarrow]', 'time64[us][pyarrow]'. A pandas.ExtensionDtype include pandas.BooleanDtype(), pandas.Float64Dtype(), pandas.Int64Dtype(), pandas.StringDtype(storage="pyarrow"), pd.ArrowDtype(pa.date32()), pd.ArrowDtype(pa.time64("us")), pd.ArrowDtype(pa.timestamp("us")), pd.ArrowDtype(pa.timestamp("us", tz="UTC")).
errors {'raise', 'null'}, default 'raise'

Control raising of exceptions on invalid data for provided dtype. If 'raise', allow exceptions to be raised if any value fails cast If 'null', will assign null value if value fails cast
Exceptions
Type Description
ValueError If errors is not one of raise.
TypeError MultiIndex with more than 1 level does not support astype.
Returns
Type Description
bigframes.pandas.Index Index with values cast to specified dtype.

copy

copy(name: typing.Optional[typing.Hashable] = None)

Make a copy of this object.

Name is set on the new object.

Examples:

>>> idx = bpd.Index(['a', 'b', 'c'])
>>> new_idx = idx.copy()
>>> idx is new_idx
False
Parameter
Name Description
name Label, optional

Set name for new object.
Returns
Type Description
bigframes.pandas.Index Index reference to new object, which is a copy of this object.

drop

drop(labels: typing.Any) -> bigframes.core.indexes.base.Index

Make new Index with passed list of labels deleted.

Examples:

>>> idx = bpd.Index(['a', 'b', 'c'])
>>> idx.drop(['a'])
Index(['b', 'c'], dtype='string')
Returns
Type Description
bigframes.pandas.Index Will be same type as self.

drop_duplicates

drop_duplicates(*, keep: __builtins__.str = "first") -> Index

Return Index with duplicate values removed.

Examples:

>>> import bigframes.pandas as bpd

Generate an pandas.Index with duplicate values.

>>> idx = bpd.Index(['lama', 'cow', 'lama', 'beetle', 'lama', 'hippo'])

The keep parameter controls which duplicate values are removed. The value first keeps the first occurrence for each set of duplicated entries. The default value of keep is first.

>>> idx.drop_duplicates(keep='first')
Index(['lama', 'cow', 'beetle', 'hippo'], dtype='string')

The value last keeps the last occurrence for each set of duplicated entries.

>>> idx.drop_duplicates(keep='last')
Index(['cow', 'beetle', 'lama', 'hippo'], dtype='string')

The value False discards all sets of duplicated entries.

>>> idx.drop_duplicates(keep=False)
Index(['cow', 'beetle', 'hippo'], dtype='string')
Parameter
Name Description
keep {'first', 'last', False}, default 'first'

One of: 'first' : Drop duplicates except for the first occurrence. 'last' : Drop duplicates except for the last occurrence. False : Drop all duplicates.

dropna

dropna(
    how: typing.Literal["all", "any"] = "any",
) -> bigframes.core.indexes.base.Index

Return Index without NA/NaN values.

Examples:

>>> idx = bpd.Index([1, np.nan, 3])
>>> idx.dropna()
Index([1.0, 3.0], dtype='Float64')
Parameter
Name Description
how {'any', 'all'}, default 'any'

If the Index is a MultiIndex, drop the value when any or all levels are NaN.
Exceptions
Type Description
ValueError If how is not any or all

fillna

fillna(value=None) -> bigframes.core.indexes.base.Index

Fill NA (NULL in BigQuery) values using the specified method.

Note that empty strings '', numpy.inf, and numpy.nan are not considered NA values. This NA/NULL logic differs from numpy, but it is the same as BigQuery and the pandas.ArrowDtype.

Examples:

>>> idx = bpd.Index(
...     pa.array([None, np.nan, 3, None], type=pa.float64()),
...     dtype=pd.ArrowDtype(pa.float64()),
... )
>>> idx
Index([<NA>, nan, 3.0, <NA>], dtype='Float64')
>>> idx.fillna(0)
Index([0.0, nan, 3.0, 0.0], dtype='Float64')
Parameter
Name Description
value scalar

Scalar value to use to fill holes (e.g. 0). This value cannot be a list-likes.
Exceptions
Type Description
TypeError MultiIndex with more than 1 level does not support fillna.

from_arrays

from_arrays(
    arrays,
    sortorder: int | None = None,
    names=None,
    *,
    session: Optional[bigframes.session.Session] = None
) -> MultiIndex

Convert arrays to MultiIndex.

Examples:

>>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
>>> bpd.MultiIndex.from_arrays(arrays, names=('number', 'color'))
MultiIndex([(1,  'red'),
            (1, 'blue'),
            (2,  'red'),
            (2, 'blue')],
        names=['number', 'color'])
Parameters
Name Description
arrays list / sequence of array-likes

Each array-like gives one level's value for each data point. len(arrays) is the number of levels.
sortorder int or None

Level of sortedness (must be lexicographically sorted by that level).
names list / sequence of str, optional

Names for the levels in the index.

from_frame

from_frame(
    frame: typing.Union[bigframes.series.Series, bigframes.dataframe.DataFrame],
) -> bigframes.core.indexes.base.Index

Make a MultiIndex from a DataFrame.

Examples:

>>> df = bpd.DataFrame([['HI', 'Temp'], ['HI', 'Precip'],
...                     ['NJ', 'Temp'], ['NJ', 'Precip']],
...                    columns=['a', 'b'])
>>> df
    a       b
0  HI    Temp
1  HI  Precip
2  NJ    Temp
3  NJ  Precip
<BLANKLINE>
[4 rows x 2 columns]

>>> bpd.MultiIndex.from_frame(df)
Index([0, 1, 2, 3], dtype='Int64')
Parameter
Name Description
frame Union[bigframes.pandas.Series, bigframes.pandas.DataFrame]

bigframes.pandas.Series or bigframes.pandas.DataFrame to convert to bigframes.pandas.Index.
Exceptions
Type Description
bigframes.exceptions.NullIndexError If Index is Null.
Returns
Type Description
bigframes.pandas.Index The Index representation of the given Series or DataFrame.

from_tuples

from_tuples(
    tuples: Iterable[tuple[Hashable, ...]],
    sortorder: int | None = None,
    names: Sequence[Hashable] | Hashable | None = None,
    *,
    session: Optional[bigframes.session.Session] = None
) -> MultiIndex

Convert list of tuples to MultiIndex.

Examples:

>>> tuples = [(1, 'red'), (1, 'blue'),
...           (2, 'red'), (2, 'blue')]
>>> bpd.MultiIndex.from_tuples(tuples, names=('number', 'color'))
MultiIndex([(1,  'red'),
            (1, 'blue'),
            (2,  'red'),
            (2, 'blue')],
        names=['number', 'color'])
Parameters
Name Description
tuples list / sequence of tuple-likes

Each tuple is the index of one row/column.
sortorder int or None

Level of sortedness (must be lexicographically sorted by that level).
names list / sequence of str, optional

Names for the levels in the index.

get_level_values

get_level_values(level) -> bigframes.core.indexes.base.Index

Return an Index of values for requested level.

This is primarily useful to get an individual level of values from a MultiIndex, but is provided on Index as well for compatibility.

Examples:

>>> idx = bpd.Index(list('abc'))
>>> idx
Index(['a', 'b', 'c'], dtype='string')

Get level values by supplying level as integer:

>>> idx.get_level_values(0)
Index(['a', 'b', 'c'], dtype='string')
Parameter
Name Description
level int or str

It is either the integer position or the name of the level.
Returns
Type Description
bigframes.pandas.Index Calling object, as there is only one level in the Index.

get_loc

get_loc(key) -> typing.Union[int, slice, bigframes.series.Series]

Get integer location, slice or boolean mask for requested label.

Exceptions
Type Description
NotImplementedError If the index has more than one level.
KeyError If the key is not found in the index.

isin

isin(values) -> bigframes.core.indexes.base.Index

Return a boolean array where the index values are in values.

Compute boolean array to check whether each index value is found in the passed set of values. The length of the returned boolean array matches the length of the index.

Examples:

>>> idx = bpd.Index([1,2,3])
>>> idx
Index([1, 2, 3], dtype='Int64')

Check whether each index value in a list of values.

>>> idx.isin([1, 4])
Index([True, False, False], dtype='boolean')

>>> midx = bpd.MultiIndex.from_arrays([[1,2,3],
...                                   ['red', 'blue', 'green']],
...                                   names=('number', 'color'))
>>> midx
MultiIndex([(1,   'red'),
            (2,  'blue'),
            (3, 'green')],
           names=['number', 'color'])
Parameter
Name Description
values set or list-like

Sought values.
Exceptions
Type Description
TypeError If object passed to isin() is not a list-like
Returns
Type Description
bigframes.pandas.Series Series of boolean values.

item

item()

Return the first element of the underlying data as a Python scalar.

Examples:

>>> s = bpd.Series([1], index=['a'])
>>> s.index.item()
'a'
Exceptions
Type Description
ValueError If the data is not length = 1.
Returns
Type Description
scalar The first element of Index.

max

max() -> typing.Any

Return the maximum value of the Index.

Examples:

>>> idx = bpd.Index([3, 2, 1])
>>> int(idx.max())
3

>>> idx = bpd.Index(['c', 'b', 'a'])
>>> idx.max()
'c'
Returns
Type Description
scalar Maximum value.

min

min() -> typing.Any

Return the minimum value of the Index.

Examples:

>>> idx = bpd.Index([3, 2, 1])
>>> int(idx.min())
1

>>> idx = bpd.Index(['c', 'b', 'a'])
>>> idx.min()
'a'
Returns
Type Description
scalar Minimum value.

nunique

nunique() -> int

Return number of unique elements in the object.

Excludes NA values by default.

Examples:

>>> s = bpd.Series([1, 3, 5, 7, 7])
>>> s
0    1
1    3
2    5
3    7
4    7
dtype: Int64

>>> int(s.nunique())
4
Returns
Type Description
int Number of unique elements

rename

rename(
    name: typing.Union[typing.Hashable, typing.Sequence[typing.Hashable]],
    *,
    inplace: bool = False
) -> typing.Optional[bigframes.core.indexes.base.Index]

Alter Index or MultiIndex name.

Able to set new names without level. Defaults to returning new index. Length of names must match number of levels in MultiIndex.

Examples:

>>> idx = bpd.Index(['A', 'C', 'A', 'B'], name='score')
>>> idx.rename('grade')
Index(['A', 'C', 'A', 'B'], dtype='string', name='grade')
Parameters
Name Description
name label or list of labels

Name(s) to set.
inplace bool

Default False. Modifies the object directly, instead of creating a new Index or MultiIndex.
Exceptions
Type Description
ValueError If name is not the same length as levels.
Returns
Type Description
bigframes.pandas.Index None The same type as the caller or None if inplace=True.

sort_values

sort_values(
    *,
    inplace: bool = False,
    ascending: bool = True,
    na_position: __builtins__.str = "last"
) -> Index

Return a sorted copy of the index.

Return a sorted copy of the index, and optionally return the indices that sorted the index itself.

Examples:

>>> idx = bpd.Index([10, 100, 1, 1000])
>>> idx
Index([10, 100, 1, 1000], dtype='Int64')

Sort values in ascending order (default behavior).

>>> idx.sort_values()
Index([1, 10, 100, 1000], dtype='Int64')
Parameters
Name Description
ascending bool, default True

Should the index values be sorted in an ascending order.
na_position {'first' or 'last'}, default 'last'

Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at the end.
Exceptions
Type Description
ValueError If no_position is not one of first or last.
Returns
Type Description
pandas.Index Sorted copy of the index.

to_list

to_list(*, allow_large_results: typing.Optional[bool] = None) -> list

API documentation for to_list method.

to_numpy

to_numpy(dtype=None, *, allow_large_results=None, **kwargs) -> numpy.ndarray

A NumPy ndarray representing the values in this Series or Index.

Parameter
Name Description
allow_large_results bool, default None

If not None, overrides the global setting to allow or disallow large query results over the default size limit of 10 GB.

to_pandas

to_pandas(
    *, allow_large_results: typing.Optional[bool] = None, dry_run: bool = False
) -> pandas.core.indexes.base.Index | pandas.core.series.Series

Gets the Index as a pandas Index.

Parameters
Name Description
allow_large_results bool, default None

If not None, overrides the global setting to allow or disallow large query results over the default size limit of 10 GB.
dry_run bool, default False

If this argument is true, this method will not process the data. Instead, it returns a Pandas series containing dtype and the amount of bytes to be processed.
Returns
Type Description
pandas.Index pandas.Series A pandas Index with all of the labels from this Index. If dry run is set to True, returns a Series containing dry run statistics.

to_series

to_series(
    index: typing.Optional[bigframes.core.indexes.base.Index] = None,
    name: typing.Optional[typing.Hashable] = None,
) -> bigframes.series.Series

Create a Series with both index and values equal to the index keys.

Useful with map for returning an indexer based on an index.

Examples:

>>> idx = bpd.Index(['Ant', 'Bear', 'Cow'], name='animal')

By default, the original index and original name is reused.

>>> idx.to_series()
animal
Ant      Ant
Bear    Bear
Cow      Cow
Name: animal, dtype: string

To enforce a new index, specify new labels to index:

>>> idx.to_series(index=[0, 1, 2])
0     Ant
1    Bear
2     Cow
Name: animal, dtype: string

To override the name of the resulting column, specify name:

>>> idx.to_series(name='zoo')
animal
Ant      Ant
Bear    Bear
Cow      Cow
Name: zoo, dtype: string
Parameters
Name Description
index Index, optional

Index of resulting Series. If None, defaults to original index.
name str, optional

Name of resulting Series. If None, defaults to name of original index.
Returns
Type Description
bigframes.pandas.Series The dtype will be based on the type of the Index values.

transpose

transpose() -> bigframes.core.indexes.base.Index

Return the transpose, which is by definition self.

unique

unique(
    level: typing.Optional[typing.Union[typing.Hashable, int]] = None,
) -> bigframes.core.indexes.base.Index

Returns unique values in the index.

Examples:

>>> idx = bpd.Index([1, 1, 2, 3, 3])
>>> idx.unique()
Index([1, 2, 3], dtype='Int64')
Parameter
Name Description
level int or hashable, optional

Only return values from specified level (for MultiIndex). If int, gets the level by integer position, else by level name.

value_counts

value_counts(
    normalize: bool = False,
    sort: bool = True,
    ascending: bool = False,
    *,
    dropna: bool = True
)

Return a Series containing counts of unique values.

The resulting object will be in descending order so that the first element is the most frequently-occurring element. Excludes NA values by default.

Examples:

>>> index = bpd.Index([3, 1, 2, 3, 4, np.nan])
>>> index.value_counts()
3.0    2
1.0    1
2.0    1
4.0    1
Name: count, dtype: Int64

With normalize set to True, returns the relative frequency by dividing all values by the sum of values.

>>> s = bpd.Series([3, 1, 2, 3, 4, np.nan])
>>> s.value_counts(normalize=True)
3.0    0.4
1.0    0.2
2.0    0.2
4.0    0.2
Name: proportion, dtype: Float64

dropna

With dropna set to False we can also see NaN index values.

>>> s.value_counts(dropna=False)
3.0     2
1.0     1
2.0     1
4.0     1
<NA>    1
Name: count, dtype: Int64
Parameters
Name Description
normalize bool, default False

If True, then the object returned will contain the relative frequencies of the unique values.
sort bool, default True

Sort by frequencies.
ascending bool, default False

Sort in ascending order.
dropna bool, default True

Don't include counts of NaN.