raccoon.series module

Series class

class raccoon.series.Series(data: list[T] | None = None, index: Sequence[IndexT] | None = None, data_name: str | tuple | None = 'value', index_name: str | tuple | None = 'index', sort: bool | None = None)

Bases: SeriesBase, Generic

Series class. The raccoon Series implements a simplified version of the pandas Series with the key objective difference that the raccoon Series is meant for use cases where the size of the Series rows is expanding frequently. This is known to be slow with Pandas due to the use of numpy as the underlying data structure. Raccoon uses native lists as the underlying data structure which is quick to expand and grow the size. The Series can be designated as sort, in which case the rows will be sort by index on construction, and then any addition of a new row will insert it into the Series so that the index remains sort.

Parameters:

• data – (optional) list of values.

• index – (optional) list of index values. If None then the index will be integers starting with zero

• data_name – (optional) name of the data column, or will default to ‘value’

• index_name – (optional) name for the index. Default is “index”

• sort – if True then Series will keep the index sort. If True all index values must be of same type. If None then will default to True if no index is provided.

append_row(index: IndexT, value: T) → None

Appends a row of value to the end of the data. Be very careful with this function as for sorted Series it will not enforce sort order. Use this only for speed when needed, be careful.

Parameters:

• index – index

• value – value

Returns:

nothing

append_rows(indexes: list[IndexT], values: list[T]) → None

Appends values to the end of the data. Be very careful with this function as for sort DataFrames it will not enforce sort order. Use this only for speed when needed, be careful.

Parameters:

• indexes – list of indexes to append

• values – list of values to append

Returns:

nothing

property data: list[T]

property data_name: str | tuple | None

delete(indexes: Any | list[Any] | list[bool]) → None

Delete rows from the DataFrame

Parameters:

indexes – either a list of values or list of booleans for the rows to delete

Returns:

nothing

equality(indexes: list[IndexT] | list[bool] | None = None, value: Any = None) → list[bool]

Math helper method. Given a column and optional indexes will return a list of booleans on the equality of the value for that index in the DataFrame to the value parameter.

Parameters:

• indexes – list of index values or list of booleans. If a list of booleans then the list must be the same length as the DataFrame

• value – value to compare

Returns:

list of booleans

get(indexes: Any | list[Any] | list[bool], as_list: bool = False) → Series[IndexT, T] | list[T] | T

Given indexes will return a sub-set of the Series. This method will direct to the specific methods based on what types are passed in for the indexes. The type of the return is determined by the types of the parameters.

Parameters:

• indexes – index value, list of index values, or a list of booleans.

• as_list – if True then return the values as a list, if False return a Series.

Returns:

either Series, list, or single value. The return is a shallow copy

get_cell(index: IndexT) → T

For a single index and return the value

Parameters:

index – index value

Returns:

value

get_location(location: int) → dict[Any, IndexT | T]

For an index location return a dict of the index and value. This is optimized for speed because it does not need to look up the index location with a search. Also, can accept relative indexing from the end of the SEries in standard python notation [-3, -2, -1]

Parameters:

location – index location in standard python form of positive or negative number

Returns:

dictionary

get_locations(locations: list[int], as_list: bool = False) → Series[IndexT, T] | list[T]

For list of locations return a Series or list of the values.

Parameters:

• locations – list of index locations

• as_list – True to return a list of values

Returns:

Series or list

get_rows(indexes: list[Any] | list[bool], as_list: bool = False) → Series[IndexT, T] | list[T]

For a list of indexes return the values of the indexes in that column.

Parameters:

• indexes – either a list of index values or a list of booleans with same length as all indexes

• as_list – if True return a list, if False return Series

Returns:

Series if as_list if False, a list if as_list is True

get_slice(start_index: Any = None, stop_index: Any = None, as_list: bool = False) → Series[IndexT, T] | tuple[list[IndexT], list[T]]

For sorted Series will return either a Series or list of all the rows where the index is greater than or equal to the start_index if provided and less than or equal to the stop_index if provided. If either the start or stop index is None then will include from the first or last element, similar to standard python slide of [:5] or [:5]. Both end points are considered inclusive.

Parameters:

• start_index – lowest index value to include, or None to start from the first row

• stop_index – highest index value to include, or None to end at the last row

• as_list – if True then return a list of the indexes and values

Returns:

Series or tuple of (index list, values list)

head(rows: int) → Series[IndexT, T]

Return a Series of the first N rows

Parameters:

rows – number of rows

Returns:

Series

property index: list[IndexT]

property index_name: str | tuple | None

isin(compare_list: list[Any]) → list[bool]

Returns a boolean list where each element is whether that element in the column is in the compare_list.

Parameters:

compare_list – list of items to compare to

Returns:

list of booleans

print(index: bool = True, **kwargs: Any) → None

Print the contents of the Series. This method uses the tabulate function from the tabulate package. Use the kwargs to pass along any arguments to the tabulate function.

Parameters:

• index – If True then include the indexes as a column in the output, if False ignore the index

• kwargs – Parameters to pass along to the tabulate function

Returns:

output of the tabulate function

reset_index() → None

Resets the index of the Series to simple integer list and the index name to ‘index’.

Returns:

nothing

select_index(compare: IndexT | tuple[Any, ...], result: Literal['boolean', 'value'] = 'boolean') → list[bool] | list[IndexT]

Finds the elements in the index that match the compare parameter and returns either a list of the values that match, of a boolean list the length of the index with True to each index that matches. If the indexes are tuples then the compare is a tuple where None in any field of the tuple will be treated as “*” and match all values.

Parameters:

• compare – value to compare as a singleton or tuple

• result – ‘boolean’ = returns a list of booleans, ‘value’ = returns a list of index values that match

Returns:

list of booleans or values

set(indexes: Any | list[Any] | list[bool], values: T | list[T] | Any = None) → None

Given indexes will set a sub-set of the Series to the values provided. This method will direct to the below methods based on what types are passed in for the indexes. If the indexes contain values not in the Series then new rows or columns will be added.

Parameters:

• indexes – indexes value, list of indexes values, or a list of booleans.

• values – value or list of values to set. If a list then must be the same length as the index’s parameter.

Returns:

nothing

set_cell(index: IndexT, value: T | Any) → None

Sets the value of a single cell. If the index is not in the current index then a new index will be created.

Parameters:

• index – index value

• value – value to set

Returns:

nothing

set_location(location: int, value: Any) → None

For a location set the value

Parameters:

• location – location

• value – value

Returns:

nothing

set_locations(locations: list[int], values: list[Any] | Any) → None

For a list of locations set the values.

Parameters:

• locations – list of index locations

• values – list of values or a single value

Returns:

nothing

set_rows(index: list[Any] | list[bool], values: T | list[T] | Any = None) → None

Set rows to a single value or list of values. If any of the index values are not in the current indexes then a new row will be created.

Parameters:

• index – list of index values or list of booleans. If a list of booleans then the list must be the same length as the Series

• values – either a single value or a list. The list must be the same length as the index list if the index list is values, or the length of the True values in the index list if the index list is booleans

Returns:

nothing

property sort: bool

sort_index() → None

Sort the Series by the index. The sort modifies the Series inplace

Returns:

nothing

tail(rows: int) → Series[IndexT, T]

Return a Series of the last N rows

Parameters:

rows – number of rows

Returns:

Series

to_dict(index: bool = True, ordered: bool = False) → dict[Any, Any] | OrderedDict[Any, Any]

Returns a dict where the keys are the data and index names and the values are list of the data and index.

Parameters:

• index – If True then include the index in the dict with the index_name as the key

• ordered – If True then return an OrderedDict() to preserve the order of the columns in the Series

Returns:

dict or OrderedDict()

validate_integrity() → None

Validate the integrity of the Series. This checks that the indexes, column names and internal data are not corrupted. Will raise an error if there is a problem.

Returns:

nothing

class raccoon.series.SeriesBase

Bases: ABC, Generic

Base Series abstract base class that concrete implementations inherit from. Note that the .data and .index property methods in Series are views to the underlying data and not copies.

No specific parameters, those are defined in the child classed

abstract property data: Sequence[T]

property data_name: str | tuple | None

equality(indexes: list[IndexT] | list[bool] | None = None, value: Any = None) → list[bool]

Math helper method. Given a column and optional indexes will return a list of booleans on the equality of the value for that index in the DataFrame to the value parameter.

Parameters:

• indexes – list of index values or list of booleans. If a list of booleans then the list must be the same length as the DataFrame

• value – value to compare

Returns:

list of booleans

get(indexes: list[IndexT] | list[bool], as_list: Literal[True]) → list[T]

get(indexes: list[IndexT] | list[bool], as_list: Literal[False] = False) → Series[IndexT, T]

get(indexes: IndexT, as_list: bool = False) → T

Given indexes will return a sub-set of the Series. This method will direct to the specific methods based on what types are passed in for the indexes. The type of the return is determined by the types of the parameters.

Parameters:

• indexes – index value, list of index values, or a list of booleans.

• as_list – if True then return the values as a list, if False return a Series.

Returns:

either Series, list, or single value. The return is a shallow copy

get_cell(index: IndexT) → T

For a single index and return the value

Parameters:

index – index value

Returns:

value

get_location(location: int) → dict[Any, IndexT | T]

For an index location return a dict of the index and value. This is optimized for speed because it does not need to look up the index location with a search. Also, can accept relative indexing from the end of the SEries in standard python notation [-3, -2, -1]

Parameters:

location – index location in standard python form of positive or negative number

Returns:

dictionary

get_locations(locations: list[int], as_list: Literal[True]) → list[T]

get_locations(locations: list[int], as_list: Literal[False] = False) → Series[IndexT, T]

For list of locations return a Series or list of the values.

Parameters:

• locations – list of index locations

• as_list – True to return a list of values

Returns:

Series or list

get_rows(indexes: list[IndexT] | list[bool], as_list: Literal[True]) → list[T]

get_rows(indexes: list[IndexT] | list[bool], as_list: Literal[False] = False) → Series[IndexT, T]

For a list of indexes return the values of the indexes in that column.

Parameters:

• indexes – either a list of index values or a list of booleans with same length as all indexes

• as_list – if True return a list, if False return Series

Returns:

Series if as_list if False, a list if as_list is True

get_slice(start_index: Any = None, stop_index: Any = None, *, as_list: Literal[True]) → tuple[list[IndexT], list[T]]

get_slice(start_index: Any = None, stop_index: Any = None, *, as_list: Literal[False] = False) → Series[IndexT, T]

For sorted Series will return either a Series or list of all the rows where the index is greater than or equal to the start_index if provided and less than or equal to the stop_index if provided. If either the start or stop index is None then will include from the first or last element, similar to standard python slide of [:5] or [:5]. Both end points are considered inclusive.

Parameters:

• start_index – lowest index value to include, or None to start from the first row

• stop_index – highest index value to include, or None to end at the last row

• as_list – if True then return a list of the indexes and values

Returns:

Series or tuple of (index list, values list)

head(rows: int) → Series[IndexT, T]

Return a Series of the first N rows

Parameters:

rows – number of rows

Returns:

Series

abstract property index: list[IndexT]

property index_name: str | tuple | None

isin(compare_list: list[Any]) → list[bool]

Returns a boolean list where each element is whether that element in the column is in the compare_list.

Parameters:

compare_list – list of items to compare to

Returns:

list of booleans

print(index: bool = True, **kwargs: Any) → None

Print the contents of the Series. This method uses the tabulate function from the tabulate package. Use the kwargs to pass along any arguments to the tabulate function.

Parameters:

• index – If True then include the indexes as a column in the output, if False ignore the index

• kwargs – Parameters to pass along to the tabulate function

Returns:

output of the tabulate function

select_index(compare: Any | tuple, result: Literal['boolean'] = 'boolean') → list[bool]

select_index(compare: IndexT | tuple[Any, ...], result: Literal['value']) → list[IndexT]

Finds the elements in the index that match the compare parameter and returns either a list of the values that match, of a boolean list the length of the index with True to each index that matches. If the indexes are tuples then the compare is a tuple where None in any field of the tuple will be treated as “*” and match all values.

Parameters:

• compare – value to compare as a singleton or tuple

• result – ‘boolean’ = returns a list of booleans, ‘value’ = returns a list of index values that match

Returns:

list of booleans or values

abstract property sort: bool

tail(rows: int) → Series[IndexT, T]

Return a Series of the last N rows

Parameters:

rows – number of rows

Returns:

Series

to_dict(index: bool = True, ordered: bool = False) → dict[Any, Any] | OrderedDict[Any, Any]

Returns a dict where the keys are the data and index names and the values are list of the data and index.

Parameters:

• index – If True then include the index in the dict with the index_name as the key

• ordered – If True then return an OrderedDict() to preserve the order of the columns in the Series

Returns:

dict or OrderedDict()

validate_integrity() → None

Validate the integrity of the Series. This checks that the indexes, column names and internal data are not corrupted. Will raise an error if there is a problem.

Returns:

nothing

class raccoon.series.ViewSeries(data: Sequence[T] | None = None, index: Sequence[IndexT] | None = None, data_name: str | tuple | None = 'value', index_name: str | tuple | None = 'index', sort: bool = False, offset: int = 0)

Bases: SeriesBase, Generic

ViewSeries class. The raccoon ViewSeries implements a view only version of the Series object with the key objective difference that the raccoon ViewSeries is meant for view only use cases where the underlying index and data are modified elsewhere or static. Use this for a view into a single column of a DataFrame. There is no type checking of the data, so it is assumed the data type is list-style.

Parameters:

• data – (optional) sequence of values.

• index – (optional) list of index values. If None then the index will be integers starting with zero

• data_name – (optional) name of the data column, or will default to ‘value’

• index_name – (optional) name for the index. Default is “index”

• sort – if True then assumes the index is sorted for faster set/get operations

• offset – integer to add to location to transform to standard python list location index

property data: Sequence[T]

property data_name: str | tuple | None

equality(indexes: list[IndexT] | list[bool] | None = None, value: Any = None) → list[bool]

Math helper method. Given a column and optional indexes will return a list of booleans on the equality of the value for that index in the DataFrame to the value parameter.

Parameters:

• indexes – list of index values or list of booleans. If a list of booleans then the list must be the same length as the DataFrame

• value – value to compare

Returns:

list of booleans

classmethod from_dataframe(dataframe: DataFrame[IndexT, Any], column: str | tuple | None, offset: int = 0) → Self

Creates and return a Series from a DataFrame and specific column

Parameters:

• dataframe – raccoon DataFrame

• column – column name

• offset – offset value must be provided as there is no equivalent for a DataFrame

Returns:

Series

classmethod from_series(series: Series[IndexT, T], offset: int = 0) → Self

Creates and return a Series from a Series

Parameters:

• series – raccoon Series

• offset – offset value must be provided as there is no equivalent for a DataFrame

Returns:

Series

get(indexes: Any | list[Any] | list[bool], as_list: bool = False) → Series[IndexT, T] | list[T] | T

Given indexes will return a sub-set of the Series. This method will direct to the specific methods based on what types are passed in for the indexes. The type of the return is determined by the types of the parameters.

Parameters:

• indexes – index value, list of index values, or a list of booleans.

• as_list – if True then return the values as a list, if False return a Series.

Returns:

either Series, list, or single value. The return is a shallow copy

get_cell(index: IndexT) → T

For a single index and return the value

Parameters:

index – index value

Returns:

value

get_location(location: int) → dict[Any, IndexT | T]

For an index location return a dict of the index and value. This is optimized for speed because it does not need to look up the index location with a search. Also, can accept relative indexing from the end of the SEries in standard python notation [-3, -2, -1]

Parameters:

location – index location in standard python form of positive or negative number

Returns:

dictionary

get_locations(locations: list[int], as_list: bool = False) → Series[IndexT, T] | list[T]

For list of locations return a Series or list of the values.

Parameters:

• locations – list of index locations

• as_list – True to return a list of values

Returns:

Series or list

get_rows(indexes: list[Any] | list[bool], as_list: bool = False) → Series[IndexT, T] | list[T]

For a list of indexes return the values of the indexes in that column.

Parameters:

• indexes – either a list of index values or a list of booleans with same length as all indexes

• as_list – if True return a list, if False return Series

Returns:

Series if as_list if False, a list if as_list is True

get_slice(start_index: Any = None, stop_index: Any = None, as_list: bool = False) → Series[IndexT, T] | tuple[list[IndexT], list[T]]

For sorted Series will return either a Series or list of all the rows where the index is greater than or equal to the start_index if provided and less than or equal to the stop_index if provided. If either the start or stop index is None then will include from the first or last element, similar to standard python slide of [:5] or [:5]. Both end points are considered inclusive.

Parameters:

• start_index – lowest index value to include, or None to start from the first row

• stop_index – highest index value to include, or None to end at the last row

• as_list – if True then return a list of the indexes and values

Returns:

Series or tuple of (index list, values list)

head(rows: int) → Series[IndexT, T]

Return a Series of the first N rows

Parameters:

rows – number of rows

Returns:

Series

property index: list[IndexT]

property index_name: str | tuple | None

isin(compare_list: list[Any]) → list[bool]

Returns a boolean list where each element is whether that element in the column is in the compare_list.

Parameters:

compare_list – list of items to compare to

Returns:

list of booleans

property offset: int

print(index: bool = True, **kwargs: Any) → None

Print the contents of the Series. This method uses the tabulate function from the tabulate package. Use the kwargs to pass along any arguments to the tabulate function.

Parameters:

• index – If True then include the indexes as a column in the output, if False ignore the index

• kwargs – Parameters to pass along to the tabulate function

Returns:

output of the tabulate function

select_index(compare: IndexT | tuple[Any, ...], result: Literal['boolean', 'value'] = 'boolean') → list[bool] | list[IndexT]

Finds the elements in the index that match the compare parameter and returns either a list of the values that match, of a boolean list the length of the index with True to each index that matches. If the indexes are tuples then the compare is a tuple where None in any field of the tuple will be treated as “*” and match all values.

Parameters:

• compare – value to compare as a singleton or tuple

• result – ‘boolean’ = returns a list of booleans, ‘value’ = returns a list of index values that match

Returns:

list of booleans or values

property sort: bool

tail(rows: int) → Series[IndexT, T]

Return a Series of the last N rows

Parameters:

rows – number of rows

Returns:

Series

to_dict(index: bool = True, ordered: bool = False) → dict[Any, Any] | OrderedDict[Any, Any]

Returns a dict where the keys are the data and index names and the values are list of the data and index.

Parameters:

• index – If True then include the index in the dict with the index_name as the key

• ordered – If True then return an OrderedDict() to preserve the order of the columns in the Series

Returns:

dict or OrderedDict()

validate_integrity() → None

Validate the integrity of the Series. This checks that the indexes, column names and internal data are not corrupted. Will raise an error if there is a problem.

Returns:

nothing

value(indexes: int, int_as_index: bool = False) → T

value(indexes: slice, int_as_index: bool = False) → list[T]

value(indexes: list[int] | list[IndexT] | list[bool], int_as_index: bool = False) → list[T]

value(indexes: object, int_as_index: bool = False) → T

Wrapper function for get. It will return a list, no index. If the indexes are integers it will be assumed that they are locations unless int_as_index = True. If the indexes are locations then they will be rotated to the left by offset number of locations.

Parameters:

• indexes – integer location, single index, list of indexes or list of boolean

• int_as_index – if True then will treat int index values as indexes and not locations

Returns:

value or list of values