2. Container Import & Creation

Rather than offering a complex default initializer with arguments that are sometimes irrelevant, Series and Frame containers offer numerous specialized constructors.

Both Series and Frame have from_items constructors that consume key/value pairs, such as those returned by dict.items() and similar functions.

2.1. Series

classmethod Series.from_items(pairs: Iterable[Tuple[Hashable, Any]], *, dtype: Union[str, numpy.dtype, type, None] = None, name: Hashable = None, index_constructor: Optional[Callable[[...], static_frame.core.index_base.IndexBase]] = None) → static_frame.core.series.Series[source]

Series construction from an iterator or generator of pairs, where the first pair value is the index and the second is the value.

Parameters
  • pairs – Iterable of pairs of index, value.

  • dtype – dtype or valid dtype specifier.

Returns

static_frame.Series

>>> sf.Series.from_items(zip(('Mercury', 'Jupiter'), (4879, 12756)), dtype=np.int64)
<Series>
<Index>
Mercury  4879
Jupiter  12756
<<U7>    <int64>

classmethod Series.from_dict(mapping: Dict[Hashable, Any], *, dtype: Union[str, numpy.dtype, type, None] = None, name: Hashable = None, index_constructor: Optional[Callable[[...], static_frame.core.index_base.IndexBase]] = None) → static_frame.core.series.Series[source]

Series construction from a dictionary, where the first pair value is the index and the second is the value.

Parameters
  • mapping – a dictionary or similar mapping interface.

  • dtype – dtype or valid dtype specifier.

Returns

static_frame.Series

classmethod Series.from_concat(containers: Iterable[Series], *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], Type[static_frame.core.index_auto.IndexAutoFactory]] = None, name: Hashable = None)[source]

Concatenate multiple Series into a new Series.

Parameters
  • containers – Iterable of Series from which values in the new Series are drawn.

  • index – If None, the resultant index will be the concatenation of all indices (assuming they are unique in combination). If IndexAutoFactory, the resultant index is a auto-incremented integer index. Otherwise, the value is used as a index initializer.

classmethod Series.from_pandas(value, *, own_data: bool = False) → static_frame.core.series.Series[source]

Given a Pandas Series, return a Series.

Parameters
  • value – Pandas Series.

  • own_data – If True, the underlying NumPy data array will be made immutable and used without a copy.

  • own_index – If True, the underlying NumPy index label array will be made immutable and used without a copy.

Returns

static_frame.Series

2.2. Frame

classmethod Frame.from_items(pairs: Iterable[Tuple[Hashable, Iterable[Any]]], *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]] = None, fill_value: object = nan, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False)[source]

Frame constructor from an iterator or generator of pairs, where the first value is the column name and the second value is an iterable of a single column’s values.

Parameters
  • pairs – Iterable of pairs of column name, column values.

  • index – Iterable of values to create an Index.

  • fill_value – If pairs include Series, they will be reindexed with the provided index; reindexing will use this fill value.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

>>> sf.Frame.from_items((('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>

classmethod Frame.from_records(records: Iterable[Any], *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], None] = None, columns: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], None] = None, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Frame constructor from an iterable of rows, where rows are defined as iterables, including tuples, lists, and dictionaries. If each row is a NamedTuple or dictionary, and columns is not provided, column names will be derived from the dictionary keys or NamedTuple fields.

Note that rows defined as Series is not supported; use Frame.from_concat; for creating a Frame from a single dictionary, where keys are column labels and values are columns, use Frame.from_dict.

Parameters
  • records – Iterable of row values, where row values are arrays, tuples, lists, dictionaries, or namedtuples.

  • index – Optionally provide an iterable of index labels, equal in length to the number of records.

  • columns – Optionally provide an iterable of column labels, equal in length to the length of each row.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

>>> index = ('Mercury', 'Venus', 'Earth', 'Mars')
>>> columns = ('diameter', 'gravity', 'temperature')
>>> records = ((4879, 3.7, 167), (12104, 8.9, 464), (12756, 9.8, 15), (6792, 3.7, -65))
>>> sf.Frame.from_records(records, index=index, columns=columns, dtypes=dict(diameter=np.int64, temperature=np.int64))
<Frame>
<Index> diameter gravity   temperature <<U11>
<Index>
Mercury 4879     3.7       167
Venus   12104    8.9       464
Earth   12756    9.8       15
Mars    6792     3.7       -65
<<U7>   <int64>  <float64> <int64>

classmethod Frame.from_records_items(items: Iterator[Tuple[Hashable, Iterable[Any]]], *, columns: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None], None] = None, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Frame constructor from iterable of pairs of index value, row (where row is an iterable).

Parameters
  • items – Iterable of pairs of index label, row values, where row values are arrays, tuples, lists, dictionaries, or namedtuples.

  • columns – Optionally provide an iterable of column labels, equal in length to the length of each row.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

classmethod Frame.from_dict(mapping: Dict[Hashable, Iterable[Any]], *, index: Union[IndexBase, Iterable[Hashable], Iterable[Sequence[Hashable]], Generator[Hashable, None, None]] = None, fill_value: object = nan, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Create a Frame from a dictionary, or any object that has an items() method.

Parameters
  • mapping – a dictionary or similar mapping interface.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

classmethod Frame.from_concat(frames: Iterable[Union[Frame, static_frame.core.series.Series]], *, axis: int = 0, union: bool = True, 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, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Concatenate multiple Frames into a new Frame. If index or columns are provided and appropriately sized, the resulting Frame will use those indices. If the axis along concatenation (index for axis 0, columns for axis 1) is unique after concatenation, it will be preserved.

Parameters
  • frames – Iterable of Frames.

  • axis – Integer specifying 0 to concatenate supplied Frames vertically (aligning on columns), 1 to concatenate horizontally (aligning on rows).

  • union – If True, the union of the aligned indices is used; if False, the intersection is used.

  • index – Optionally specify a new index.

  • columns – Optionally specify new columns.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

>>> f1 = sf.Frame.from_dict(dict(diameter=(12756, 142984), mass=(5.97, 1898)), index=('Earth', 'Jupiter'))
>>> f2 = sf.Frame.from_dict(dict(mass=(0.642, 102), moons=(2, 14)), index=('Mars', 'Neptune'))
>>> sf.Frame.from_concat((f1, f2))
<Frame>
<Index> diameter  mass      moons     <<U8>
<Index>
Earth   12756.0   5.97      nan
Jupiter 142984.0  1898.0    nan
Mars    nan       0.642     2.0
Neptune nan       102.0     14.0
<<U7>   <float64> <float64> <float64>
>>> sf.Frame.from_concat((f1, f2), union=False)
<Frame>
<Index> mass      <<U8>
<Index>
Earth   5.97
Jupiter 1898.0
Mars    0.642
Neptune 102.0
<<U7>   <float64>

classmethod Frame.from_csv(fp: Union[str, TextIO], *, delimiter: str = ',', index_column: Union[int, str, None] = None, skip_header: int = 0, skip_footer: int = 0, header_is_columns: bool = True, quote_char: str = '"', encoding: Optional[str] = None, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Create a Frame from a file path or a file-like object defining a delimited (CSV, TSV) data file.

Parameters
  • fp – A file path or a file-like object.

  • delimiter – The character used to seperate row elements.

  • index_column – Optionally specify a column, by position or name, to become the index.

  • skip_header – Number of leading lines to skip.

  • skip_footer – Numver of trailing lines to skip.

  • header_is_columns – If True (by default), the header, the first line after the skip_header count of lines, is used to create the column labels.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

>>> from io import StringIO
>>> filelike = StringIO('name,mass,temperature\\nVenus,4.87,464\\nNeptune,102,-200')
>>> sf.Frame.from_csv(filelike, index_column='name', dtypes=dict(temperature=np.int64))
<Frame>
<Index> mass      temperature <<U11>
<Index>
Venus   4.87      464
Neptune 102.0     -200
<<U7>   <float64> <int64>

classmethod Frame.from_tsv(fp, **kwargs) → static_frame.core.frame.Frame[source]

Specialized version of Frame.from_csv() for TSV files.

Returns

static_frame.Frame

classmethod Frame.from_json(json_data: str, *, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Frame constructor from an in-memory JSON document.

Parameters
  • json_data – a string of JSON, encoding a table as an array of JSON objects.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

classmethod Frame.from_json_url(url: str, *, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Frame constructor from a JSON documenst provided via a URL.

Parameters
  • url – URL to the JSON resource.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

classmethod Frame.from_sql(query: str, connection: sqlite3.Connection) → static_frame.core.frame.Frame[source]

Frame constructor from an SQL query and a database connection object.

Parameters
  • query – A query string.

  • connection – A DBAPI2 (PEP 249) Connection object, such as those returned from SQLite (via the sqlite3 module) or PyODBC.

classmethod Frame.from_structured_array(array: numpy.ndarray, *, index_column: Union[int, str, None] = None, dtypes: Union[Iterable[Union[str, numpy.dtype, type, None]], Dict[Hashable, Union[str, numpy.dtype, type, None]], None] = None, name: Hashable = None, consolidate_blocks: bool = False) → static_frame.core.frame.Frame[source]

Convert a NumPy structed array into a Frame.

Parameters
  • array – Structured NumPy array.

  • index_column – Optionally provide the name or position offset of the column to use as the index.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name. If a dtype is given as None, NumPy’s default type determination will be used.

  • name – A hashable object to name the Frame.

  • consolidate_blocks – Optionally consolidate adjacent same-typed columns into contiguous arrays.

Returns

static_frame.Frame

>>> a = np.array([('Venus', 4.87, 464), ('Neptune', 102, -200)], dtype=[('name', object), ('mass', 'f4'), ('temperature', 'i4')])
>>> sf.Frame.from_structured_array(a, index_column='name')
<Frame>
<Index>  mass              temperature <<U11>
<Index>
Venus    4.869999885559082 464
Neptune  102.0             -200
<object> <float32>         <int32>


classmethod Frame.from_pandas(value, *, own_data: bool = False) → static_frame.core.frame.Frame[source]

Given a Pandas DataFrame, return a Frame.

Parameters
  • value – Pandas DataFrame.

  • own_data – If True, the underlying NumPy data array will be made immutable and used without a copy.

Returns

static_frame.Frame

2.3. Index

While indices are often specified with their data at container creation, in some cases explicitly creating indices in advance of the data is practical.

classmethod Index.from_labels(labels: Iterable[Sequence[Hashable]]) → static_frame.core.index.Index[source]

Construct an Index from an iterable of labels, where each label is a hashable. Provided for a compatible interface to IndexHierarchy.

classmethod IndexHierarchy.from_product(*levels, name: Hashable = None) → IH[source]

Given groups of iterables, return an IndexHierarchy made of the product of a values in those groups, where the first group is the top-most hierarchy.

Returns

static_frame.IndexHierarchy

classmethod IndexHierarchy.from_tree(tree, *, name: Hashable = None) → IH[source]

Convert into a IndexHierarchy a dictionary defining keys to either iterables or nested dictionaries of the same.

Returns

static_frame.IndexHierarchy

classmethod IndexHierarchy.from_labels(labels: Iterable[Sequence[Hashable]], *, name: Hashable = None, index_constructors: Optional[Sequence[Callable[[...], IndexBase]]] = None) → IH[source]

Construct an IndexHierarhcy from an iterable of labels, where each label is tuple defining the component labels for all hierarchies.

Parameters

labels – an iterator or generator of tuples.

Returns

static_frame.IndexHierarchy