Detail: Frame: Constructor

Overview: Frame: Constructor

Frame.__init__(data=<object object>, *, index=None, columns=None, name=<object object>, index_constructor=None, columns_constructor=None, own_data=False, own_index=False, own_columns=False)[source]

Initializer.

Parameters:
  • data – Default Frame initialization requires typed data such as a NumPy array. All other initialization should use specialized constructors.

  • 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.

  • index_constructor

  • columns_constructor

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

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

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

>>> sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
classmethod Frame.from_arrow(value, *, index_depth=0, index_name_depth_level=None, index_constructors=None, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, dtypes=None, name=None, consolidate_blocks=False)[source]

Realize a Frame from an Arrow Table.

Parameters:
  • value – A pyarrow.Table instance.

  • index_depth – integer specification of how many columns to use in forming the index. A value of 0 will select none; a value greater than 1 will create an IndexHierarchy.

  • columns_depth – integer specification of how many rows to use in forming the columns. A value of 0 will select none; a value greater than 1 will create an IndexHierarchy.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> aw = f1.to_arrow()
>>> aw
pyarrow.Table
__index0__: string
a: int64
b: int64
----
__index0__: [["p","q","r"]]
a: [[0,2,4]]
b: [[1,3,5]]
>>> sf.Frame.from_arrow(aw, index_depth=1)
<Frame>
<Index>  a       b       <<U1>
<Index>
p        0       1
q        2       3
r        4       5
<object> <int64> <int64>
classmethod Frame.from_clipboard(*, delimiter='\t', index_depth=0, index_column_first=0, index_name_depth_level=None, index_constructors=None, index_continuation_token=<object object>, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, columns_continuation_token=<object object>, columns_select=None, skip_header=0, skip_footer=0, skip_initial_space=False, quoting=0, quote_char='"', quote_double=True, escape_char=None, thousands_char='', decimal_char='.', encoding=None, dtypes=None, name=None, consolidate_blocks=False, store_filter=None)[source]

Create a Frame from the contents of the clipboard (assuming a table is stored as delimited file).

Returns:

static_frame.Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f1.to_clipboard()
>>> sf.Frame.from_clipboard(index_depth=1)
<Frame>
<Index> a       b       <<U1>
<Index>
p       0       1
q       2       3
r       4       5
<<U1>   <int64> <int64>
classmethod Frame.from_concat(frames, *, axis=0, union=True, index=None, columns=None, index_constructor=None, columns_constructor=None, name=None, fill_value=nan, consolidate_blocks=False)[source]

Concatenate multiple Frame or Series 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; otherwise, a new index or an IndexAutoFactory must be supplied.

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.

  • index_constructor – Optionally apply a constructor to the derived or passed labels.

  • columns_constructor – Optionally apply a constructor to the derived or passed labels.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f2 = sf.Frame((np.arange(6).reshape(3,2) % 2).astype(bool), index=('p', 'q', 'r'), columns=('c', 'd'), name='y')
>>> f2
<Frame: y>
<Index>    c      d      <<U1>
<Index>
p          False  True
q          False  True
r          False  True
<<U1>      <bool> <bool>
>>> sf.Frame.from_concat((f1, f2), axis=1)
<Frame>
<Index> a       b       c      d      <<U1>
<Index>
p       0       1       False  True
q       2       3       False  True
r       4       5       False  True
<<U1>   <int64> <int64> <bool> <bool>
>>> sf.Frame.from_concat((f1, f2.relabel(columns=('a', 'b'))), axis=0, index=sf.IndexAutoFactory)
<Frame>
<Index> a        b        <<U1>
<Index>
0       0        1
1       2        3
2       4        5
3       False    True
4       False    True
5       False    True
<int64> <object> <object>
classmethod Frame.from_concat_items(items, *, axis=0, union=True, name=None, fill_value=nan, index_constructor=None, columns_constructor=None, consolidate_blocks=False)[source]

Produce a Frame with a hierarchical index from an iterable of pairs of labels, Frame. The IndexHierarchy is formed from the provided labels and the Index if each Frame.

Parameters:
  • items – Iterable of pairs of label, Frame

  • axis

  • union

  • name

  • fill_value

  • index_constructor

  • columns_constructor

  • consolidate_blocks

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f2 = sf.Frame((np.arange(6).reshape(3,2) % 2).astype(bool), index=('p', 'q', 'r'), columns=('c', 'd'), name='y')
>>> f2
<Frame: y>
<Index>    c      d      <<U1>
<Index>
p          False  True
q          False  True
r          False  True
<<U1>      <bool> <bool>
>>> sf.Frame.from_concat_items(((f1.name, f1), (f2.name, f2)), axis=1)
<Frame>
<IndexHierarchy> x       x       y      y      <<U1>
                 a       b       c      d      <<U1>
<Index>
p                0       1       False  True
q                2       3       False  True
r                4       5       False  True
<<U1>            <int64> <int64> <bool> <bool>
>>> sf.Frame.from_concat_items(((f1.name, f1), (f2.name, f2.relabel(columns=('a', 'b')))), axis=0)
<Frame>
<Index>                a        b        <<U1>
<IndexHierarchy>
x                p     0        1
x                q     2        3
x                r     4        5
y                p     False    True
y                q     False    True
y                r     False    True
<<U1>            <<U1> <object> <object>
classmethod Frame.from_csv(fp, *, index_depth=0, index_column_first=0, index_name_depth_level=None, index_constructors=None, index_continuation_token=<object object>, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, columns_continuation_token=<object object>, columns_select=None, skip_header=0, skip_footer=0, skip_initial_space=False, quoting=0, quote_char='"', quote_double=True, escape_char=None, thousands_char='', decimal_char='.', encoding=None, dtypes=None, name=None, consolidate_blocks=False, store_filter=None)[source]

Specialized version of Frame.from_delimited for CSV files.

Returns:

Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f1.to_csv('/tmp/f.csv')
>>> from pathlib import Path
>>> Path('/tmp/f.csv').read_text()
__index0__,a,b
p,0,1
q,2,3
r,4,5

>>> sf.Frame.from_csv('/tmp/f.csv', index_depth=1)
<Frame>
<Index> a       b       <<U1>
<Index>
p       0       1
q       2       3
r       4       5
<<U1>   <int64> <int64>
classmethod Frame.from_delimited(fp, *, delimiter, index_depth=0, index_column_first=0, index_name_depth_level=None, index_constructors=None, index_continuation_token=<object object>, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, columns_continuation_token=<object object>, columns_select=None, skip_header=0, skip_footer=0, skip_initial_space=False, quoting=0, quote_char='"', quote_double=True, escape_char=None, thousands_char='', decimal_char='.', encoding=None, dtypes=None, name=None, consolidate_blocks=False, store_filter=None)[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_depth – Specify the number of columns used to create the index labels; a value greater than 1 will attempt to create a hierarchical index.

  • index_column_first – Optionally specify a column, by position in the realized columns, to become the start of the index if index_depth is greater than 0 and columns_depth is 0.

  • index_name_depth_level – If columns_depth is greater than 0, interpret values over index as the index name.

  • index_constructors

  • index_continuation_token

  • columns_depth – Specify the number of rows after the skip_header used to create the column labels. A value of 0 will be no header; a value greater than 1 will attempt to create a hierarchical index.

  • columns_name_depth_level – If index_depth is greater than 0, interpret values over index as the columns name.

  • columns_constructors

  • columns_continuation_token

  • columns_select – an iterable of columns to select by label or position; can only be used if index_depth is 0.

  • skip_header – Number of leading lines to skip.

  • skip_footer – Number of trailing lines to skip.

  • store_filter – A StoreFilter instance, defining translation between unrepresentable strings and types. By default it is disabled, and only empty fields or “NAN” are intepreted as NaN. To force usage, set the type of the column to string.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f1.to_delimited('/tmp/f.psv', delimiter='|')
>>> from pathlib import Path
>>> Path('/tmp/f.psv').read_text()
__index0__|a|b
p|0|1
q|2|3
r|4|5

>>> sf.Frame.from_delimited('/tmp/f.psv', delimiter='|', index_depth=1)
<Frame>
<Index> a       b       <<U1>
<Index>
p       0       1
q       2       3
r       4       5
<<U1>   <int64> <int64>
classmethod Frame.from_dict(mapping, *, index=None, fill_value=nan, dtypes=None, name=None, index_constructor=None, columns_constructor=None, consolidate_blocks=False)[source]

Create a Frame from a dictionary (or any object that has an items() method) where keys are column labels and values are columns values (either sequence types or Series).

Parameters:
  • mapping – a dictionary or similar mapping interface.

  • index

  • fill_value

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

  • index_constructor

  • columns_constructor

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

>>> sf.Frame.from_dict(mapping=dict(a=(10, 2, 8, 3), b=('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), dtypes=dict(b=np.datetime64), name='x')
<Frame: x>
<Index>    a       b               <<U1>
<Index>
0          10      1517-01-01
1          2       1517-04-01
2          8       1517-12-31
3          3       1517-06-30
<int64>    <int64> <datetime64[D]>
classmethod Frame.from_dict_fields(fields, *, columns=None, dtypes=None, name=None, fill_value=nan, consolidate_blocks=False, index_constructor=None, columns_constructor=None, own_index=False)[source]

Frame constructor from an iterable of dictionaries, where each dictionary represents a column; index labels will be derived from the union of all column dictionary keys.

Parameters:
  • fields – Iterable of column values, where column values are dictionaries.

  • index – Optionally provide an iterable of index labels, equal in length to the number of fields. If a generator, this value will not be evaluated until after fields are loaded.

  • columns

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> sf.Frame.from_dict_fields(records=(dict(a=False, b=False, c=True), dict(a='1517-04-01', b='1517-01-01', c='1517-04-01')), columns=('p', 'q'), dtypes=dict(q=np.datetime64), name='x')
TypeError("Frame.from_dict_fields() got an unexpected keyword argument 'records'")
classmethod Frame.from_dict_records(records, *, index=None, dtypes=None, name=None, fill_value=nan, consolidate_blocks=False, index_constructor=None, columns_constructor=None, own_index=False)[source]

Frame constructor from an iterable of dictionaries, where each dictionary represents a row; column names will be derived from the union of all row dictionary keys.

Parameters:
  • records – Iterable of row values, where row values are dictionaries.

  • index – Optionally provide an iterable of index labels, equal in length to the number of records. If a generator, this value will not be evaluated until after records are loaded.

  • index

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> sf.Frame.from_dict_records(records=(dict(a=10, b=False, c='1517-01-01'), dict(a=8, b=True, c='1517-04-01')), index=('p', 'q'), dtypes=dict(c=np.datetime64), name='x')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
p          10      False  1517-01-01
q          8       True   1517-04-01
<<U1>      <int64> <bool> <datetime64[D]>
classmethod Frame.from_dict_records_items(items, *, dtypes=None, name=None, consolidate_blocks=False)[source]

Frame constructor from iterable of pairs of index label, row, where row is a dictionary. Column names will be derived from the union of all row dictionary keys.

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

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> sf.Frame.from_dict_records_items(items=(('p', dict(a=10, b=False, c='1517-01-01')), ('q', dict(a=8, b=True, c='1517-04-01'))), dtypes=dict(c=np.datetime64), name='x')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
p          10      False  1517-01-01
q          8       True   1517-04-01
<<U1>      <int64> <bool> <datetime64[D]>
classmethod Frame.from_duckdb(fp, *, label, index_depth=0, index_constructors=None, columns_depth=1, columns_constructors=None, consolidate_blocks=False)[source]

Load Frame from the contents of a table in an SQLite database file.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), ('qrs ', 'XYZ', '123', ' wX ')), columns=('a', 'b'), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> f1.to_duckdb('/tmp/f.db')
>>> sf.Frame.from_duckdb('/tmp/f.db', label=f1.name, index_depth=1)
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
classmethod Frame.from_element(element, *, index, columns, dtype=None, name=None, index_constructor=None, columns_constructor=None, own_index=False, own_columns=False)[source]

Create a Frame from an element, i.e., a single value stored in a single cell. Both index and columns are required, and cannot be specified with IndexAutoFactory.

>>> sf.Frame.from_element(0, index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       0
q          0       0
r          0       0
<<U1>      <int64> <int64>
classmethod Frame.from_element_items(items, *, index, columns, dtype=None, axis=None, name=None, fill_value=<object object>, index_constructor=None, columns_constructor=None, own_index=False, own_columns=False)[source]

Create a Frame from an iterable of key, value, where key is a pair of row, column labels.

This function is partialed (setting the index and columns) and used by IterNodeDelegate as the apply constructor for doing application on element iteration.

Parameters:
  • items – an iterable of pairs of 2-tuples of row, column loc labels and values.

  • axis – when None, items can be in an order; when 0, items must be well-formed and ordered row major; when 1, items must be well-formed and ordered columns major.

Returns:

static_frame.Frame

>>> sf.Frame.from_element_items(((('a', 0), -1), (('b', 0), 10), (('a', 1), 3), (('b', 'a'), 1)), columns=(0, 1), index=('a', 'b'), name='x', axis=1)
ErrorInitTypeBlocks('Array block has unaligned row count: found 1, expected 2')
classmethod Frame.from_elements(elements, *, index=None, columns=None, dtype=None, name=None, index_constructor=None, columns_constructor=None, own_index=False, own_columns=False)[source]

Create a Frame from an iterable of elements, to be formed into a Frame with a single column.

>>> sf.Frame.from_elements((10, 2, 8, 3), index=('p', 'q', 'r', 's'), columns=['a'], name='x')
<Frame: x>
<Index>    a       <<U1>
<Index>
p          10
q          2
r          8
s          3
<<U1>      <int64>
classmethod Frame.from_fields(fields, *, index=None, columns=None, fill_value=nan, dtypes=None, name=None, index_constructor=None, columns_constructor=None, own_index=False, own_columns=False, consolidate_blocks=False)[source]

Frame constructor from an iterator of columns, where columns are iterables. Series can be provided as values if an index argument is supplied. This constructor is similar to from_items(), though here columns are provided through an independent columns argument.

Parameters:
  • fields – Iterable of 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 (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
classmethod Frame.from_hdf5(fp, *, label, index_depth=0, index_constructors=None, columns_depth=1, columns_constructors=None, name=<object object>, consolidate_blocks=False)[source]

Load Frame from the contents of a table in an HDF5 file.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), ('qrs ', 'XYZ', '123', ' wX ')), columns=('a', 'b'), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> f1.to_hdf5('/tmp/f.hdf5')
>>> f1.from_hdf5('/tmp/f.hdf5', label='x', index_depth=1)
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
classmethod Frame.from_items(pairs, *, index=None, fill_value=nan, dtypes=None, name=None, index_constructor=None, columns_constructor=None, consolidate_blocks=False)[source]

Frame constructor from an iterator of pairs, where the first value is the column label and the second value is an iterable of column values. Series can be provided as values if an index argument is supplied.

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 (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

  • index_constructor

  • columns_constructor

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

Returns:

Frame

>>> sf.Frame.from_items((('a', (10, 2, 8, 3)), ('b', ('qrs ', 'XYZ', '123', ' wX '))), index=('p', 'q', 'r', 's'), name='x')
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
classmethod Frame.from_json_columns(json_data, *, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON object keyed by column labels, where values are columns represented by an object mapping of index labels to values.

Parameters:
  • json_data – a string or StringIO of JSON data

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_columns(indent=4)
>>> msg
{
    "a": {
        "0": 10,
        "1": 2,
        "2": 8,
        "3": 3
    },
    "b": {
        "0": false,
        "1": true,
        "2": true,
        "3": false
    },
    "c": {
        "0": "1517-01-01",
        "1": "1517-04-01",
        "2": "1517-12-31",
        "3": "1517-06-30"
    }
}
>>> sf.Frame.from_json_columns(msg, dtypes=dict(c=np.datetime64))
<Frame>
<Index> a       b      c          <<U1>
<Index>
0       10      False  1517-01-01
1       2       True   1517-04-01
2       8       True   1517-12-31
3       3       False  1517-06-30
<<U1>   <int64> <bool> <<U10>
classmethod Frame.from_json_index(json_data, *, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON object keyed by index labels, where values are rows represented by an object mapping of column labels to values.

Parameters:
  • json_data – a string or StringIO of JSON data

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_index(indent=4)
>>> msg
{
    "0": {
        "a": 10,
        "b": false,
        "c": "1517-01-01"
    },
    "1": {
        "a": 2,
        "b": true,
        "c": "1517-04-01"
    },
    "2": {
        "a": 8,
        "b": true,
        "c": "1517-12-31"
    },
    "3": {
        "a": 3,
        "b": false,
        "c": "1517-06-30"
    }
}
>>> sf.Frame.from_json_index(msg, dtypes=dict(c=np.datetime64))
<Frame>
<Index> a       b      c               <<U1>
<Index>
0       10      False  1517-01-01
1       2       True   1517-04-01
2       8       True   1517-12-31
3       3       False  1517-06-30
<<U1>   <int64> <bool> <datetime64[D]>
classmethod Frame.from_json_records(json_data, *, index=None, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON array of row objects, where column labels are repeated for each row, and no index labels are included.

Parameters:
  • json_data – a string or StringIO of JSON data

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_records(indent=4)
>>> msg
[
    {
        "a": 10,
        "b": false,
        "c": "1517-01-01"
    },
    {
        "a": 2,
        "b": true,
        "c": "1517-04-01"
    },
    {
        "a": 8,
        "b": true,
        "c": "1517-12-31"
    },
    {
        "a": 3,
        "b": false,
        "c": "1517-06-30"
    }
]
>>> sf.Frame.from_json_records(msg, dtypes=dict(c=np.datetime64))
<Frame>
<Index> a       b      c               <<U1>
<Index>
0       10      False  1517-01-01
1       2       True   1517-04-01
2       8       True   1517-12-31
3       3       False  1517-06-30
<int64> <int64> <bool> <datetime64[D]>
classmethod Frame.from_json_split(json_data, *, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON object with a key for “columns”, “index”, and “data”, where data is given as an array of arrays of row values.

Parameters:
  • json_data – a string or StringIO of JSON data

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_split(indent=4)
>>> msg
{
    "columns": [
        "a",
        "b",
        "c"
    ],
    "index": [
        0,
        1,
        2,
        3
    ],
    "data": [
        [
            10,
            false,
            "1517-01-01"
        ],
        [
            2,
            true,
            "1517-04-01"
        ],
        [
            8,
            true,
            "1517-12-31"
        ],
        [
            3,
            false,
            "1517-06-30"
        ]
    ]
}
>>> sf.Frame.from_json_split(msg, dtypes=dict(c=np.datetime64))
<Frame>
<Index> a       b      c               <<U1>
<Index>
0       10      False  1517-01-01
1       2       True   1517-04-01
2       8       True   1517-12-31
3       3       False  1517-06-30
<int64> <int64> <bool> <datetime64[D]>
classmethod Frame.from_json_typed(json_data, *, consolidate_blocks=False)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON object with a key for “columns”, “index”, and “data”, where data is given as an array of arrays of column values; additionally, a key for “__meta__” defines an object with complete metadata and typing information.

Parameters:

json_data – a string or StringIO of JSON data

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), index=sf.IndexHierarchy.from_product((0, 1), ('p', 'q')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>                a       b      c               <<U1>
<IndexHierarchy>
0                p     10      False  1517-01-01
0                q     2       True   1517-04-01
1                p     8       True   1517-12-31
1                q     3       False  1517-06-30
<int64>          <<U1> <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_typed(indent=4)
>>> msg
{
    "columns": [
        "a",
        "b",
        "c"
    ],
    "index": [
        [
            0,
            "p"
        ],
        [
            0,
            "q"
        ],
        [
            1,
            "p"
        ],
        [
            1,
            "q"
        ]
    ],
    "data": [
        [
            10,
            2,
            8,
            3
        ],
        [
            false,
            true,
            true,
            false
        ],
        [
            "1517-01-01",
            "1517-04-01",
            "1517-12-31",
            "1517-06-30"
        ]
    ],
    "__meta__": {
        "__names__": [
            "x",
            null,
            null
        ],
        "__dtypes__": [
            "=i8",
            "|b1",
            "=M8[D]"
        ],
        "__dtypes_index__": [
            "=i8",
            "=U1"
        ],
        "__dtypes_columns__": [
            "=U1"
        ],
        "__types__": [
            "IndexHierarchy",
            "Index"
        ],
        "__types_index__": [
            "Index",
            "Index"
        ],
        "__depths__": [
            3,
            2,
            1
        ]
    }
}
>>> sf.Frame.from_json_typed(msg)
<Frame: x>
<Index>                a       b      c               <<U1>
<IndexHierarchy>
0                p     10      False  1517-01-01
0                q     2       True   1517-04-01
1                p     8       True   1517-12-31
1                q     3       False  1517-06-30
<int64>          <<U1> <int64> <bool> <datetime64[D]>
classmethod Frame.from_json_values(json_data, *, index=None, columns=None, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None)[source]

Frame constructor from an in-memory JSON document in the following format: A JSON array of arrays of row values; no index or columns labels are included.

Parameters:
  • json_data – a string or StringIO of JSON data

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> f = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> msg = f.to_json_values(indent=4)
>>> msg
[
    [
        10,
        false,
        "1517-01-01"
    ],
    [
        2,
        true,
        "1517-04-01"
    ],
    [
        8,
        true,
        "1517-12-31"
    ],
    [
        3,
        false,
        "1517-06-30"
    ]
]
>>> sf.Frame.from_json_values(msg, columns=tuple('abc'), dtypes=dict(c=np.datetime64))
<Frame>
<Index> a       b      c               <<U1>
<Index>
0       10      False  1517-01-01
1       2       True   1517-04-01
2       8       True   1517-12-31
3       3       False  1517-06-30
<int64> <int64> <bool> <datetime64[D]>
static Frame.from_msgpack(msgpack_data)[source]

Frame constructor from an in-memory binary object formatted as a msgpack.

Parameters:

msgpack_data – A binary msgpack object, encoding a Frame as produced from to_msgpack()

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), ('qrs ', 'XYZ', '123', ' wX ')), columns=('a', 'b'), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> mb = f1.to_msgpack()
>>> mb
b'\x85\xc4\x02sf\xa5Frame\xc4\x04name\xa1x\xc4\x06blocks\xc4\xcd\x82\xc4\x02sf\xaaTypeBlocks\xc4\x06blocks\xc4\xb3\x92\x85\xc4\x02nd\xc3\xc4\x04type\xa3<i8\xc4\x04kind\xc4\x00\xc4\x05shape\x91\x04\xc4\x04data\xc4 \n\x00\x00\x00\x00\x00\x00\x00\x02\x00\x00\x00\x00\x00\x00\x00\x08\x00\x00\x00\x00\x00\x00\x00\x03\x00\x00\x00\x00\x00\x00\x00\x85\xc4\x02nd\xc3\xc4\x04type\xa3<U4\xc4\x04kind\xc4\x00\xc4\x05shape\x91\x04\xc4\x04data\xc4@q\x00\x00\x00r\x00\x00\x00s\x00\x00\x00 \x00\x00\x00X\x00\x00\x00Y\x00\x00\x00Z\x00\x00\x00\x00\x00\x00\x001\x00\x00\x002\x00\x00\x003\x00\x00\x00\x00\x00\x00\x00 \x00\x00\x00w\x00\x00\x00X\x00\x00\x00 \x00\x00\x00\xc4\x05index\xc4S\x83\xc4\x02sf\xa5Index\xc4\x04name\xc0\xc4\x04data\xc49\x85\xc4\x02nd\xc3\xc4\x04type\xa3<U1\xc4\x04kind\xc4\x00\xc4\x05shape\x91\x04\xc4\x04data\xc4\x10p\x00\x00\x00q\x00\x00\x00r\x00\x00\x00s\x00\x00\x00\xc4\x07columns\xc4K\x83\xc4\x02sf\xa5Index\xc4\x04name\xc0\xc4\x04data\xc41\x85\xc4\x02nd\xc3\xc4\x04type\xa3<U1\xc4\x04kind\xc4\x00\xc4\x05shape\x91\x02\xc4\x04data\xc4\x08a\x00\x00\x00b\x00\x00\x00'
>>> sf.Frame.from_msgpack(mb)
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
classmethod Frame.from_npy(fp)[source]

Create a Frame from an directory of npy files.

Parameters:

fp – The path to the NPY directory.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_npy('/tmp/f.npy')
>>> sf.Frame.from_npy('/tmp/f.npy')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> import shutil
>>> shutil.rmtree('/tmp/f.npy')
classmethod Frame.from_npy_mmap(fp)[source]

Create a Frame from an directory of npy files using memory maps.

Parameters:

fp – The path to the NPY directory.

Returns:

A tuple of Frame and the callable needed to close the open memory map objects. On some platforms this must be called before the process exits.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_npy('/tmp/f.npy')
>>> f2, closer = sf.Frame.from_npy_mmap('/tmp/f.npy')
>>> f2
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> closer() # close mmaps after usage
>>> import shutil
>>> shutil.rmtree('/tmp/f.npy')
classmethod Frame.from_npz(fp)[source]

Create a Frame from an npz file.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_npz('/tmp/f.npz')
>>> sf.Frame.from_npz('/tmp/f.npz')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
classmethod Frame.from_overlay(containers, *, index=None, columns=None, union=True, name=None, func=<function isna_array>, fill_value=<object object>)[source]

Return a new Frame made by overlaying containers, filling in values with aligned values from subsequent containers. Values are filled based on a passed function that must return a Boolean array. By default, that function is isna_array, returning True for missing values (NaN and None).

Parameters:
  • containers – Iterable of Frame.

  • index – An optional Index, IndexHierarchy, or index initializer, to be used as the index upon which all containers are aligned. IndexAutoFactory is not supported.

  • columns – An optional Index, IndexHierarchy, or columns initializer, to be used as the columns upon which all containers are aligned. IndexAutoFactory is not supported.

  • union – If True, and no index or columns argument is supplied, a union index or columns from containers will be used; if False, the intersection index or columns will be used.

  • name

  • func – A function that takes an array and returns a same-sized Boolean array, where True indicates availability for insertion.

>>> f1 = sf.Frame.from_items((('a', (10, 2, np.nan, 3)), ('b', ('qrs ', 'XYZ', None, None))), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a         b        <<U1>
<Index>
p          10.0      qrs
q          2.0       XYZ
r          nan       None
s          3.0       None
<<U1>      <float64> <object>
>>> f2 = sf.Frame.from_items((('a', (8, 3)), ('b', ('123', ' wX '))), index=('r', 's'), name='y')
>>> f2
<Frame: y>
<Index>    a       b     <<U1>
<Index>
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> sf.Frame.from_overlay((f1, f2))
<Frame>
<Index> a         b        <<U1>
<Index>
p       10.0      qrs
q       2.0       XYZ
r       8.0       123
s       3.0        wX
<<U1>   <float64> <object>
classmethod Frame.from_pandas(value, *, index=None, index_constructor=None, columns=None, columns_constructor=None, dtypes=None, name=<object object>, consolidate_blocks=False, own_data=False)[source]

Given a Pandas DataFrame, return a Frame.

Parameters:
  • value – Pandas DataFrame.

  • index_constructor – Optional class or constructor function to create the Index applied to the rows.

  • columns_constructor – Optional class or constructor function to create the Index applied to the columns.

  • dtypes

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

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

Returns:

Frame

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), ('qrs ', 'XYZ', '123', ' wX ')), columns=('a', 'b'), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> df = f1.to_pandas()
>>> df
    a     b
p  10  qrs 
q   2   XYZ
r   8   123
s   3   wX 
>>> sf.Frame.from_pandas(df, dtypes=dict(b=str))
<Frame: x>
<Index>    a       b     <object>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<object>   <int64> <<U4>
classmethod Frame.from_parquet(fp, *, index_depth=0, index_name_depth_level=None, index_constructors=None, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, columns_select=None, dtypes=None, name=None, consolidate_blocks=False)[source]

Realize a Frame from a Parquet file.

Parameters:
  • fp – A string file path or Path instance.

  • index_depth – integer specification of how many columns to use in forming the index. A value of 0 will select none; a value greater than 1 will create an IndexHierarchy.

  • index_name_depth_level

  • index_constructors

  • columns_depth – integer specification of how many rows to use in forming the columns. A value of 0 will select none; a value greater than 1 will create an IndexHierarchy.

  • columns_name_depth_level

  • columns_constructors

  • columns_select – An optional iterable of column names to load.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), ('qrs ', 'XYZ', '123', ' wX ')), columns=('a', 'b'), index=('p', 'q', 'r', 's'), name='x')
>>> f1
<Frame: x>
<Index>    a       b     <<U1>
<Index>
p          10      qrs
q          2       XYZ
r          8       123
s          3        wX
<<U1>      <int64> <<U4>
>>> f1.to_parquet('/tmp/f.parquet')
>>> sf.Frame.from_parquet('/tmp/f.parquet', index_depth=1)
<Frame>
<Index>  a       b        <<U1>
<Index>
p        10      qrs
q        2       XYZ
r        8       123
s        3        wX
<object> <int64> <object>
classmethod Frame.from_pickle(fp)[source]

Create a Frame from a pickle file.

The pickle module is not secure. Only unpickle data you trust.

Parameters:

fp – The path to the pickle file.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_pickle('/tmp/f.pickle')
>>> sf.Frame.from_pickle('/tmp/f.pickle')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
classmethod Frame.from_records(records, *, index=None, columns=None, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None, own_index=False, own_columns=False)[source]

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

Supplying dtypes will significantly improve performance, as otherwise columnar array types must be derived by element-wise examination.

For records defined as Series, use Frame.from_concat; for records defined as dictionary, use Frame.from_dict_records; 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, or namedtuples. For dictionary records, use Frame.from_dict_records.

  • index – Optionally provide an iterable of index labels, equal in length to the number of records. If a generator, this value will not be evaluated until after records are loaded.

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

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

Frame

>>> sf.Frame.from_records(((10, False, '1517-01-01'), (8, True,'1517-04-01')), index=('p', 'q'), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
p          10      False  1517-01-01
q          8       True   1517-04-01
<<U1>      <int64> <bool> <datetime64[D]>
classmethod Frame.from_records_items(items, *, columns=None, dtypes=None, name=None, consolidate_blocks=False, index_constructor=None, columns_constructor=None, own_columns=False)[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 (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> sf.Frame.from_records_items((('p', (10, False, '1517-01-01')), ('q', (8, True,'1517-04-01'))), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
p          10      False  1517-01-01
q          8       True   1517-04-01
<<U1>      <int64> <bool> <datetime64[D]>
classmethod Frame.from_series(series, *, name=None, columns_constructor=None)[source]

Frame constructor from a Series:

Parameters:

series – A Series instance, to be realized as single column, with the column label taken from the name attribute.

>>> s = sf.Series((10, 2, 8), index=('a', 'b', 'c'), name='x')
>>> s
<Series: x>
<Index>
a           10
b           2
c           8
<<U1>       <int64>
>>> sf.Frame.from_series(s)
<Frame>
<Index> x       <<U1>
<Index>
a       10
b       2
c       8
<<U1>   <int64>
classmethod Frame.from_sql(query, *, connection, index_depth=0, index_constructors=None, columns_depth=1, columns_select=None, columns_constructors=None, dtypes=None, name=None, consolidate_blocks=False, parameters=())[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.

  • dtypes – Optionally provide an iterable of dtypes, equal in length to the length of each row, or a mapping by column name (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • index_depth

  • index_constructors

  • columns_depth

  • columns_select – An optional iterable of field names to extract from the results of the query.

  • columns_constructors

  • name – A hashable object to label the container.

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

  • parameters – Provide a list of values for an SQL query expecting parameter substitution.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_sqlite('/tmp/f.db')
>>> import sqlite3
>>> conn = sqlite3.connect('/tmp/f.db')
>>> sf.Frame.from_sql("select * from x limit 2", connection=conn, index_depth=1)
<Frame>
<Index> a       b       c          <<U1>
<Index>
0       10      0       1517-01-01
1       2       1       1517-04-01
<int64> <int64> <int64> <<U10>
classmethod Frame.from_sqlite(fp, *, label, index_depth=0, index_constructors=None, columns_depth=1, columns_constructors=None, dtypes=None, name=<object object>, consolidate_blocks=False)[source]

Load Frame from the contents of a table in an SQLite database file.

>>> f1 = sf.Frame.from_fields(((10, 2, 8, 3), (False, True, True, False), ('1517-01-01', '1517-04-01', '1517-12-31', '1517-06-30')), columns=('a', 'b', 'c'), dtypes=dict(c=np.datetime64), name='x')
>>> f1
<Frame: x>
<Index>    a       b      c               <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <datetime64[D]>
>>> f1.to_sqlite('/tmp/f.db')
>>> sf.Frame.from_sqlite('/tmp/f.db', label=f1.name, index_depth=1)
<Frame: x>
<Index>    a       b      c          <<U1>
<Index>
0          10      False  1517-01-01
1          2       True   1517-04-01
2          8       True   1517-12-31
3          3       False  1517-06-30
<int64>    <int64> <bool> <<U10>
classmethod Frame.from_structured_array(array, *, index_depth=0, index_column_first=None, index_constructors=None, columns_depth=1, columns_constructors=None, dtypes=None, name=None, consolidate_blocks=False, store_filter=<static_frame.core.store_filter.StoreFilter object>)[source]

Convert a NumPy structed array into a Frame.

Parameters:
  • array – Structured NumPy array.

  • index_depth – Depth if index levels, where (for example) 0 is no index, 1 is a single column index, and 2 is a two-columns IndexHierarchy.

  • index_column_first – 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 (where overspecied labels is not an error). If a dtype is given as None, element-wise type determination will be used.

  • name – A hashable object to label the container.

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

Returns:

static_frame.Frame

>>> sa = np.array([(False, 8), (True, 19)], dtype=[('a', bool), ('b', int)])
>>> sa
[(False,  8) ( True, 19)]
>>> sf.Frame.from_structured_array(sa)
<Frame>
<Index> a      b       <<U1>
<Index>
0       False  8
1       True   19
<int64> <bool> <int64>
classmethod Frame.from_tsv(fp, *, index_depth=0, index_column_first=0, index_name_depth_level=None, index_constructors=None, index_continuation_token=<object object>, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, columns_continuation_token=<object object>, columns_select=None, skip_header=0, skip_footer=0, skip_initial_space=False, quoting=0, quote_char='"', quote_double=True, escape_char=None, thousands_char='', decimal_char='.', encoding=None, dtypes=None, name=None, consolidate_blocks=False, store_filter=None)[source]

Specialized version of Frame.from_delimited for TSV files.

Returns:

static_frame.Frame

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f1.to_tsv('/tmp/f.tsv')
>>> from pathlib import Path
>>> Path('/tmp/f.tsv').read_text()
__index0__	a	b
p	0	1
q	2	3
r	4	5

>>> sf.Frame.from_tsv('/tmp/f.tsv', index_depth=1)
<Frame>
<Index> a       b       <<U1>
<Index>
p       0       1
q       2       3
r       4       5
<<U1>   <int64> <int64>
classmethod Frame.from_xlsx(fp, *, label=<object object>, index_depth=0, index_name_depth_level=None, index_constructors=None, columns_depth=1, columns_name_depth_level=None, columns_constructors=None, dtypes=None, name=<object object>, consolidate_blocks=False, skip_header=0, skip_footer=0, trim_nadir=False, store_filter=<static_frame.core.store_filter.StoreFilter object>)[source]

Load Frame from the contents of a sheet in an XLSX workbook.

Parameters:

label – Optionally provide the sheet name from which to read. If not provided, the first sheet will be used.

>>> f1 = sf.Frame(np.arange(6).reshape(3,2), index=('p', 'q', 'r'), columns=('a', 'b'), name='x')
>>> f1
<Frame: x>
<Index>    a       b       <<U1>
<Index>
p          0       1
q          2       3
r          4       5
<<U1>      <int64> <int64>
>>> f1.to_xlsx('/tmp/f.xlsx')
>>> sf.Frame.from_xlsx('/tmp/f.xlsx', index_depth=1)
<Frame>
<Index> a       b       <<U1>
<Index>
p       0       1
q       2       3
r       4       5
<<U1>   <int64> <int64>

Frame: Constructor | Exporter | Attribute | Method | Dictionary-Like | Display | Assignment | Selector | Iterator | Operator Binary | Operator Unary | Accessor Values | Accessor Datetime | Accessor String | Accessor Transpose | Accessor Fill Value | Accessor Regular Expression | Accessor Hashlib | Accessor Type Clinic | Accessor Reduce