biocframe package

Subpackages

• biocframe.io package
  • Submodules
  • biocframe.io.from_pandas module
    • from_pandas()
  • Module contents

Submodules

biocframe.BiocFrame module

class biocframe.BiocFrame.BiocFrame(data: Dict[str, Any] | None = None, number_of_rows: int | None = None, row_names: List | None = None, column_names: List[str] | None = None, column_data: BiocFrame | None = None, metadata: dict | None = None, validate: bool = True)

Bases: object

BiocFrame is an alternative to DataFrame, with support for nested and flexible column types. Inspired by the DFrame class from Bioconductor’s S4Vectors package. Any object may be used as a column, provided it has:

• Some concept of “height”, as defined by get_height() from BiocUtils. This defaults to the length as defined by __len__.

• The ability to be sliced by integer indices, as implemented by subset() from BiocUtils. This defaults to calling __getitem__.

• The ability to be combined with other objects, as implemented in combine() from BiocUtils.

• The ability to perform an assignment, as implemented in assign() from BiocUtils.

This allows BiocFrame to accept arbitrarily complex classes (such as nested BiocFrame instances) as columns.

__array_ufunc__(func, method, *inputs, **kwargs) → BiocFrame

Interface for NumPy array methods.

Note: This is a very primitive implementation and needs tests to support different types.

Returns:

An object with the same type as the caller.

__copy__()

Returns:

A shallow copy of the current BiocFrame.

__deepcopy__(memo=None, _nil=[])

Returns:

A deep copy of the current BiocFrame.

__delitem__(name: str)

Alias for remove_column with in_place = True.

As this mutates the original object, a warning is raised.

__getitem__(args: int | str | Sequence | tuple) → BiocFrame | Any

Wrapper around get_column and get_slice to obtain a slice of a BiocFrame or any of its columns.

Parameters:

args –

A sequence or a scalar integer or string, specifying the columns to retain based on their names or indices.

Alternatively a tuple of length 1. The first entry specifies the rows to retain based on their names or indices.

Alternatively a tuple of length 2. The first entry specifies the rows to retain, while the second entry specifies the columns to retain, based on their names or indices.

Returns:

If args is a scalar, the specified column is returned. This is achieved internally by calling get_column.

If args is a sequence, a new BiocFrame is returned containing only the specified columns. This is achieved by just calling get_slice with no row slicing.

If args is a tuple of length 1, a new BiocFrame is returned containing the specified rows. This is achieved by just calling get_slice with no column slicing.

If args is a tuple of length 2, a new BiocFrame is returned containing the specified rows and columns. This is achieved by just calling get_slice with the specified arguments.

__init__(data: Dict[str, Any] | None = None, number_of_rows: int | None = None, row_names: List | None = None, column_names: List[str] | None = None, column_data: BiocFrame | None = None, metadata: dict | None = None, validate: bool = True) → None

Initialize a BiocFrame object from columns.

Parameters:

• data – Dictionary of column names as keys and their values. All columns must have the same length. Defaults to an empty dictionary.

• number_of_rows – Number of rows. If not specified, inferred from data. This needs to be provided if data is empty and row_names are not present.

• row_names – Row names. This should not contain missing strings.

• column_names – Column names. If not provided, inferred from the data. This may be in a different order than the keys of data. This should not contain missing strings.

• column_data – Metadata about columns. Must have the same number of rows as the length of column_names. Defaults to None.

• metadata – Additional metadata. Defaults to an empty dictionary.

• validate – Internal use only.

__iter__() → BiocFrameIter

Iterator over rows.

__len__() → int

Returns:

Number of rows.

__repr__() → str

Returns:

A string representation of this BiocFrame.

__setitem__(args: int | str | Sequence | tuple, value: BiocFrame)

Wrapper around set_column and set_slice to modify a slice of a BiocFrame or any of its columns. As this modified the original object in place, a warning is raise.

If args is a string, it is assumed to be a column name and value is expected to be the column contents; these are passed onto set_column with in_place = True.

If args is a tuple, it is assumed to contain row and column indices. value is expected to be a BiocFrame containing replacement values. These are passed to set_slice with in_place = True.

property colnames: Names

Alias for get_column_names, provided for back-compatibility only.

column(column: str | int) → Any

Alias for get_column(), provided for back-compatibility only.

property column_data: None | BiocFrame

Alias for get_column_data.

property column_names: Names

Alias for get_column_names.

property columns: Names

Alias for get_column_names, provided for compatibility with pandas.

combine(*other)

Wrapper around relaxed_combine_rows(), provided for back-compatibility only.

copy()

Alias for __copy__().

property data: Dict[str, Any]

Alias for get_data.

property dims: Tuple[int, int]

Alias for shape.

flatten(as_type: Literal['dict', 'biocframe'] = 'dict', delim: str = '.') → BiocFrame

Flatten a nested BiocFrame object.

Parameters:

• as_type – Return type of the result. Either a dict or a BiocFrame object.

• delim – Delimiter to join nested column names. Defaults to “.”.

Returns:

An object with the type specified by as_type argument. If as_type is dict, an additional column “rownames” is added if the object contains rownames.

classmethod from_pandas(input: pandas.DataFrame) → BiocFrame

Create a BiocFrame from a DataFrame object.

Parameters:

input – Input data.

Returns:

A BiocFrame object.

classmethod from_polars(input: polars.DataFrame) → BiocFrame

Create a BiocFrame from a DataFrame object.

Parameters:

input – Input data.

Returns:

A BiocFrame object.

get_column(column: str | int) → Any

Parameters:

column –

Name of the column, which must exist in get_column_names.

Alternatively, the integer index of the column of interest.

Returns:

The contents of the specified column.

get_column_data(with_names: bool = True) → None | BiocFrame

Parameters:

with_names – Whether to set the column names of this BiocFrame as the row names of the column data BiocFrame.

Returns:

The annotations for each column. This may be None if no annotation is present, or is a BiocFrame where each row corresponds to a column and contains that column’s metadata.

get_column_names() → Names

Returns:

A list of column names.

get_data() → Dict[str, Any]

Returns:

Dictionary of columns and their values.

get_metadata() → dict

Returns:

Dictionary of metadata for this object.

get_row(row: str | int) → dict

Parameters:

row –

Integer index of the row to access.

If row names are available (see get_row_names), a string may be supplied instead. The first occurrence of the string in the row names is used.

Returns:

A dictionary where the keys are column names and the values are the contents of the columns at the specified row.

get_row_names() → Names | None

Returns:

List of row names, or None if no row names are available.

get_slice(rows: str | int | bool | Sequence, columns: str | int | bool | Sequence) → BiocFrame

Slice BiocFrame along the rows and/or columns, based on their indices or names.

Parameters:

• rows –

  Rows to be extracted. This may be an integer, boolean, string, or any sequence thereof, as supported by normalize_subscript(). Scalars are treated as length-1 sequences.

  Strings may only be used if row names are available (see get_row_names). The first occurrence of each string in the row names is used for extraction.

• columns – Columns to be extracted. This may be an integer, boolean, string, or any sequence thereof, as supported by normalize_subscript(). Scalars are treated as length-1 sequences.

Returns:

A BiocFrame with the specified rows and columns.

has_column(name: str) → bool

Parameters:

name – Name of the column.

Returns:

Whether a column with the specified name exists in this object.

property index: Names | None

Alias to get_row_names, provided for compatibility with pandas.

property metadata: dict

Alias for get_metadata.

remove_column(column: int | str, in_place: bool = False) → BiocFrame

Remove a column. This is a convenience wrapper around remove_columns.

Parameters:

• column – Name or positional index of the column to remove.

• in_place – Whether to modify the object in place. Defaults to False.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

remove_columns(columns: Sequence[int | str], in_place: bool = False) → BiocFrame

Remove any number of existing columns.

Parameters:

• columns – Names or indices of the columns to remove.

• in_place – Whether to modify the object in place. Defaults to False.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

Return type:

BiocFrame

row(row: str | int) → dict

Alias for get_row, provided for back-compatibility only.

property row_names: Names | None

Alias for get_row_names.

property rownames: Names | None

Alias for get_row_names, provided for back-compatibility.

set_column(column: int | str, value: Any, in_place: bool = False) → BiocFrame

Modify an existing column or add a new column. This is a convenience wrapper around set_columns.

Parameters:

• column – Name of an existing or new column. Alternatively, an index specifying the position of an existing column.

• value – Value of the new column. This should have the same height as the number of rows in the current object.

• in_place – Whether to modify the object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_column_data(column_data: None | BiocFrame, in_place: bool = False) → BiocFrame

Parameters:

• column_data – New column data. This should either be a BiocFrame with the numbero of rows equal to the number of columns in the current object, or None to remove existing column data.

• in_place – Whether to modify the BiocFrame object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_column_names(names: List[str], in_place: bool = False) → BiocFrame

Parameters:

• names – List of unique strings, of length equal to the number of columns in this BiocFrame.

• in_place – Whether to modify the BiocFrame object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_columns(columns: Dict[str, Any], in_place: bool = False) → BiocFrame

Modify existing columns or add new columns.

Parameters:

• columns – Contents of the columns to set. Keys may be strings containing new or existing column names, or integers containing the position of the column. Values should be the contents of each column.

• in_place – Whether to modify the object in place. Defaults to False.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_metadata(metadata: dict, in_place: bool = False) → BiocFrame

Parameters:

• metadata – New metadata for this object.

• in_place – Whether to modify the BiocFrame object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_row_names(names: List | None, in_place: bool = False) → BiocFrame

Parameters:

• names – List of strings. This should have length equal to the number of rows in the current BiocFrame.

• in_place – Whether to modify the BiocFrame object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

set_slice(rows: int | str | bool | Sequence, columns: int | str | bool | Sequence, value: BiocFrame, in_place: bool = True) → BiocFrame

Replace a slice of the BiocFrame given the row and columns of the slice.

Parameters:

• rows –

  Rows to be replaced. This may be any sequence of strings, integers, or booleans (or mixture thereof), as supported by normalize_subscript(). Scalars are treated as length-1 sequences.

  Strings may only be used if row names are available (see get_row_names). The first occurrence of each string in the row names is used for extraction.

• columns – Columns to be replaced. This may be any sequence of strings, integers, or booleans (or mixture thereof), as supported by normalize_subscript(). Scalars are treated as length-1 sequences.

• value – A BiocFrame containing replacement values. Each row corresponds to a row in rows, while each column corresponds to a column in columns. Note that the replacement is based on position, so row and column names in value are ignored.

• in_place – Whether to modify the BiocFrame object in place.

Returns:

A modified BiocFrame object, either as a copy of the original or as a reference to the (in-place-modified) original.

property shape: Tuple[int, int]

Returns: Tuple containing the number of rows and columns in this BiocFrame.

slice(rows: Sequence, columns: Sequence) → BiocFrame

Alias for __getitem__, for back-compatibility.

split(column_name: str, only_indices: bool = False) → Dict[str, BiocFrame | List[int]]

Split the object by a column.

Parameters:

• column_name – Name of the column to split by.

• only_indices – Whether to only return indices. Defaults to False

Returns:

A dictionary of biocframe objects, with names representing the group and the value the sliced frames.

if only_indices is True, the values contain the row indices that map to the same group.

to_pandas()

Convert the BiocFrame into a DataFrame object.

Returns:

A DataFrame object. Column names of the resulting dataframe may be different is the BiocFrame is nested.

to_polars()

Convert the BiocFrame into a DataFrame object.

Returns:

A DataFrame object. Column names of the resulting dataframe may be different is the BiocFrame is nested.

class biocframe.BiocFrame.BiocFrameIter(obj: BiocFrame)

Bases: object

An iterator to a BiocFrame object.

Parameters:

obj (BiocFrame) – Source object to iterate.

__init__(obj: BiocFrame) → None

Initialize the iterator.

Parameters:

obj (BiocFrame) – source object to iterate.

__iter__()

__next__()

biocframe.BiocFrame.merge(x: Sequence[BiocFrame], by: None | str | Sequence = None, join: Literal['inner', 'left', 'right', 'outer'] = 'left', rename_duplicate_columns: bool = False) → BiocFrame

Merge multiple BiocFrame` objects together by common columns or row names, yielding a combined object with a union of columns across all objects.

Parameters:

• x – Sequence of BiocFrame objects. Each object may have any number and identity of rows and columns.

• by –

  If string, the name of column containing the keys. Each entry of x is assumed to have this column.

  If integer, the index of column containing the keys. The same index is used for each entry of x.

  If None, keys are assumed to be present in the row names.

  Alternatively a sequence of strings, integers or None, specifying the location of the keys in each entry of x.

• join – Strategy for the merge. For left and right joins, we consider the keys for the first and last object in x, respectively.

• rename_duplicate_columns – Whether duplicated non-key columns across x should be automatically renamed in the merged object. If False, an error is raised instead.

Returns:

A BiocFrame containing the merged contents.

If by = None, the keys are stored in the row names.

If by is a string, keys are stored in the column of the same name.

If by is a sequence, keys are stored in the row names if by[0] = None, otherwise they are stored in the column named by[0].

Return type:

BiocFrame

biocframe.BiocFrame.relaxed_combine_columns(*x: BiocFrame) → BiocFrame

Wrapper around merge() that performs a left join on the row names.

biocframe.BiocFrame.relaxed_combine_rows(*x: BiocFrame) → BiocFrame

A relaxed version of the combine_rows() method for BiocFrame objects. Whereas combine_rows expects that all objects have the same columns, relaxed_combine_rows allows for different columns. Absent columns in any object are filled in with appropriate placeholder values before combining.

Parameters:

x – One or more BiocFrame objects, possibly with differences in the number and identity of their columns.

Returns:

A BiocFrame that combines all x along their rows and contains the union of all columns. Columns absent in any x are filled in with placeholders consisting of Nones or masked NumPy values.

Module contents