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.

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)

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

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
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:

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

  • 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

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

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

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

    By default, the partitioning is done on the key columns of the store modulo the number of available processors, or on the non-numerical columns of the store if it does not have any key columns.

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.

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_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
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
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
Return type

Measure