Areas¶

class tinyolap.area.Area(cube, args)

An Area represents a subspace of a cube. Areas are intended be used for mass operations on cube cells. The following example should explain the basic concept:

area = cube.area("Jan", "2023", "Plan")
# clears all data for months='Jan', years='2023' and datatype='Plan' over all other dimensions.
area.clear()

# Copies all data from 'Actual', '2022', increases all values by 15% and writes them to the 'Plan' for '2023'.
# Info: All data in the target area will be deleted beforehand.
# Info: Depending on the amount of data to be copied, such operations may take some time (a few seconds).
cube.area("Plan", "2023") = cube.area("Actual", "2022") * 1,15

The smallest possible subspace would be a single cube cell. For such purposes it is recommended to use the Cell object.

addresses(include_cube_name: bool = False, enumerate_data_space: bool = False, include_value: bool = False): Generator to loop over existing addresses of the data area. Returns tuples in the form (dim_member1, … , dim_memberN). :param include_cube_name: Identifies if the name of the cube should be included in the address tuple. :param enumerate_data_space: Identifies if the entire data space, independent of value exists or not should be returned. Caution, the data space can be hugh. :param include_value: Identifies if the actual values of the records should be returned.

alter(*args) → tinyolap.area.Area: Alters the data area, based on the given arguments.

avg(): Returns the average of all existing numeric cells in the data area.

clear(): Clears the data area. All cells holding values will be removed from the cube.

clone() → tinyolap.area.Area: Creates a copy of the data area.

enumerate(include_cube_name: bool = False): Generator to loop over all addresses of the data area. It enumerates the entire space. Returns tuples in the form (dim_member1, … , dim_memberN).

from_dict(area_dict: dict, validate: bool = False) → bool

Reads a data area from a Python dict object, clears the data area and writes (imports) all values contained in the data area definition into the cube.

Parameters

area_dict – A Python dict object containing the data area definition.
validate – If set to True , the data area will be validated before importing. By this you can ensure that all values of the data area can be written to the cube. If at least one value of the data area can not be written to the cube, then from_dict() will stop and return False , otherwise the method will continue and start to write (import) values to the cube.

Returns

Returns True if the import was successful, False otherwise.

from_json(json: str, validate: bool = False) → bool

Reads a data area from a json string, clears the data area and writes (imports) all values contained in the data area definition into the cube.

Parameters

json – A json string containing the data area definition.
validate – If set to True , the data area will be validated before importing. By this you can ensure that all values of the data area can be written to the cube. If at least one value of the data area can not be written to the cube, then from_json() will stop and return False , otherwise the method will continue and start to write (import) values to the cube.

Returns

Returns True if the import was successful, False otherwise.

increment(value: float): Increments all existing cells holding numeric values by a certain value. :type value: The value to increment all cells holding numeric values by.

max(): Returns the maximum value of all existing numeric cells in the data area.

min(): Returns the minimum value of all existing numeric cells in the data area.

multiply(factor: float): Multiplies all existing cells holding numeric values with a certain factor. :type factor: The factor to multiply all cells holding numeric values with.

records(include_cube_name: bool = False, as_list: bool = True): Generator to loop over existing items of the data area. Returns nested tuples in the form ((dim_member1, … , dim_memberN), value).

set_value(value, enumerate_data_space: bool = False): Sets all existing cells of the data area to a specific value. :param enumerate_data_space: Will force the enumerate the entire data space. :param value: The value to be set.

sum(): Returns the sum of all existing numeric cells in the data area.

to_dict(compact: bool = True)

Returns a data area as a Python dict object. For larger data areas it is recommended to set parameter compact to True (the default value). This reduces the memory footprint of the returned dict by factor 2 to 10.

Parameters: compact – Identifies is the data area should be compacted.

to_json(compact: bool = True)

Returns a data area as a json string, including the definition of the area and all base level cell data from that area. For larger data areas it is recommended to set parameter compact to True (the default value). This reduces the size of the returned json string by factor 2 to 10.

The json returned by this method will identical to calling json.dumps(area.to_dict()) .

This function is intended to be used for custom persistence. If you just want to temporarily keep data (e.g. to undo certain changes), in memory, then consider to use method to_dict() for better performance instead.

Parameters: compact – Identifies is the data area should be compacted.