atoti package¶

Submodules¶

atoti.agg module¶

Aggregation functions.

atoti.agg.count_distinct(column, *, scope=None)¶

Return a measure equal to the distinct count aggregation of the passed measure.

It represents the number of distinct values among the aggregated elements.

Parameters

column (Column) – The store column which members are counted.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.long(measure, *, scope=None)¶

Return a measure equal to the sum of the positive values of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.max(measure, *, scope=None)¶

Return a measure equal to the maximum of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.max_member(measure, level)¶

Return a measure equal to the member maximizing the passed measure on the given level.

When multiple members maximize the passed measure, the first one (according to the comparator of the given level) is returned.

Example

Considering this dataset:

Continent	City	Price
Europe	Paris	200.0
Europe	Berlin	150.0
Europe	London	240.0
North America	New York	270.0

And this measure:

m["City with max price"] = atoti.agg.max_member(m["Price"], lvl["Country"])

Then, at the given level, the measure is equal to the current member of the City level:

cube.query(m["Price"], m["City with max price"], levels=lvl["Country"])

City	Price	City with max price
Paris	200.0	Paris
Berlin	150.0	Berlin
London	240.0	London
New York	270.0	New York

At a level above it, the measure is equal to the city of each continent with the maximum price:

cube.query(m["City with min price"], levels=lvl["Continent"])

Continent	City with max price
Europe	London
North America	New York

At the top level, the measure is equal to the city with the maxium price across all continents:

cube.query(m["City with max price"])

City with max Price
New York

Parameters

measure (Measure) – The measure to maximize.
level (Level) – The level on which the maximizing member is searched for.

Return type

Measure

atoti.agg.mean(measure, *, scope=None)¶

Return a measure equal to the mean of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.median(measure, *, scope=None)¶

Return a measure equal to the median of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.min(measure, *, scope=None)¶

Return a measure equal to the minimum of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.min_member(measure, level)¶

Return a measure equal to the member minimizing the passed measure on the given level.

When multiple members maximize the passed measure, the first one (according to the comparator of the given level) is returned.

Example

Considering this dataset:

Continent	City	Price
Europe	Paris	200.0
Europe	Berlin	150.0
Europe	London	240.0
North America	New York	270.0

And this measure:

m["City with min price"] = atoti.agg.min_member(m["Price"], lvl["Country"])

Then, at the given level, the measure is equal to the current member of the City level:

cube.query(m["Price"], m["City with min price"], levels=lvl["Country"])

City	Price	City with min price
Paris	200.0	Paris
Berlin	150.0	Berlin
London	240.0	London
New York	270.0	New York

At a level above it, the measure is equal to the city of each continent with the minimum price:

cube.query(m["City with min price"], levels=lvl["Continent"])

Continent	City with min price
Europe	Berlin
North America	New York

At the top level, the measure is equal to the city with the minium price across all continents:

cube.query(m["City with min price"])

City with min Price
Berlin

Parameters

measure (Measure) – The measure to minimize.
level (Level) – The level on which the minimizing member is searched for.

atoti.agg.prod(measure, *, scope=None)¶

Return a measure equal to the product of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.quantile(measure, q, *, mode='inc', interpolation='linear', scope=None)¶

Return a measure equal to the requested quantile of the passed measure across the specified scope.

Here is how to obtain the same behaviour as these standard quantile calculation methods:

R-1: mode="center" and interpolation="lower"
R-2: mode="center" and interpolation="midpoint"
R-3: mode="simple" and interpolation="nearest"
R-4: mode="simple" and interpolation="linear"
R-5: mode="center" and interpolation="linear"
R-6 (similar to Excel’s PERCENTILE.EXC): mode="exc" and interpolation="linear"
R-7 (similar to Excel’s PERCENTILE.INC): mode="inc" and interpolation="linear"
R-8 and R-9 are not supported

The formulae given for the calculation of the quantile index assume a 1-based indexing system.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to get the quantile of.
q (Union[float, Measure]) – The quantile to take. Must be between 0 and 1. For instance, 0.95 is the 95th percentile and 0.5 is the median.
mode (Literal[‘simple’, ‘centered’, ‘inc’, ‘exc’]) –
The method used to calculate the index of the quantile, available options are, when search for the q quantile of a vector X:
- simple: len(X) * q
- centered: len(X) * q + 0.5
- exc: (len(X) + 1) * q
- inc: (len(X) - 1) * q + 1
interpolation (Literal[‘linear’, ‘higher’, ‘lower’, ‘nearest’, ‘midpoint’]) –
If the quantile index is not an integer, the interpolation decides what value is returned. The different options are, considering a quantile index k with i < k < j for a sorted vector X:
- linear: v = X[i] + (X[j] - X[i]) * (k - i)
- lowest: v = X[i]
- highest: v = X[j]
- nearest: v = X[i] or v = X[j] depending on which of i or j is closest to k
- midpoint: v = (X[i] + X[j]) / 2
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.short(measure, *, scope=None)¶

Return a measure equal to the sum of the negative values of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.single_value(measure, *, scope=None)¶

Return a measure equal to the single value aggregation of the passed measure across the specified scope.

The new measure value is equal to the value of the aggregated elements if they are all equal, and to None otherwise.

Example

Considering this dataset with, for each day and product, the sold amount and the product price:

Date	Product ID	Category	Price	Amount
2020-01-01	001	TV	300.0	5.0
2020-01-02	001	TV	300.0	1.0
2020-01-01	002	Computer	900.0	2.0
2020-01-02	002	Computer	900.0	3.0
2020-01-01	003	TV	500.0	2.0

As the price is constant for a product, single_value can be used to aggregate it:

m["Product Price"] = atoti.agg.single_value(store["Price"])

At the Product ID level, there is a single price so the aggregation forwards it:

cube.query(m["Product Price"], levels=lvl["Product ID"])

Product ID	Product Price
001	300.0
002	900.0
003	500.0

However, at the Category level, it behaves differently:

cube.query(m["Product Price"], levels=lvl["Category"])

Category	Product Price
Computer	900.0
TV

Computer: single price so the measure still forwards it.
TV: two different prices so the measure equals None.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.square_sum(measure, *, scope=None)¶

Return a measure equal to the sum of the square of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.std(measure, *, mode='sample', scope=None)¶

Return a measure equal to the standard deviation of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to get the standard deviation of.
mode (Literal[‘sample’, ‘population’]) –
One of the supported modes:
- The sample standard deviation, similar to Excel’s STDEV.S, is sqrt( sum((Xi - m)²) / (n - 1) ) where m is the sample mean and n the size of the sample. Use this mode if your data represents a sample of the population.
- The population standard deviation, similar to Excel’s STDEV.P is sqrt( sum((Xi - m)²) / n ) where m is the mean of the Xi elements and n the size of the population. Use this mode if your data represents the entire population.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.stop(measure, *at)¶

Return a measure equal to the passed measure at and below the given levels and None above them.

Example

Consider the following measures:

m["stop1"] = tt.agg.stop(m["Quantity"], lvl["Date"])
m["stop2"] = tt.agg.stop(m["Quantity"], lvl["Date"], lvl["Product"])

	Date	Product	Quantity	stop1	stop2
ALL			700
	2020-01-01		400	400
		A	150	150	150
		B	250	250	250
	2020-01-02		300	300
		A	200	200	200
		B	100	100	100

stop1 is only defined when the Date level is defined. stop2 is only defined when both the Date level and the Product level are defined.

Parameters

measure (Measure) – The measure to stop aggregating.
at (Level) – One or more levels to stop at.

Return type

Measure

atoti.agg.sum(measure, *, scope=None)¶

Return a measure equal to the sum of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to aggregate.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.agg.var(measure, *, mode='sample', scope=None)¶

Return a measure equal to the variance of the passed measure across the specified scope.

Parameters

measure (Union[Measure, MeasureConvertible]) – The measure to get the variance of.
mode (Literal[‘sample’, ‘population’]) –
One of the supported modes:
- The sample variance, similar to Excel’s VAR.S, is sum((Xi - m)²) / (n - 1) where m is the sample mean and n the size of the sample. Use this mode if your data represents a sample of the population.
- The population variance, similar to Excel’s VAR.P is sum((Xi - m)²) / n where m is the mean of the Xi elements and n the size of the population. Use this mode if your data represents the entire population.
scope (Optional[Scope]) – The scope of the aggregation. When None is specified, the natural aggregation scope is used: it contains all the data in the cube which coordinates match the ones of the currently evaluated member.

Return type

Measure

atoti.aggregates_cache module¶

Aggregates cache.

class atoti.aggregates_cache.AggregatesCache(_java_api, _cube)¶

Bases: object

The aggregates cache associated with a cube.

property capacity¶

Capacity of the cache.

It is the number of {location: measure} pairs of all the aggregates that can be stored.

A strictly negative value will disable caching.

A zero value will enable sharing but no caching. This means that queries will share their computations if they are executed at the same time, but the aggregated values will not be stored to be retrieved later.

Return type: int

atoti.array module¶

Functions operating on array measures.

atoti.array.len(measure)¶

Return a measure equal to the number of elements of the passed array measure.

Return type: Measure

atoti.array.max(measure)¶

Return a measure equal to the maximum element of the passed array measure.

Return type: Measure

atoti.array.mean(measure)¶

Return a measure equal to the mean of all the elements of the passed array measure.

Return type: Measure

atoti.array.min(measure)¶

Return a measure equal to the minimum element of the passed array measure.

Return type: Measure

atoti.array.n_greatest(measure, n)¶

Return an array measure containing the n greatest elements of the passed array measure.

Return type: Measure

atoti.array.n_lowest(measure, n)¶

Return an array measure containing the n lowest elements of the passed array measure.

Return type: Measure

atoti.array.negative_values(measure)¶

Return a measure where all the elements > 0 of the passed array measure are replaced by 0.

Return type: Measure

atoti.array.nth_greatest(measure, n)¶

Return a measure equal to the n-th greatest element of the passed array measure.

Return type: Measure

atoti.array.nth_lowest(measure, n)¶

Return a measure equal to the n-th lowest element of the passed array measure.

Return type: Measure

atoti.array.positive_values(measure)¶

Return a measure where all the elements < 0 of the passed array measure are replaced by 0.

Return type: Measure

atoti.array.prefix_sum(measure)¶

Return a measure equal to the sum of the previous elements in the passed array measure.

Example

If an array has the following values: [2.0, 1.0, 0.0, 3.0], the returned array will be: [2.0, 3.0, 3.0, 6.0].

Return type: Measure

atoti.array.quantile(measure, q, *, mode='inc', interpolation='linear')¶

Return a measure equal to the requested quantile of the elements of the passed array measure.

Here is how to obtain the same behaviour as these standard quantile calculation methods:

R-1: mode="center" and interpolation="lower"
R-2: mode="center" and interpolation="midpoint"
R-3: mode="simple" and interpolation="nearest"
R-4: mode="simple" and interpolation="linear"
R-5: mode="center" and interpolation="linear"
R-6 (similar to Excel’s PERCENTILE.EXC): mode="exc" and interpolation="linear"
R-7 (similar to Excel’s PERCENTILE.INC): mode="inc" and interpolation="linear"
R-8 and R-9 are not supported

The formulae given for the calculation of the quantile index assume a 1-based indexing system.

Parameters

measure (Measure) – The measure to get the quantile of.
q (Union[float, Measure]) – The quantile to take. Must be between 0 and 1. For instance, 0.95 is the 95th percentile and 0.5 is the median.
mode (Literal[‘simple’, ‘centered’, ‘inc’, ‘exc’]) –
The method used to calculate the index of the quantile, available options are, when search for the q quantile of a vector X:
- simple: len(X) * q
- centered: len(X) * q + 0.5
- exc: (len(X) + 1) * q
- inc: (len(X) - 1) * q + 1
interpolation (Literal[‘linear’, ‘higher’, ‘lower’, ‘nearest’, ‘midpoint’]) –
If the quantile index is not an integer, the interpolation decides what value is returned. The different options are, considering a quantile index k with i < k < j for a sorted vector X:
- linear: v = X[i] + (X[j] - X[i]) * (k - i)
- lowest: v = X[i]
- highest: v = X[j]
- nearest: v = X[i] or v = X[j] depending on which of i or j is closest to k
- midpoint: v = (X[i] + X[j]) / 2

Return type

Measure

atoti.array.sort(measure, *, ascending=True)¶

Return an array measure with the elements of the passed array measure sorted.

Parameters

measure (Measure) – The array measure to sort.
ascending (bool) – When set to False, the first value will be the greatest.

Return type

Measure

atoti.array.std(measure, *, mode='sample')¶

Return a measure equal to the standard deviation of the elements of the passed array measure.

Parameters

measure (Measure) – The measure to get the standard deviation of.
mode (Literal[‘sample’, ‘population’]) –
One of the supported modes:
- The sample standard deviation, similar to Excel’s STDEV.S, is sqrt( sum((Xi - m)²) / (n - 1) ) where m is the sample mean and n the size of the sample. Use this mode if your data represents a sample of the population.
- The population standard deviation, similar to Excel’s STDEV.P is sqrt( sum((Xi - m)²) / n ) where m is the mean of the Xi elements and n the size of the population. Use this mode if your data represents the entire population.

Return type

Measure

atoti.array.sum(measure)¶

Return a measure equal to the sum of all the elements of the passed array measure.

Return type: Measure

atoti.array.var(measure, *, mode='sample')¶

Return a measure equal to the variance of the elements of the passed array measure.

Parameters

measure (Measure) – The measure to get the variance of.
mode (Literal[‘sample’, ‘population’]) –
One of the supported modes:
- The sample variance, similar to Excel’s VAR.S, is sum((Xi - m)²) / (n - 1) where m is the sample mean and n the size of the sample. Use this mode if your data represents a sample of the population.
- The population variance, similar to Excel’s VAR.P is sum((Xi - m)²) / n where m is the mean of the Xi elements and n the size of the population. Use this mode if your data represents the entire population.

Return type

Measure

atoti.column module¶

Column of a Store.

class atoti.column.Column(name, data_type, _store)¶

Bases: atoti.measure.MeasureConvertible

Column of a Store.

data_type: AtotiType = None¶

name: str = None¶

atoti.comparator module¶

Level comparators.

class atoti.comparator.Comparator(_name, _first_members)¶

Bases: object

Level comparator.

atoti.comparator.first_members(members)¶

Create a level comparator with the given first members.

Return type: Comparator

atoti.copy_tutorial module¶

Copy the tutorial files when executed as the __main__ module.

atoti.cube module¶

Cube of a Session.

class atoti.cube.Cube(java_api, name, base_store, session)¶

Bases: object

Cube of a Session.

property aggregates_cache¶

Aggregates cache of the cube.

Return type: AggregatesCache

create_parameter_hierarchy(name, members, *, data_type=None, index_measure=None, indices=None, store_name=None)¶

Create an arbitrary single-level static hierarchy with the given members.

It can be used as a parameter hierarchy in advanced analyses.

Parameters

name (str) – The name of hierarchy and its single level.
members (Sequence[Any]) – The members of the hierarchy.
data_type (Optional[AtotiType]) – The type with which the members will be stored. Automatically inferred by default.
index_measure (Optional[str]) – The name of the indexing measure to create for this hierarchy, if any.
indices (Optional[Sequence[int]]) – The custom indices for each member in the new hierarchy. They are used when accessing a member through the index_measure. Defaults to range(len(members)).
store_name (Optional[str]) – The name of the store backing the parameter hierarchy. Defaults to the passed name argument.

explain_query(*measures, levels=None, condition=None, scenario='Base', timeout=30)¶

Run the query but return an explanation of the query instead of the result.

The explanation contains a summary, global timings and the query plan with all the retrievals.

Parameters

measures (NamedMeasure) – The measures to query. If none are specified, all the measures are returned.
levels (Union[Level, Sequence[Level], None]) – The levels to split on. If none are specified, the value of the measures at the top level is returned.
condition (Union[LevelCondition, MultiCondition, None]) –
The filtering condition. Only conditions on level equality with a string are supported. For instance:
- lvl["Country"] == "France"
- (lvl["Country"] == "USA") & (lvl["Currency"] == "USD")
scenario (str) – The scenario to query.
timeout (int) – The query timeout in seconds.

Return type

QueryAnalysis

Returns

The query explanation.

property hierarchies¶

Hierarchies of the cube.

Return type: Hierarchies

property levels¶

Levels of the cube.

Return type: Levels

property measures¶

Measures of the cube.

Return type: Measures

property name¶

Name of the cube.

Return type: str

query(*measures, levels=None, condition=None, scenario='Base', timeout=30)¶

Query the cube to get the value of some measures.

The value of the measures is given on all the members of the given levels.

Parameters

measures (NamedMeasure) – The measures to query. If none are specified, all the measures are returned.
levels (Union[Level, Sequence[Level], None]) – The levels to split on. If none are specified, the value of the measures at the top level is returned.
condition (Union[LevelCondition, MultiCondition, None]) –
The filtering condition. Only conditions on level equality with a string are supported. For instance:
- lvl["Country"] == "France"
- (lvl["Country"] == "USA") & (lvl["Currency"] == "USD")
scenario (str) – The scenario to query.
timeout (int) – The query timeout in seconds.

Return type

DataFrame

Returns

The resulting DataFrame.

property schema¶

Return the schema of the cube’s stores as an SVG graph.

Note

Graphviz is required to display the graph. It can be installed with Conda: conda install graphviz or by following the download instructions.

Return type: Any
Returns: An SVG image in IPython and a Path to the SVG file otherwise.

setup_simulation(name, *, base_scenario='Base', levels=None, multiply=None, replace=None, add=None)¶

Create a simulation store for the given measures.

Simulations can have as many scenarios as desired.

The same measure cannot be passed in several methods.

Parameters

name (str) – The name of the simulation.
base_scenario (str) – The name of the base scenario.
levels (Optional[Sequence[Level]]) – The levels to simulate on.
multiply (Optional[Collection[Measure]]) – Measures whose values will be multiplied.
replace (Optional[Collection[Measure]]) – Measures whose values will be replaced.
add (Optional[Collection[Measure]]) – Measures whose values will be added (incremented).

Return type

Simulation

Returns

The simulation on which scenarios can be made.

property simulations¶

Simulations of the cube.

Return type: Simulations

visualize(name=None)¶

Display an atoti widget to explore the cube interactively.

This is only supported in JupyterLab and requires the atoti extension to be installed and enabled.

The widget state will be stored in the cell metadata. This state should not have to be edited but, if desired, it can be found in JupyterLab by opening the “Notebook tools” sidebar and expanding the the “Advanced Tools” section.

Parameters: name (Optional[str]) – The name of the widget.

atoti.cubes module¶

Cubes.

class atoti.cubes.Cubes(_java_api, _cubes=<factory>)¶

Bases: collections.abc.MutableMapping, typing.Generic

Manage the cubes of the session.

atoti.exceptions module¶

Custom atoti exceptions.

The custom exceptions are here to disguise the “ugly” stack traces which occur when Py4J raises a Java error. If any other exception is raised by the code inside the custom hook, it is processed normally.

This module is public so the exceptions classes are public and can be documented.

exception atoti.exceptions.AtotiException¶

Bases: Exception

The generic atoti exception class.

All exceptions which inherit from this class will be treated differently when raised. However, this exception is still handled by the default excepthook.

exception atoti.exceptions.AtotiJavaException(message, java_traceback, java_exception)¶

Bases: atoti.exceptions.AtotiException

Exception thrown when Py4J throws a Java exception.

exception atoti.exceptions.AtotiNetworkException¶

Bases: atoti.exceptions.AtotiException

Exception thrown when Py4J throws a network exception.

exception atoti.exceptions.AtotiPy4JException¶

Bases: atoti.exceptions.AtotiException

Exception thrown when Py4J throws a Py4JError.

exception atoti.exceptions.NoCubeStartedException¶

Bases: Exception

Exception thrown when an action requires a cube to be strated but it is not.

atoti.hierarchies module¶

Hierarchies.

class atoti.hierarchies.Hierarchies(_java_api, _cube)¶

Bases: atoti._mappings.DelegateMutableMapping

Manage the hierarchies.

static multiple_hierarchies_error(key, hierarchies)¶

Get the error to raise when multiple hierarchies match the key.

Return type: KeyError

atoti.hierarchy module¶

Hierarchy of a Cube.

class atoti.hierarchy.Hierarchy(_name, _levels, _dimension, _slicing, _cube, _java_api)¶

Bases: object

Hierarchy of a Cube.

property dimension¶

Name of the dimension of the hierarchy.

Return type: str

isin(*member_paths)¶

Return a condition to check that the hierarchy is on one of the given members.

Considering hierarchy_1 containing level_1 and level_2, hierarchy_1.isin((a, x), (b,)) is equivalent to ((level_1 == a) & (level_2 == x)) | (level_1 == b).

Example

Considering a “Geography” hierarchy containing two levels “Country” and “City”, and this measure:

measures["Price in USA/Paris and Germany"] = atoti.filter(
    measures["Price"],
    hierarchies["Geography"].isin(("USA", "Paris"), ("Germany", ))
)

The behavior is the following one:

Country	City	Price	measures[“Price in USA/Paris and Germany”]
France	Paris	200.0
Germany	Berlin	150.0	150.0
UK	London	240.0
USA	New York	270.0
USA	Paris	500.0	500.0

Parameters: members – One or more members expressed as tuples on which the hierarchy should be. Each element in a tuple corresponds to a level of the hierarchy, from the shallowest to the deepest.
Return type: HierarchyIsInCondition

property levels¶

Levels of the hierarchy.

Return type: Mapping[str, Level]

property name¶

Name of the hierarchy.

Return type: str

property slicing¶

Whether the hierarchy is slicing or not.

Return type: bool

atoti.level module¶

Level of a Hierarchy.

class atoti.level.Level(_name, _column_name, _data_type, _hierarchy=None, _comparator=None)¶

Bases: atoti.measure.MeasureConvertible

Level of a Hierarchy.

property comparator¶

Comparator of the level.

Return type: Optional[Comparator]

property data_type¶

Type of the level members.

Return type: str

property dimension¶

Name of the dimension holding the level.

Return type: str

property hierarchy¶

Name of the hierarchy holding the level.

Return type: str

isin(*members)¶

Return a condition to check that the level is on one of the given members.

levels["x"].isin("a", "b") is equivalent to levels["x"] == "a" OR levels["x"] == "b".

Example

Considering this measure:

measures["Price in Paris and London"] = atoti.filter(
    measures["Price"],
    levels["City"].isin("Paris", "London")
)

The behavior is the following one:

City	Price	measures[“Price in Paris and London”]
Paris	200.0	200.0
Berlin	150.0
London	240.0	240.0
New York	270.0

Parameters: members (Any) – One or more members on which the level should be.
Return type: LevelIsInCondition

property name¶

Name of the level.

Return type: str

atoti.levels module¶

Levels.

class atoti.levels.Levels(_hierarchies)¶

Bases: atoti._base_levels.BaseLevels

Flat representation of all the levels in the cube.

atoti.logs module¶

Logs.

class atoti.logs.Logs(lines)¶

Bases: object

Lines of logs.

lines: List[str] = None¶

atoti.measure module¶

Measure of a cube.

class atoti.measure.Measure¶

Bases: abc.ABC

A measure is a mostly-numeric data value, computed on demand for aggregation purposes.

class atoti.measure.MeasureConvertible¶

Bases: abc.ABC

Instances of this class can be converted to measures.

atoti.measures module¶

Measures.

class atoti.measures.Measures(_java_api, _cube)¶

Bases: atoti._mappings.DelegateMutableMapping

Manage the measures.

atoti.sampling module¶

Sampling modes describe how data is loaded into stores.

atoti can handle very large volumes of data while still providing fast answers to queries. However, loading a large amount of data during the modeling phase of the application is rarely a good idea because creating stores, joins, cubes, hierarchies and measures are all operations that take more time when there is more data.

atoti speeds up the sampling process by incoporating an automated sampling mechanism.

For instance datasets can be automatically sampled on their first lines while working on the model and then switched to the full dataset when the project is ready to be shared with other users.

By reducing the amount of data, sampling is a way to have immediate feedback for each cell run in a notebook and keep the modeling phase as snappy as possible.

As a rule of thumb:

sampling is always recommended while building a project.

atoti.session.Session.load_all_data() should be called as late as possible.

atoti.sampling.FULL¶: Load all the data in all the stores.

class atoti.sampling.SamplingMode(name, parameters)¶

Bases: atoti._serialization_utils.FromDict

Mode of source loading.

name: str = None¶

parameters: List[Any] = None¶

atoti.sampling.first_files(limit)¶

Mode to load only the first files of the source.

Parameters: limit (int) – The maximum number of files to read.
Return type: SamplingMode

atoti.sampling.first_lines(limit)¶

Mode to load only the first lines of the source.

Parameters: limit (int) – The maximum number of lines to read.
Return type: SamplingMode

atoti.session module¶

Session.

class atoti.session.Session(name, *, config, **kwargs)¶

Bases: object

Holds a connection to the Java gateway.

close()¶: Close this session and free all the associated resources.

property closed¶

Return whether the session is closed or not.

Return type: bool

create_cube(base_store, name=None, *, mode='auto')¶

Create a cube using based on the passed store.

Parameters

base_store (Store) – The cube’s base store.
name (Optional[str]) – The name of the created cube. Defaults to the name of the base store.
mode (Literal[‘auto’, ‘manual’, ‘no_measures’]) –
The cube creation mode:
- auto: Creates hierarchies for every non-numeric column, and measures for every numeric column.
- manual: Does not create any hierarchy or measure (except from the count).
- no_measures: Creates the hierarchies like auto but does not create any measures.

Return type

Cube

create_scenario(name, *, origin='Base')¶

Create a new source scenario in the datastore.

Parameters

name (str) – The name of the scenario.
origin (str) – The scenario to fork.

create_store(types, store_name, *, keys=None, partitioning=None, sampling_mode=None)¶

Create a store from a schema.

Parameters

types (Mapping[str, AtotiType]) – Types for all columns of the store. This defines the columns which will be expected in any future data loaded into the store.
store_name (str) – The name of the store to create.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.
sampling_mode (Optional[SamplingMode]) – The sampling mode. Defaults to this session’s one.

Return type

Store

property cubes¶

Cubes of the session.

Return type: Cubes

delete_scenario(scenario)¶

Delete the source scenario with the provided name if it exists.

Return type: None

endpoint(route, method)¶

Create a custom endpoint at f"{session.url}/atoti/pyapi/{route}".

The decorated function must take three arguments with types pyapi.user.User , pyapi.http_request.HttpRequest and session.Session and return a response body as a Python data structure that can be converted to JSON. DELETE, POST, and PUT requests can have a body but it must be JSON.

Example:

@session.endpoint("simple_get", "GET")
def callback(request: HttpRequest, user: User, session: Session):
    return "something that will be in response.data"

Parameters

route (str) – The path suffix after /atoti/pyapi/. For instance, if custom/search is passed, a request to /atoti/pyapi/custom/search?query=test#results will match. The route should not contain the query (?) or fragment (#).
method (Literal[‘POST’, ‘GET’, ‘PUT’, ‘DELETE’]) – The HTTP method the request must be using to trigger this endpoint.

Return type

Any

property excel_url¶

URL of the Excel endpoint.

To connect to the session in Excel, create a new connection to an Analysis Services. Use this URL for the server field and choose to connect with “User Name and Password”:

Without authentication, leave these fields blank.
With Basic authentication, fill them with your username and password.
Other authentication types (such as Auth0) are not supported by Excel.

Return type: str

explain_mdx_query(mdx, *, timeout=30)¶

Explain an MDX query.

Parameters

mdx (str) –
The MDX SELECT query to execute. Requirements to guarantee that the DataFrame is well shaped:
- No more than two axes.
- No grand or sub totals.
- Nothing else but measures on the COLUMNS axis.
timeout (int) – The query timeout in seconds.

Return type

QueryAnalysis

export_translations_template(path)¶

Export a template containing all translatable values in the session’s cubes.

Parameters: path (Union[pathlib.Path, str]) – The path at which to write the template.

load_all_data()¶

Trigger the full loading of the data.

Calling this method will change the sampling mode to atoti.sampling.FULL which triggers the loading of all the data. All subsequent loads, including new stores, will not be sampled.

When building a project, this method should be called as late as possible.

property logs_path¶

Path to the session logs file.

Return type: Path

logs_tail(n=20)¶

Return the n last lines of the logs or all the lines if n <= 0.

Return type: Logs

property name¶

Name of the session.

Return type: str

property port¶

Port on which the session is exposed.

Can be set in the session’s configuration.

Return type: int

query_mdx(mdx, *, timeout=30)¶

Execute an MDX query and return its result as a pandas DataFrame.

Parameters

mdx (str) –
The MDX SELECT query to execute. Requirements to guarantee that the DataFrame is well shaped:
- No more than two axes.
- No grand or sub totals.
- Nothing else but measures on the COLUMNS axis.
timeout (int) – The query timeout in seconds.

Return type

DataFrame

read_csv(path, *, keys=None, store_name=None, in_all_scenarios=True, sep=None, encoding='utf-8', process_quotes=None, partitioning=None, types=None, watch=False, array_sep=None, sampling_mode=None)¶

Read a CSV file into a store.

Parameters

path (Union[pathlib.Path, str]) –
The path to the CSV file or directory to load.

If a path pointing to a directory is provided, all of the files with the .csv extension in the directory and subdirectories will be loaded into the same store and, as such, they are all expected to share the same schema

The path can contain glob parameters (e.g. path/to/directory/**.*.csv) and will be expanded correctly. Be carefull, when using glob expressions in paths, all files which match the expression will be loaded, regardless of their extension. When the provided path is a directory, the default glob parameter of **.csv is used.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
store_name (Optional[str]) – The name of the store to create. Defaults to the final component of the given path.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
sep (Optional[str]) – The delimiter to use. If None, the separator will automatically be detected.
encoding (str) – The encoding to use to read the CSV.
encoding – The encoding to use to read the CSV.
process_quotes (Optional[bool]) –
Whether double quotes should be processed to follow the official CSV specification:
- True:
  - Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields.
  - A double quote appearing inside a field must be escaped by preceding it with another double quote.
  - Fields containing line breaks, double quotes, and commas should be enclosed in double-quotes.
- False: all double-quotes within a field will be treated as any regular character, following Excel’s behavior. In this mode, it is expected that fields are not enclosed in double quotes. It is also not possible to have a line break inside a field.
- None: the behavior will be inferred from the first lines of the CSV.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.
types (Optional[Mapping[str, AtotiType]]) – Types for some or all columns of the store. Types for non specified columns will be inferred from the first 1,000 lines.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well. Any non-CSV files added to the directory will be ignored.
array_sep (Optional[str]) – The delimiter to use for arrays. Setting it to a non-None value will parse all the columns containing this separator as arrays.
sampling_mode (Optional[SamplingMode]) – The sampling mode. Defaults to this session’s one.

Return type

Store

Returns

The created store holding the content of the CSV file(s).

read_numpy(array, columns, store_name, *, keys=None, in_all_scenarios=True, partitioning=None, **kwargs)¶

Read a NumPy 2D array into a new store.

Parameters

array (np.ndarray) – The NumPy 2D ndarray to read the data from.
columns (Sequence[str]) – The names to use for the store’s columns. They must be in the same order as the values in the NumPy array.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
store_name (str) – The name of the store to create.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.

Return type

Store

Returns

The created store holding the content of the array.

read_pandas(dataframe, store_name, *, keys=None, in_all_scenarios=True, partitioning=None, types=None, **kwargs)¶

Read a pandas DataFrame into a store.

All the named indices of the DataFrame are included into the store. Multilevel columns are flattened into a single string name.

Parameters

dataframe (DataFrame) – The DataFrame to load.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
store_name (str) – The name of the store to create.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.
types (Optional[Mapping[str, AtotiType]]) – Types for some or all columns of the store. Types for non specified columns will be inferred.

Return type

Store

Returns

The created store holding the content of the DataFrame.

read_parquet(path, *, keys=None, store_name=None, in_all_scenarios=True, partitioning=None, sampling_mode=None, watch=False)¶

Read a Parquet file into a store.

Parameters

path (Union[pathlib.Path, str]) – The path to the Parquet file or directory. If the path points to a directory, all the files in the directory and subdirectories will be loaded into the store and, as such, are expected to have the same schema as the store and to be Parquet files.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
store_name (Optional[str]) – The name of the store to create. Defaults to the final component of the given path.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.
sampling_mode (Optional[SamplingMode]) – The sampling mode. Defaults to this session’s one.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well.

Return type

Store

Returns

The created store holding the content of the Parquet file(s).

read_spark(dataframe, store_name, *, keys=None, in_all_scenarios=True, partitioning=None)¶

Read a Spark DataFrame into a store.

Parameters

dataframe (SparkDataFrame) – The DataFrame to load.
keys (Optional[Sequence[str]]) – The columns that will become keys of the store.
store_name (str) – The name of the store to create.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
partitioning (Optional[str]) –
The description of how the data will be split across partitions of the store.

Default rules:
- Only non-referenced base stores are automatically partitioned.
- Base stores are automatically partitioned by hashing their key fields. If there are no key fields, all the dictionarized fields are hashed.
- Referenced stores can only use a sub-partitionning of the store referencing them.
- Automatic partitioning is done modulo the number of available processors.
For instance, hash4(country) split the data across 4 partitions based on the country column’s hash value.

Only key columns can be used in the partitioning description.

Return type

Store

Returns

The created store holding the content of the DataFrame.

property scenarios¶

Collection of source scenarios of the session.

Return type: Collection[str]

property stores¶

Stores of the session.

Return type: Stores

property url¶

Public URL of the session.

Can be set in the session’s configuration.

Return type: str

wait()¶

Wait for the underlying server subprocess to terminate.

This will prevent the Python process to exit.

Return type: None

atoti.simulation module¶

Simulation and related classes.

class atoti.simulation.Scenario(name, _simulation, _java_api)¶

Bases: object

A scenario for a simulation.

append(*rows)¶

Add one or multiple rows to the scenario.

If a row with the same keys already exist in the scenario, it will be overridden by the passed one.

Parameters

rows (Union[Tuple[Any, …], Mapping[str, Any]]) –

The rows to add. Rows can either be:

Tuples of values in the correct order.
Column name to value mappings.

All rows must share the shame shape.

property columns¶

Columns of the scenario.

Return type: Sequence[str]

property columns_without_priority¶

Columns of the scenario (Priority column excluded).

Return type: Sequence[str]

head(n=5)¶

Return the first n rows of the scenario as a pandas DataFrame.

Return type: DataFrame

load_csv(path, *, sep=', ')¶

Load a CSV into this scenario.

The expected columns are columns or columns_without_priority.

The name of the scenario is automatically added before the row is added to the simulation store.

If the value of a column is left empty (None), then it will be treated as a wildcard value. i.e. it will match all the values of the corresponding column when performing the simulation.

If a value for a column on a given row is None, then it will be treated as a wildcard. i.e it will match all the values of the corresponding column when performing the simulation.

Parameters

path (Union[pathlib.Path, str]) – The path to the CSV file.
sep (Optional[str]) – The CSV separator character. If None, it is inferred by pandas.

load_pandas(dataframe, **kwargs)¶

Load a pandas DataFrame into this scenario.

The expected columns are columns or columns_without_priority.

The name of the scenario is automatically added before the row is added to the simulation store.

If the value of a column is left empty (None), then it will be treated as a wildcard value. i.e. it will match all the values of the corresponding column when performing the simulation.

Parameters: dataframe (DataFrame) – The DataFrame to load.

name: str = None¶

class atoti.simulation.Simulation(_name, _levels, _multiply, _replace, _add, _base_scenario, _cube, _java_api)¶

Bases: object

Represents a simulation.

property columns¶

Columns of the simulation.

Return type: Sequence[str]

property columns_without_priority¶

Columns of the simulation (Priority column excluded).

Return type: Sequence[str]

head(n=5)¶

Return the first n rows of the simulation as a pandas DataFrame.

Return type: DataFrame

property levels¶

Levels of the simulation.

Return type: Sequence[Level]

load_csv(path, *, sep=None, encoding='utf-8', process_quotes=True, watch=False, array_sep=None)¶

Load a CSV into this simulation.

The expected columns are columns or columns_without_priority.

The value provided for simulation_name is the name of the scenario the values will be loaded into.

If the value of a column is left empty (None), then it will be treated as a wildcard value. i.e. it will match all the values of the corresponding column when performing the simulation.

If a value for a specific field is left empty, then it wil be treated as a wildcard value. i.e. it will match all the values of the corresponding column when performing the simulation.

Parameters

path (Union[pathlib.Path, str]) –
The path to the CSV file or directory to load.

If a path pointing to a directory is provided, all of the files with the .csv extension in the directory and subdirectories will be loaded into the same store and, as such, they are all expected to share the same schema

The path can contain glob parameters (e.g. path/to/directory/**.*.csv) and will be expanded correctly. Be carefull, when using glob expressions in paths, all files which match the expression will be loaded, regardless of their extension. When the provided path is a directory, the default glob parameter of **.csv is used.
sep (Optional[str]) – The delimiter to use. If None, the separator will automatically be detected.
encoding (str) – The encoding to use to read the CSV.
encoding – The encoding to use to read the CSV.
process_quotes (bool) –
Whether double quotes should be processed to follow the official CSV specification:
- True:
  - Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields.
  - A double quote appearing inside a field must be escaped by preceding it with another double quote.
  - Fields containing line breaks, double quotes, and commas should be enclosed in double-quotes.
- False: all double-quotes within a field will be treated as any regular character, following Excel’s behavior. In this mode, it is expected that fields are not enclosed in double quotes. It is also not possible to have a line break inside a field.
- None: the behavior will be inferred from the first lines of the CSV.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well. Any non-CSV files added to the directory will be ignored.
array_sep (Optional[str]) – The delimiter to use for arrays. Setting it to a non-None value will parse all the columns containing this separator as arrays.

load_pandas(dataframe, **kwargs)¶

Load a pandas DataFrame into this simulation.

The expected columns are columns or columns_without_priority.

The value provided for simulation_name is the name of the scenario the values will be loaded into.

If the value of a column is left empty (None), then it will be treated as a wildcard value. i.e. it will match all the values of the corresponding column when performing the simulation.

Parameters: dataframe (DataFrame) – The DataFrame to load.

property measure_columns¶

Measure columns of the simulation.

Return type: List[str]

property name¶

Name of the simulation.

Return type: str

property scenarios¶

Scenarios of the simulation.

Return type: SimulationScenarios

class atoti.simulation.SimulationScenarios(_simulation)¶

Bases: collections.abc.MutableMapping, typing.Generic

Manage the scenarios of a simulation.

atoti.simulations module¶

Simulations.

class atoti.simulations.Simulations(_java_api, _simulations=<factory>)¶

Bases: collections.abc.MutableMapping, typing.Generic

Manage the simulations.

atoti.store module¶

Store and related classes.

class atoti.store.Store(_name, _java_api, _scenario='Base', _columns=<factory>)¶

Bases: object

Represents a single store.

append(*rows)¶

Add one or multiple rows to the store.

If a row with the same keys already exist in the store, it will be overridden by the passed one.

Parameters

rows (Union[Tuple[Any, …], Mapping[str, Any]]) –

The rows to add. Rows can either be:

Tuples of values in the correct order.
Column name to value mappings.

All rows must share the shame shape.

property columns¶

Columns of the stores.

Return type: Sequence[str]

head(n=5)¶

Return the first n rows of the store as a pandas DataFrame.

Return type: DataFrame

join(other, *, mapping=None)¶

Define a reference between this store and another.

There are two different possible situations when creating references:

All the key columns of the destination store are mapped: this is a normal reference.
Only some of the key columns of the destination store are mapped: this is a partial reference:
- The columns from the source store used in the mapping must be attached to hierarchies.
- The un-mapped key columns of the destination store will be converted into hierarchies.

Depending on the cube creation mode, the join will also generate different hierarchies and measures:

manual: The un-mapped keys of the destination store will become hierarchies.
no_measures:All of the non-numeric columns from the destination store, as well as those containing integers, will be converted into hierarchies. No measures will be created in this mode.
auto: The same hierarchies will be created as in the no_measures mode. Additionaly, columns containing numeric values, or arrays, except for columns which contain only integers, will be converted into measures.

Parameters

other (Store) – The other store to reference.
mapping (Optional[Mapping[str, str]]) – The column mapping of the reference. Defaults to the columns with the same names in the two stores.

property keys¶

Names of the key columns of the stores.

Return type: Sequence[str]

load_csv(path, *, sep=None, encoding='utf-8', process_quotes=True, in_all_scenarios=False, truncate=False, watch=False, array_sep=None)¶

Load a CSV into this scenario.

Parameters

path (Union[pathlib.Path, str]) –
The path to the CSV file or directory to load.

If a path pointing to a directory is provided, all of the files with the .csv extension in the directory and subdirectories will be loaded into the same store and, as such, they are all expected to share the same schema

The path can contain glob parameters (e.g. path/to/directory/**.*.csv) and will be expanded correctly. Be carefull, when using glob expressions in paths, all files which match the expression will be loaded, regardless of their extension. When the provided path is a directory, the default glob parameter of **.csv is used.
sep (Optional[str]) – The delimiter to use. If None, the separator will automatically be detected.
encoding (str) – The encoding to use to read the CSV.
encoding – The encoding to use to read the CSV.
process_quotes (bool) –
Whether double quotes should be processed to follow the official CSV specification:
- True:
  - Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields.
  - A double quote appearing inside a field must be escaped by preceding it with another double quote.
  - Fields containing line breaks, double quotes, and commas should be enclosed in double-quotes.
- False: all double-quotes within a field will be treated as any regular character, following Excel’s behavior. In this mode, it is expected that fields are not enclosed in double quotes. It is also not possible to have a line break inside a field.
- None: the behavior will be inferred from the first lines of the CSV.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
truncate (bool) – Whether to clear the store before loading the new data into it.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well. Any non-CSV files added to the directory will be ignored.
array_sep (Optional[str]) – The delimiter to use for arrays. Setting it to a non-None value will parse all the columns containing this separator as arrays.

load_kafka(bootstrap_server, topic, *, group_id, batch_duration=1000, consumer_config={}, deserializer=KafkaDeserializer(name='com.activeviam.chouket.loading.kafka.impl.serialization.JsonDeserializer'))¶

Consume a Kafka topic and load its records in the store.

Kafka records’ key deserializer default to StringDeserializer.

Parameters

bootstrap_server (str) – host[:port] that the consumer should contact to bootstrap initial cluster metadata.
topic (str) – Topic to subscribe to.
group_id (str) – The name of the consumer group to join.
batch_duration (int) – Milliseconds spent batching received records before publishing them to the store. If 0, received records are immediately published to the store. Must not be negative.
consumer_config (Mapping[str, str]) – Mapping containing optional parameters to set up the KafkaConsumer. List of available params can be found here.
deserializer (KafkaDeserializer) – Deserialize Kafka records’ value to atoti store rows. Use atoti.kafa.create_deserializer() to create custom ones.

load_pandas(dataframe, *, in_all_scenarios=False, truncate=False, **kwargs)¶

Load a pandas DataFrame into this scenario.

Parameters

dataframe (DataFrame) – The DataFrame to load.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
truncate (bool) – Whether to clear the store before loading the new data into it.

load_parquet(path, *, in_all_scenarios=False, truncate=False, watch=False)¶

Load a Parquet file into this scenario.

Parameters

path (Union[pathlib.Path, str]) – The path to the Parquet file or directory. If the path points to a directory, all the files in the directory and subdirectories will be loaded into the store and, as such, are expected to have the same schema as the store and to be Parquet files.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
truncate (bool) – Whether to clear the store before loading the new data into it.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well.

load_spark(dataframe, *, in_all_scenarios=False, truncate=False)¶

Load a Spark DataFrame into this scenario.

Parameters

dataframe (SparkDataFrame) – The dataframe to load.
in_all_scenarios (bool) – Whether to load the data in all existing scenarios.
truncate (bool) – Whether to clear the store before loading the new data into it.

property name¶

Name of the store.

Return type: str

property scenario¶

Scenario on which the store is.

Return type: NewType()(ScenarioName, str)

property scenarios¶

All the scenarios the store can be on.

Return type: StoreScenarios

property shape¶

Shape of the store.

Return type: Mapping[str, int]

property source_simulation_enabled¶

Whether source simulations are enabled on the store.

Return type: bool

class atoti.store.StoreScenarios(_java_api, _store)¶

Bases: object

Scenarios of a store.

load_csv(scenario_directory_path, *, sep=None, encoding='utf-8', process_quotes=True, truncate=False, watch=False, array_sep=None, pattern=None, base_scenario_directory='Base')¶

Load multiple CSV files into the store while automatically generating scenarios.

Loads the data from a directory into multiple scenarios, creating them as necessary, based on the directory’s structure. The contents of each sub-directory of the provided path will be loaded into a scenario with the same name. Here is an example of a valid directory structure:

ScenarioStore
├── Base
│   └── base_data.csv
├── Scenario1
│   └── scenario1_data.csv
└── Scenario2
│    └── scenario2_data.csv

With this structure:

The contents of the Base directory are loaded into the base scenario.
Two new scenarios are created: Scenario1 and Scenario2, containing respectively the data from scenario1_data.csv and scenario2_data.csv.

Parameters

scenario_directory_path (Union[pathlib.Path, str]) – The path pointing to the directory containing all of the scenarios.
sep (Optional[str]) – The delimiter to use. If None, the separator will automatically be detected.
encoding (str) – The encoding to use to read the CSV.
encoding – The encoding to use to read the CSV.
process_quotes (bool) –
Whether double quotes should be processed to follow the official CSV specification:
- True:
  - Each field may or may not be enclosed in double quotes (however some programs, such as Microsoft Excel, do not use double quotes at all). If fields are not enclosed with double quotes, then double quotes may not appear inside the fields.
  - A double quote appearing inside a field must be escaped by preceding it with another double quote.
  - Fields containing line breaks, double quotes, and commas should be enclosed in double-quotes.
- False: all double-quotes within a field will be treated as any regular character, following Excel’s behavior. In this mode, it is expected that fields are not enclosed in double quotes. It is also not possible to have a line break inside a field.
- None: the behavior will be inferred from the first lines of the CSV.
truncate (bool) – Whether to clear the store before loading the new data into it.
watch (bool) – Whether the source file or directory at the given path should be watched for changes. When set to True, changes to the source will automatically be reflected in the store. If the source is a directory, new files will be loaded into the same store as the initial data and must therefore have the same schema as the initial data as well. Any non-CSV files added to the directory will be ignored.
array_sep (Optional[str]) – The delimiter to use for arrays. Setting it to a non-None value will parse all the columns containing this separator as arrays.
pattern (Optional[str]) – A glob pattern used to specify which files to load in each scenario directory. If no pattern is provided, all files with the .csv extension will be loaded by default.
base_scenario_directory (str) – The data from a scenario directory with this name will be loaded into the base scenario and not a new scenario with the original name of the directory.

atoti.stores module¶

Stores.

class atoti.stores.Stores(java_api, mapping)¶

Bases: atoti._mappings.ImmutableMapping

Manage the stores.

property schema¶

Datastore schema as an SVG graph.

Note

Graphviz is required to display the graph. It can be installed with Conda: conda install graphviz or by following the download instructions.

Return type: Any
Returns: An SVG image in IPython and a Path to the SVG file otherwise.

atoti.types module¶

atoti Types.

class atoti.types.AtotiType(java_type, nullable)¶

Bases: object

atoti Type.

java_type¶: The name of the associated Java literal type.

nullable¶: Whether the objects of this type can be None. Elements within array types cannot be None and must share the same scalar type.

java_type: str = None

nullable: bool = None

atoti.types.local_date(java_format)¶: Create a date type with the given Java date format.

atoti.types.local_date_time(java_format)¶: Create a datetime type with the given Java datetime format.

Module contents¶

atoti’s entrypoint.

atoti.create_session(name='Unnamed', *, config=None, **kwargs)¶

Create a session.

Parameters

name (str) – The name of the session.
config (Union[SessionConfiguration, Path, str, None]) – The configuration of the session or the path to a configuration file.

Return type

Session

atoti.open_query_session(url, name=None, *, auth=None)¶

Open an existing session to query it.

Parameters

url (str) – The server base URL, if {url} is given, {url}/versions/rest is expected to exist.
name (Optional[str]) – The name to give to the session. Defaults to the passed url.
auth (Optional[Callable[[str], Optional[Mapping[str, str]]]]) – The authentication to use.

Return type

QuerySession

Returns

The query session.

atoti.abs(measure)¶

Return a measure equal to the absolute value of the passed measure.

Return type: Measure

atoti.at(measure, coordinates)¶

Return a measure equal to the passed measure at some other coordinates of the cube.

Parameters

measure (Measure) – The measure to take at other coordinates.

coordinates (Mapping[Level, Any]) –

A {level_to shift_on: value_to_shift_to} mapping. Values can either be:

A literal matching an existing member of the key level:

# Return the value of Quantity for France on each member of the Country level.
atoti.at(m["Quantity"], {lvl["Country"]: "France"})

Another level whose current member the key level will be shifted to:

# Return the value of Quantity for the current member
# of the Target Country and Target City levels.
atoti.at(m["Quantity"], {
    lvl["Country"]: lvl["Target Country"],
    lvl["City"]: lvl["Target City"],
})

If this other level is not expressed, the shifting will not be done.

atoti.ceil(measure)¶

Return a measure equal to the smallest integer that is >= to the passed measure.

Return type: Measure

atoti.cos(measure)¶

Return a measure equal to the cosine of the passed measure in radians.

Return type: Measure

atoti.date_diff(from_date, to_date, *, unit='days')¶

Return a measure equal to the difference between two dates.

Parameters

from_date (Union[Measure, date, datetime]) – The first date measure or object.
to_date (Union[Measure, date, datetime]) – The second date measure or object.
unit (Literal[‘seconds’, ‘minutes’, ‘hours’, ‘days’, ‘weeks’, ‘months’, ‘years’]) – The difference unit. Seconds, minutes and hours are only allowed if the dates contain time information.

Return type

Measure

atoti.date_shift(measure, on, offset, *, method='exact')¶

Return a measure equal to the passed mesure shifted to another date.

Parameters

measure (Measure) – The measure to shift.
on (Hierarchy) – The hierarchy to shift on.
offset (str) – The offset of the form xxDxxWxxMxxQxxY to shift by. Only the D, W, M, Q, and Y offset aliases are supported. Offset aliases have the same meaning as Pandas’.

method (Literal[‘exact’, ‘previous’, ‘following’, ‘interpolate’]) –

Determine the value to use when there is no member at the shifted date:

exact: None.
previous: Value at the previous existing date.
following: Value at the following existing date.

interpolate: Linear interpolation of the values at the previous and following existing dates:

Example:
m2 = atoti.date_shift("m1", on=h["date"], offset="1M", method="interpolate")
date

m1

m2

explanation

2000-01-05

15

10.79

linear interpolation of 2000-02-03’s 10 and 2000-03-03’s 21 for 2000-02-05

2000-02-03

10

21

exact match at 2000-03-03: no need to interpolate

2000-03-03

21

9.73

linear interpolation of 2000-03-03’s 21 and 2000-04-05’s 9 for 2000-04-03

2000-04-05

9

∅

no record after 2000-04-05: cannot interpolate

Return type

Measure

atoti.exp(measure)¶

Return a measure equal to the exponential value of the passed measure.

Return type: Measure

atoti.filter(measure, condition)¶

Return a filtered measure.

The new measure is equal to the passed one where the condition is True and to None elsewhere.

Different types of conditions are supported:

Levels compared to levels:
```
lvl["source"] == lvl["destination"]
```
Levels compared to literals:
```
lvl["city"] == "Paris"
```

A conjunction of conditions using the & operator:

(lvl["source"] == lvl["destination"]) & (lvl["city"] == "Paris")

Parameters

measure (Union[date, datetime, int, float, str, Measure, MeasureConvertible]) – The measure to filter.
condition (Union[LevelCondition, MultiCondition, LevelIsInCondition, HierarchyIsInCondition]) – The condition to evaluate.

Return type

Measure

atoti.floor(measure)¶

Return a measure equal to the largest integer <= to the passed measure.

Return type: Measure

atoti.log(measure)¶

Return a measure equal to the natural logarithm (base e) of the passed measure.

Return type: Measure

atoti.log10(measure)¶

Return a measure equal to the base 10 logarithm of the passed measure.

Return type: Measure

atoti.max(*measures)¶

Return a measure equal to the maximum of the passed arguments.

Return type: Measure

atoti.min(*measures)¶

Return a measure equal to the minimum of the passed arguments.

Return type: Measure

atoti.parent_value(measure, on, *, apply_filters=False, degree=1, total_value=None)¶

Return a measure equal to the passed measure at the parent member on the given hierarchy.

Example

Measure definitions:

m1 = parent_value(Quantity.SUM, Date)
m2 = parent_value(Quantity.SUM, Date, degree=3)
m3 = parent_value(Quantity.SUM, Date, degree=3, total_value=Quantity.SUM))
m4 = parent_value(Quantity.SUM, Date, degree=3, total_value=Other.SUM))

Considering a non slicing hierarchy Date with three levels Years, Month and Day:

Year	Month	Day	Quantity.SUM	Other.SUM	m1	m2	m3	m4
2019			75	1000	110	null	110	1500
	7		35	750	75	null	110	1500
		1	15	245	35	110	110	110
		2	20	505	35	110	110	110
	6		40	250	75	null	110	1500
		1	25	115	40	110	110	110
		2	15	135	40	110	110	110
2018			35	500	110	null	110	1500
	7		15	200	35	null	110	1500
		1	5	55	15	110	110	110
		2	10	145	15	110	110	110
	6		20	300	35	null	110	1500
		1	15	145	20	110	110	110
		2	5	155	20	110	110	110

Considering a slicing hierarchy Date with three levels Years, Month and Day:

Year	Month	Day	Quantity.SUM	Other.SUM	m1	m2	m3	m4
2019			75	1000	75	null	75	1000
	7		35	750	75	null	75	1000
		1	15	245	35	75	75	75
		2	20	505	35	75	75	75
	6		40	250	75	null	75	1000
		1	25	115	40	75	75	75
		2	15	135	40	75	75	75
2018			35	500	35	null	35	500
	7		15	200	35	null	35	500
		1	5	55	15	35	35	35
		2	10	145	15	35	35	35
	6		20	300	35	null	35	500
		1	15	145	20	35	35	35
		2	5	155	20	35	35	35

Parameters

measure (Union[Measure, str]) – The measure to take the parent value of.
on (Hierarchy) – The hierarchy to drill up to take the parent value.
apply_filters (bool) – Whether to apply the query filters when computing the value at the parent member.
degree (int) – The number of levels to go up to take the value on. A value of 1 as parent_degree will do a one step drill up in the hierarchy.
total_value (Union[date, datetime, int, float, str, Measure, MeasureConvertible, None]) – The value to take when the drill up went above the top level of the hierarchy.

Return type

Measure

atoti.rank(measure, hierarchy, ascending=True, apply_filters=True)¶

Return a measure equal to the rank of a hierarchy’s members according to a reference measure.

Members with equal values are further ranked using the level comparator.

Example:

m2 = atoti.rank(m1, hierarchy["date"])

Year	Month	Day	m1	m2	Comments
2000			90	1
	01		25	2
		01	15	1
		02	10	2
	02		50	1
		01	30	1	same value as 2000/02/05 but this member comes first
		03	20	3
		05	30	2	same value as 2000/02/01 but this member comes last
	04		15	3
		05	5	2
		05	10	1

Parameters

measure (Measure) – The measure on which the ranking is done.
hierarchy (Hierarchy) – The hierarchy containing the members to rank.
ascending (bool) – When set to False, the 1st place goes to the member with greatest value.
apply_filters (bool) – When True, query filters will be applied before ranking members. When
query filters will be applied after the ranking, resulting in "holes" in the (False,) –
ranks. –

atoti.round(measure)¶

Return a measure equal to the closest integer to the passed measure.

Return type: Measure

atoti.shift(measure, on, *, offset=1)¶

Return a measure equal to the passed measure shifted to another member.

Parameters

measure (Measure) – The measure to shift.
on (Level) – The level to shift on.
offset (int) – The amount of members to shift by.

Return type

Measure

atoti.sin(measure)¶

Return a measure equal to the sine of the passed measure in radians.

Return type: Measure

atoti.sqrt(measure)¶

Return a measure equal to the square root of the passed measure.

Return type: Measure

atoti.tan(measure)¶

Return a measure equal to the tangent of the passed measure in radians.

Return type: Measure

atoti.total(measure, on)¶

Return a measure equal to the measure on the top level member on each hierarchy member.

It ignores the filters on this hierarchy.

If the hierarchy is not slicing, total is equal to the value for all the members. If the hierarchy is slicing, total is equal to the value on the first level.

Example

Considering a hierarchy Date with three levels Year, Month and Day. In the first case Date is not slicing. In the second case Date is slicing.

Year	Month	Day	Price	total(Price) NON SLICING	total(Price) SLICING
2019			75.0	110.0	75.0
	7		35.0	110.0	75.0
		1	15.0	110.0	75.0
		2	20.0	110.0	75.0
	6		40.0	110.0	75.0
		1	25.0	110.0	75.0
		2	15.0	110.0	75.0
2018			35.0	110.0	35.0
	7		15.0	110.0	35.0
		1	5.0	110.0	35.0
		2	10.0	110.0	35.0
	6		20.0	110.0	35.0
		1	15.0	110.0	35.0
		2	5.0	110.0	35.0

Parameters

measure (Measure) – The measure to take the total of.
on (Hierarchy) – The hierarchy on which to find the top-level member.

Return type

Measure

atoti.where(condition, true_measure, false_measure=None)¶

Return a conditional measure.

This function is like an if-then-else statement:

Where the condition is True, the new measure will be equal to true_measure.
Where the condition is False, the new measure will be equal to false_measure.

Different types of conditions are supported:

Measures compared to anything measure-like:
```
m["Test"] == 20
```
Levels compared to levels:
```
lvl["source"] == lvl["destination"]
```
Levels compared to literals:
```
lvl["city"] == "Paris"
```

A conjunction of conditions using the & operator:

(m["Test"] == 20) & (lvl["city"] == "Paris")

Parameters

condition (Union[BooleanMeasure, LevelCondition, MultiCondition, HierarchyIsInCondition, LevelIsInCondition]) – The condition to evaluate.
true_measure (Union[date, datetime, int, float, str, Measure, MeasureConvertible]) – The measure to propagate where the condition is True.
false_measure (Union[date, datetime, int, float, str, Measure, MeasureConvertible, None]) – The measure to propagate where the condition is False.

Return type

Measure

atoti package¶

Subpackages¶

Submodules¶

atoti.agg module¶

atoti.aggregates_cache module¶

atoti.array module¶

atoti.column module¶

atoti.comparator module¶

atoti.copy_tutorial module¶

atoti.cube module¶

atoti.cubes module¶

atoti.exceptions module¶

atoti.hierarchies module¶

atoti.hierarchy module¶

atoti.level module¶

atoti.levels module¶

atoti.logs module¶

atoti.measure module¶

atoti.measures module¶

atoti.sampling module¶

atoti.session module¶

atoti.simulation module¶

atoti.simulations module¶

atoti.store module¶

atoti.stores module¶

atoti.types module¶

Module contents¶