1. Structures

1.1. Primary Containers

The primary components of the StaticFrame library are the one-dimensional static_frame.Series and the two-dimensional static_frame.Frame and static_frame.FrameGO.

While Frame and Series are immutable, the FrameGO permits a type of grow-only mutation, the addition of columns.

class Series(values: Union[Iterable[Any], numpy.ndarray, Mapping[Hashable, Any], int, float, str, bool], *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, name: Hashable = None, dtype: Union[str, numpy.dtype, type, None] = None, index_constructor: Callable[[...], IndexBase] = None, own_index: bool = False)[source]

A one-dimensional ordered, labelled collection, immutable and of fixed size.

Parameters
  • values – An iterable of values, or a single object, to be aligned with the supplied (or automatically generated) index. Alternatively, a dictionary of index / value pairs can be provided.

  • index – Optional index initializer. If provided in addition to data values, lengths must be compatible.

  • own_index – Flag the passed index as ownable by this Series. Primarily used by internal clients.

>>> import numpy as np
>>> import static_frame as sf

>>> sf.Series.from_dict(dict(Mercury=167, Neptune=-200), dtype=np.int64)
<Series>
<Index>
Mercury  167
Neptune  -200
<<U7>    <int64>

>>> sf.Series((167, -200), index=('Mercury', 'Neptune'), dtype=np.int64)
<Series>
<Index>
Mercury  167
Neptune  -200
<<U7>    <int64>

class Frame(data: Union[Iterable[Iterable[Any]], numpy.ndarray] = <object object>, *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, columns: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, name: Hashable = None, index_constructor: Callable[[...], IndexBase] = None, columns_constructor: Callable[[...], IndexBase] = None, own_data: bool = False, own_index: bool = False, own_columns: bool = False)[source]

A two-dimensional ordered, labelled collection, immutable and of fixed size.

Parameters
  • data – A Frame initializer, given as either a NumPy array, a single value (to be used to fill a shape defined by index and columns), or an iterable suitable to given to the NumPy array constructor.

  • index – Optional index initializer. If provided in addition to data values, lengths must be compatible.

  • columns – Optional column initializer. If provided in addition to data values, lengths must be compatible.

  • own_data – Flag the data values as ownable by this Frame. Primarily used by internal clients.

  • own_index – Flag the passed index as ownable by this Frame. Primarily used by internal clients.

  • own_columns – Flag the passed columns as ownable by this Frame. Primarily used by internal clients.

>>> sf.Frame(((-65, 227.9), (-200, 4495.1)), columns=('temperature', 'distance'), index=('Mars', 'Neptune'))
<Frame>
<Index> temperature distance  <<U11>
<Index>
Mars    -65.0       227.9
Neptune -200.0      4495.1
<<U7>   <float64>   <float64>

>>> sf.Frame.from_dict(dict(diameter=(12756, 142984, 120536), mass=(5.97, 1898, 568)), index=('Earth', 'Jupiter', 'Saturn'), dtypes=dict(diameter=np.int64))
<Frame>
<Index> diameter mass      <<U8>
<Index>
Earth   12756    5.97
Jupiter 142984   1898.0
Saturn  120536   568.0
<<U7>   <int64>  <float64>

class FrameGO(data: Union[Iterable[Iterable[Any]], numpy.ndarray] = <object object>, *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, columns: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, name: Hashable = None, index_constructor: Callable[[...], IndexBase] = None, columns_constructor: Callable[[...], IndexBase] = None, own_data: bool = False, own_index: bool = False, own_columns: bool = False)[source]

A two-dimensional, ordered, labelled collection, immutable with grow-only columns. Initialization arguments are the same as for Frame.

>>> f = sf.FrameGO.from_dict(dict(diameter=(12756, 142984, 120536), mass=(5.97, 1898, 568)), index=('Earth', 'Jupiter', 'Saturn'), dtypes=dict(diameter=np.int64))
>>> f['radius'] = f['diameter'] * 0.5
>>> f
<FrameGO>
<IndexGO> diameter mass      radius    <<U8>
<Index>
Earth     12756    5.97      6378.0
Jupiter   142984   1898.0    71492.0
Saturn    120536   568.0     60268.0
<<U7>     <int64>  <float64> <float64>

1.2. Index Mappings

Index mapping classes are used to map labels to ordinal positions on the Series, Frame, and FrameGO.

class Index(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, loc_is_iloc: bool = False, name: Hashable = None, dtype: Union[str, numpy.dtype, type, None] = None)[source]

A mapping of labels to positions, immutable and of fixed size. Used by default in Series and as index and columns in Frame.

Parameters
  • labels – An iterable of unique, hashable values, or another Index or IndexHierarchy, to be used as the labels of the index.

  • name – A hashable object to name the Index.

  • loc_is_iloc – Optimization when a contiguous integer index is provided as labels. Generally only set by internal clients.

  • dtype – Optional dtype to be used for labels.

>>> sf.Index(('Mercury', 'Mars'), dtype=object)
<Index>
Mercury
Mars
<object>

>>> sf.Index(name[:2].upper() for name in ('Mercury', 'Mars'))
<Index>
ME
MA
<object>

class IndexGO(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, loc_is_iloc: bool = False, name: Hashable = None, dtype: Union[str, numpy.dtype, type, None] = None)[source]

A mapping of labels to positions, immutable with grow-only size. Used as columns in FrameGO.

Parameters
  • labels – An iterable of unique, hashable values, or another Index or IndexHierarchy, to be used as the labels of the index.

  • name – A hashable object to name the Index.

  • loc_is_iloc – Optimization when a contiguous integer index is provided as labels. Generally only set by internal clients.

  • dtype – Optional dtype to be used for labels.

>>> a = sf.IndexGO(('Uranus', 'Neptune'))
>>> a.append('Pluto')
>>> a
<IndexGO>
Uranus
Neptune
Pluto
<<U7>

class IndexYear(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, name: Hashable = None)[source]

A mapping of years (via NumPy datetime64[Y]) to positions, immutable and of fixed size.

Parameters
  • labels – Iterable of hashable values to be used as the index labels. If strings, NumPy datetime conversions will be applied.

  • name – A hashable object to name the Index.

class IndexYearMonth(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, name: Hashable = None)[source]

A mapping of year months (via NumPy datetime64[M]) to positions, immutable and of fixed size.

Parameters
  • labels – Iterable of hashable values to be used as the index labels. If strings, NumPy datetime conversions will be applied.

  • name – A hashable object to name the Index.

class IndexDate(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, name: Hashable = None)[source]

A mapping of dates (via NumPy datetime64[D]) to positions, immutable and of fixed size.

Parameters
  • labels – Iterable of hashable values to be used as the index labels. If strings, NumPy datetime conversions will be applied.

  • name – A hashable object to name the Index.

class IndexSecond(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, name: Hashable = None)[source]

A mapping of time stamps at the resolution of seconds (via NumPy datetime64[s]) to positions, immutable and of fixed size.

Parameters
  • labels – Iterable of hashable values to be used as the index labels. If strings, NumPy datetime conversions will be applied.

  • name – A hashable object to name the Index.

class IndexMillisecond(labels: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]], *, name: Hashable = None)[source]

A mapping of time stamps at the resolutoin of milliseconds (via NumPy datetime64[ms]) to positions, immutable and of fixed size.

Parameters
  • labels – Iterable of hashable values to be used as the index labels. If strings, NumPy datetime conversions will be applied.

  • name – A hashable object to name the Index.

Deviations from Pandas

Index and IndexGO require that all labels are unique. Duplicated labels will raise an error in all cases. This deviates form Pandas, where Index objects permit duplicate labels. This also makes options like the verify_integrity argument to pd.Series.set_index and pd.DataFrame.set_index unnecessary.

class IndexHierarchy(levels: Union[static_frame.core.index_level.IndexLevel, IndexHierarchy], *, name: Hashable = None)[source]

A hierarchy of static_frame.Index objects, defined as strict tree of uniform depth across all branches.

class IndexHierarchyGO(levels: Union[static_frame.core.index_level.IndexLevel, IndexHierarchy], *, name: Hashable = None)[source]

A hierarchy of static_frame.Index objects that permits mutation only in the addition of new hierarchies or labels.

1.3. Utility Objects

The following objects are generally only created by internal clients, and thus are not fully documented here.

class TypeBlocks(*, blocks: List[numpy.ndarray], dtypes: List[numpy.dtype], index: List[Tuple[int, int]], shape: Tuple[int, int])[source]

An ordered collection of type-heterogenous, immutable NumPy arrays, providing an external array-like interface of a single, 2D array. Used by Frame for core, unindexed array management.

A TypeBlocks instance can have a zero size shape (where the length of one axis is zero). Internally, when axis 0 (rows) is of size 0, we store similarly sized arrays. When axis 1 (columns) is of size 0, we do not store arrays, as such arrays do not define a type (as tyupes are defined by columns).