PyMPX.pympx module - reference

Site objects

An object model which allows Metapraxis Empower sites to be manipulated programatically

class pympx.pympx.Site(site_locator=None, work_directory=None, storage_dimension_index=None, elements_per_storage_dimension=None, number_of_unit_dimensions=None, empower_importer_executable='C:\\Program Files\\Metapraxis\\Empower 9.9\\Empower Importer Console.exe', logging_queue=None, security_storage_path=None, debug=False, machine_locked=False)[source]

Representation of a Metapraxis Empower site.

Attributes

base: Gets the base dimension i.e.
comparison: A synonym for .mode
currency: A synonym for .base
dimensions: A dictionary like object of zero indexed dimensions for the site
importer: Get the Importer object for this site.
indicator: A synonym for .metric
loaders: The named loaders for this site.
metric: Gets the metric dimension i.e.
mode: Gets the mode dimension i.e.
time: Gets the time dimension i.e.
transformation: Gets the transformation dimension i.e.
viewpoints: A dictionary-like object of shortname indexed `Viewpoint`s for this site

Methods

`housekeep`()	Housekeep this site, to reduce the size of data files
`loader`(name[, source, delta, ...])	Create a named loader for this site.

password
site_file
username

__init__(site_locator=None, work_directory=None, storage_dimension_index=None, elements_per_storage_dimension=None, number_of_unit_dimensions=None, empower_importer_executable='C:\\Program Files\\Metapraxis\\Empower 9.9\\Empower Importer Console.exe', logging_queue=None, security_storage_path=None, debug=False, machine_locked=False)[source]

Log on to the site and access Dimensions, Structures and transactional data. If you have never logged on before on the machine you are calling from, you will be prompted for a user name and password. The password will be stored in C:Empower SitesPythonSecurityunder a directory containing the site name

If you have Empower Importer 9.5 RC6 or greater installed you only need to specify site_locator (or site path) Specify the work_directory if you want to, otherwise it will default to C:Empower SitesTemp Work[Site Name]

Parameters

site_locator – Path to the .eks or .beks containing the site, or site locator string for an SQL site
work_directory – a directory for work files used when exporting and importing data into Empower.
storage_dimension_index – If you are using an Empower Importer version before 9.5..855 specify the 0 based index of the storage dimension. This can be found in “Site Details” in Empower. This information is read automatically with later versions of Importer.
elements_per_storage_dimension – If you are using an Empower Importer version before 9.5..855 specify the number of elements in each the storage dimension. This can be found in “Site Details” in Empower. This information is read automatically with later versions of Importer.
number_of_unit_dimensions – If you are using an Empower Importer version before 9.5..855 specify the number of unit dimensions in this empower site. This can be found in “Site Details” in Empower. This information is read automatically with later versions of Importer.
empower_importer_executable – If you wish to interface with Empower using a version of Empower Importer that is not kept in the standard location then set a path to the executable you wish to use here. By default PyMPX will try to find the latest Empower Importer installed on the system.
logging_queue – multiprocessing.Queue used to send log messages to. Log messages are sent to the console by default, but can be redirected to a file listener at the other end of this queue.
security_storage_path – directory for holding encrypted and user locked security credentials. This will default to C:Empower Sites if no path is set.
debug – Boolean, set to true when you want exports and imports performed by Importer written to file rather than being passed around in memory. Useful for debugging probelematic Imports/Exports
machine_locked – Boolean, set to true when you want security to be machine locked, so that a servcie account can run Empower, after the password has been set up and the Key1 key has been given read access

property base: Gets the base dimension i.e. .dimensions[10]

property comparison: A synonym for .mode

property currency: A synonym for .base

property dimensions

A dictionary like object of zero indexed dimensions for the site

>>> #Create a reference the the customer dimension, assuming it is the first dimension in the site `mysite`
>>> customer = mysite.dimensions[0]

housekeep()[source]: Housekeep this site, to reduce the size of data files

property importer: Get the Importer object for this site. See Importer api documentation for how to use the returned Importer object

property indicator: A synonym for .metric

loader(name, source=None, delta=True, identifier_columns=None, empower_period_type=3)[source]: Create a named loader for this site. Loaders need to be named to ensure the bulk load process works correctly

property loaders: The named loaders for this site. A Loader Loaders need to be named to ensure the bulk load process works correctly

property metric: Gets the metric dimension i.e. .dimensions[9]

property mode: Gets the mode dimension i.e. .dimensions[9]

property time: Gets the time dimension i.e. .dimensions[11]

property transformation: Gets the transformation dimension i.e. .dimensions[12]

property viewpoints: A dictionary-like object of shortname indexed `Viewpoint`s for this site

class pympx.pympx.Dimension(site, index)[source]

An Empower Dimension

Manipulate a dimension’s elements, structures and security using this class.

Attributes

element_dataframe
elements: Shortname indexed elements for the dimension
fields: return a the field definitions of the dimension as an ordered dictionary
longname: The Dimension’s Empower longname
structures: Structures for the dimension - by shortname

Methods

`get`(path)	Return a StructureElement within a Dimension by passing in the path as a string
`make_elements_from_dataframe`(dataframe[, ...])	Make new elements from a pandas Dataframe columns should be ['Short Name','Long Name','Description','Group Only','Calculation Status','Calculation','Colour','Measure Element'] followed by field shortnames If shortname is missing it will be generated from the long name All other columns should relate to a field shortname If parent_key_column is set
`make_structure_from_dataframe`(dataframe, ...)	Make a structure from a pandas Dataframe columns should be ['Short Name'] and a parent key column (default 'Parent Short Name').
`synchronise`([reexport, reimport, ...])	Synchronise the Elements in the Dimension with the Empower Site.

__init__(site, index)[source]

property elements

Shortname indexed elements for the dimension

.elements behaves like a dictionary (you can call .values(), .items() and .keys() on it), but when iterated over it yields Elements one after the other.

A single element can be retrieved from .elements by indexing it on its shortname, e.g.: >>> site.dimension[0].elements[‘MYSHORTCO2’]

property fields: return a the field definitions of the dimension as an ordered dictionary

get(path)[source]

Return a StructureElement within a Dimension by passing in the path as a string

Path: A string describing the path to a StructureElement within a Dimension

e.g. >>> site.dimension[0].get(‘SPAM.EGGS/BACON’)

Will return the ‘BACON’ Structure Element from the ‘SPAM’ Structure

property longname: The Dimension’s Empower longname

make_elements_from_dataframe(dataframe, primary_key_columns=['Short Name'], deduplicate='last', longname_shortname_rule=None, subsequent_shortname_rule=None, sync=True, structure_shortname=None, structure_root_element_shortname=None, parent_key_column=None, parent_key_field_name=None, include_parent_key_column_in_element=False)[source]

Make new elements from a pandas Dataframe columns should be [‘Short Name’,’Long Name’,’Description’,’Group Only’,’Calculation Status’,’Calculation’,’Colour’,’Measure Element’] followed by field shortnames If shortname is missing it will be generated from the long name All other columns should relate to a field shortname If parent_key_column is set

Parameters

primary_key_columns – the columns to be used when deciding what is a unique element. Should be a list of field names of the element
deduplicate – remove duplicates based on the primary key name - set to False if you have manually removed duplicates already. Otherwise choose ‘first’ or ‘last’ to create dimension elements from the the first or last instance of the primary_key_field
structure_shortname – Must be set if we want to create a structure from this dataframe simultaneously with creating the elements.
parent_key_column –
parent_key_field_name –
include_parent_key_column_in_element – If set to false the parent_key_column will be only used to create the nominated structure. If set to True, the parent key column will be also saved as a field in the Element

make_structure_from_dataframe(dataframe, structure_shortname, structure_root_element_shortname=None, parent_key_column='Parent Short Name', parent_key_field_name='Short Name', sync=True)[source]

Make a structure from a pandas Dataframe columns should be [‘Short Name’] and a parent key column (default ‘Parent Short Name’). The key field of the parent should be specified - default is ‘Short Name’

Parameters

structure_root_element_shortname – only needs to be set if there are multiple root elements in the structure
parent_key_column – column name (in dataframe) which refers to the parent
parent_key_field_name – the field to be used (in the parent element) when deciding what is a unique element

property structures

Structures for the dimension - by shortname

.structures behaves like a dictionary (you can call .values(), .items() and .keys() on it), but when iterated over it yields Structures one after the other.

A single Structure can be retrieved from .structures by indexing it on its shortname, e.g.: >>> site.dimension[0].structures[‘SPAM’]

synchronise(reexport=True, reimport=False, primary_key_fields=['Short Name'])[source]

Synchronise the Elements in the Dimension with the Empower Site.

New elements will be created in Empower and changed field values will be updated in the Empower Site

class pympx.pympx.Structure(shortname=None, longname=None, dimension_index=None, dimension=None, description=None)[source]

Attributes

descendants: Deprecated, Don’t use this function, To visit all of the descendants, simply use .walk()
description: The Empower description for this Structure.
elements: Deprecated.
hierarchies: Get a dictionary-like object contianing all of the hierarchies (top level StructureElements) in this Structure
longname: The longname for this Structure.
root_elements: Iterate over all of the hierarchies (root level structure elements) in turn.
shortcode: The shortname for this Structure.
shortname: The shortname for this Structure.

Methods

`add_child_element_parent`(child, parent)	Add the child element to have a given parent.
`get_element`(shortname)	Deprecated, Don't use this function, You probably want .get_root_element(), Failing that you may want .get_elements('some_sn')[0].
`get_elements`(shortname)	Get all of the elements in this structure with the given shortname
`get_root_element`(shortname)	Get the root element in this structure with the given shortname
`print_hierarchy`()	Deprecated, Use the python print() function instead.
`set_child_element_parent`(child, parent)	Synonym for add_child_element_parent() This function will be deprecated in a future release of pympx
`synchronise`()	Synchronise this structure with the Empower site.
`walk`()	Step through every element in the structure in turn.
`walk_elements`()	Deprecated, Use .walk() instead.

__init__(shortname=None, longname=None, dimension_index=None, dimension=None, description=None)[source]

add_child_element_parent(child, parent)[source]

Add the child element to have a given parent. This is the one way we can set elements in a structure.

A more common way (and the preferred way) to set a child element would be to use the StructureElement directly using StructureElement.children .

Parameters

child – Child element. StructureElement
parent – Parent element. StructureElement

property descendants: Deprecated, Don’t use this function, To visit all of the descendants, simply use .walk()

property description: The Empower description for this Structure.

property elements: Deprecated. Don’t use this function - use walk() instead

get_element(shortname)[source]: Deprecated, Don’t use this function, You probably want .get_root_element(), Failing that you may want .get_elements(‘some_sn’)[0].

get_elements(shortname)[source]: Get all of the elements in this structure with the given shortname

get_root_element(shortname)[source]: Get the root element in this structure with the given shortname

property hierarchies

Get a dictionary-like object contianing all of the hierarchies (top level StructureElements) in this Structure

E.g. to get the root StructureElement for Structure my_structure, with shortcode ‘SPAM’:

>>> my_structure.hierarchies['SPAM']

property longname: The longname for this Structure.

print_hierarchy()[source]

Deprecated, Use the python print() function instead. Prints out the Structure in text form.

>>> print(site.dimensions[0].structures['SPAM'])
SPAM
+-EGGS
  +-BACON

property root_elements

Iterate over all of the hierarchies (root level structure elements) in turn.

This proprty does not descend into those hierarchies - use .walk() to do that.

Does the same thing as .hierarchies.values()

set_child_element_parent(child, parent)[source]: Synonym for add_child_element_parent() This function will be deprecated in a future release of pympx

property shortcode: The shortname for this Structure. Synonym for .shortname

property shortname: The shortname for this Structure.

synchronise()[source]: Synchronise this structure with the Empower site. Changes made to this structure will be written back to the Empower site that this structure belongs to.

walk()[source]: Step through every element in the structure in turn. Start with the first root element and walk trunk to leaf, and then on to next leaf Yield elements as the walk goes on.

walk_elements()[source]: Deprecated, Use .walk() instead.

class pympx.pympx.StructureElement(parent_structure_element=None, structure=None, element=None, shortname=None, longname=None, physid=None, year=None, month=None, day=None, interval_index=None, is_root=False)[source]

An Element within a Structure.

StructureElement is one of the most powerful PyMPX classes, allowing Structures to be manipulated in multiple ways. Each StructureElement has a .parent and .children which define where it is in the Structure

Attributes

ancestors: Generator which yields every parent up to the root from this element
ancestors_longname_string: A string, similar to .path, of all ancestor StructureElements longnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘
ancestors_string: A string, similar to .path, of all ancestor StructureElements shortnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘.
calculation: The calculation of the Empower Element underpinning this StructureElement.
calculation_status: The calculation_status of the Empower Element underpinning this StructureElement.
children: The children of this
colour: The colour of the Empower Element underpinning this StructureElement.
day: For Time StructureElements only.
depths: return a dictionary of depths (from root) and list of StructureElements at that depth
descendants: return a magic object which allows descendants to be indexed by shortname
description: The description of the Empower Element underpinning this StructureElement
dimension: The Empower Dimension this StructureElement belongs to
element: The Empower Element underpinning this StructureElement
empower_period_number: Applies to time elements only.
fields: A dictionary like object giving access to the underlying element’s fields.
group_only: ‘Group’ if this is a Group Only StructureElement. A GroupOnly element does not have a calculation, and cannot have data associated with it
has_children: If this StructureElement has at least one childStructureElement, then return True, otherwise returns False
interval: For Time StructureElements only.
interval_amount: For Time StructureElements only.
interval_index: For Time StructureElements only.
is_leaf: If this StructureElement has no children it is a ‘leaf element’, so return True, otherwise returns False
leaves: Yield the leaf StructureElements in a ragged hierarchy, below the given shortname
level: return the zero-based depth of this structure from the root
longname: The longname of the Empower Element underpinning this StructureElement
month: For Time StructureElements only.
offset: For Time StructureElements only.
parent: The Parent StructureElement of this StructureElement.
path: Route from the structure to this StructureElement
physid: The physical identity of the underlying Element.
resolution: For Time StructureElements only.
security: The security of the underlying Element.
shallownesses: return a dictionary of shallownesses (from leaf) and list of StructureElements at that depth
shortcode: The shortname of the Empower Element underpinning this StructureElement
shortname: The shortname of the Empower Element underpinning this StructureElement
site: The site this StructureElement belongs to
string_to_root: A string, similar to .path, of all ancestor StructureElements shortnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘.
structure: The Empower Structure that this StructureElemtn belongs to.
year: For Time StructureElements only.

Methods

`abdicate`()	Remove self from a hierarchy and replace self with children in the same spot This is very important for filtering, because we must leave an intact hierarchy when filtering, and successively abdicating elements will allow children to shuffle up
`add_child`(child_structure_element)	Add a child StructureElement to .children.
`apply`(function)	recursively apply a function to the hierarchy
`ascend`([by_depth])	Traverse tree from leaves to trunk (root)
`bushify`([bushify_additional_rule])	Make the tree bushier and less straggly by putting single children in place of their parents
`compare`(other[, shortcode_translations, ...])	Compare this StructureElement to another, essentially doing a diff Also get a list of new, moved and removed elements
`consolidate`()	Create a consolidation calculation, and set the underlying Element's calculation to the sparse sum of the children
`copy`([element_shortname_filter_out_list])	Return a copy of the hierarchy
`cut`()	Remove this structure element from its parent and return it.
`descend`([by_depth])	Traverse tree from trunk (root) to leaves
`diff`(other[, shortcode_translations, ...])	Compare this StructureElement to another, essentially doing a diff If an element is new or has been removed then record this information.
`embellish`(mappings[, element_type_field, ...])	Add new elements in a layer to a StructureElement.
`filter`([filter_rule, shortcode_list, filter_in])	Filter out (or filter in) all elements of the subtree that do not (or do) conform to the filter rule or are not (or are) in the shortcode_list.
`get_elements`(shortname)	Get all of the elements in this hierarchy with the given shortname
`get_leaves`([subtree_shortname, permissive])	Yield the leaf StructureElements in a ragged hierarchy, below the given shortname :param subtree_shortname: Empower Short Name of the Structure Element we want to start yielding items from.
`get_subtree_translation_df`(subtree_shortname)	Starting at self (a root node) return a pandas DataFrame of shortname and physids for translating rollups for the sub-tree specified by the shortname
`get_unique_leaves`([subtree_shortname])	Yield unique leaf DimensionElements in a ragged hierarchy, below the given shortname :param subtree_shortname: Empower Short Name of the Structure Element we want to start yielding items from.
`graft_on`(scion_hierarchy[, ...])	When grafting apple trees together, you graft a scion (twig or branch) onto a rootstock tree.
`print_hierarchy`([prefix_string, counter])	Deprecated, Use the python print() function instead.
`remove_child`(child_structure_element)	Remove a Child StructureElement.
`remove_children`()	Remove all children from this structure element/ Same as .children.clear()
`replace_child`(child_structure_element[, ...])	Replace one of the child structure elements with one or more structure elements in the same spot If there are no replacements, this function will behave in the same way as remove_child - only it will throw a KeyError if the child does not exist :param child_structure_element: Structure element in children to replace - if not found a KeyError will be raised :param replacements: a StructureElement or list of StructureElements to replace
`set_sort_function`(sort_function)	Deprecated - the sort function is no longer used
`set_tree`(relationships[, update])	Set all of the relationships in the tree below this StructureElement.
`slurp_up_field`(fieldname[, optimisation_lookup])	From the leaves of a StructureElement to that StructureElement, copy the value in the children's field to the parent StructureElement's field, if and only if all of the fields on the children match.
`swap_elements`(shortcode_element_dictionary)	Swap out elements in the tree for new ones If self not in the shortcode_element_dictionary, then return a copy of self
`trickle_down_field`(fieldname, value)	Set the value of a field on this StructureElement and all its descendents
`trickle_down_fields`(fieldname, value)	Deprecated.
`update_tree`(relationships)	Add new relationships in the tree below this StructureElement.
`walk`([level, permissive])	Visit every descendant element in a Structure element in turn.
`walk_subtree`(subtree_shortname[, permissive])	Walk a tree starting at self (a root node) returning only the sub-tree specified by the shortname
`walk_with_levels`([level, permissive])	Yield all elements in a structure, beginning with the root.

add_parent
set_parent

__init__(parent_structure_element=None, structure=None, element=None, shortname=None, longname=None, physid=None, year=None, month=None, day=None, interval_index=None, is_root=False)[source]

Create a new StructureElement.

StructureElement is one of the most powerful PyMPX classes, allowing Structures to be manipulated in multiple ways. Each StructureElement has a .parent and .children which define where it is in the Structure

Parameters

parent_structure_element – The StructureElement that is the parent of this StructureElement
structure – The Empower Structure this StructureElement belongs to. Doesn’t need to be set if parent_structure_element has its structure set
element – The Empower Element referred to. An Element can apepar in many StructureElements
shortname – If element is not set, then the shortname of the underlying element. See Element.shortname api documentation for details.
longname – If element is not set, then the longname of the underlying element. See Element.longname api documentation for details.
physid – If element is not set, then the physical ID of the underlying element. See Element.physid api documentation for details.
year – If element is not set, and this has a Time StructureElement, then the year of the underlying element. See Element.year api documentation for details.
month – If element is not set, and this has a Time StructureElement, then the month of the underlying element. See Element.month api documentation for details.
day – If element is not set, and this has a Time StructureElement, then the day of the underlying element. See Element.day api documentation for details.
interval_index – If element is not set, and this has a Time StructureElement, then the interval_index of the underlying element. See Element.interval_index api documentation for details.
is_root – Set this to True if the StructureElement is a root element in the hierarchy. This will automatically get set to False once a parent is set on this Element.

abdicate()[source]: Remove self from a hierarchy and replace self with children in the same spot This is very important for filtering, because we must leave an intact hierarchy when filtering, and successively abdicating elements will allow children to shuffle up

add_child(child_structure_element)[source]

Add a child StructureElement to .children.

Parameters: child_structure_element – StructureElement, Element or shortcode string referring to an element. The child we wish to add to this StructureElement.

property ancestors: Generator which yields every parent up to the root from this element

property ancestors_longname_string: A string, similar to .path, of all ancestor StructureElements longnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘

property ancestors_string: A string, similar to .path, of all ancestor StructureElements shortnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘. Does not include this StructureElement’s shortname

apply(function)[source]: recursively apply a function to the hierarchy

ascend(by_depth=True)[source]

Traverse tree from leaves to trunk (root)

By depth determines if the primary consideration is the depth from the root (by_depth = True) or the shallowness from the leaves

Children always get returned before parents, but if by_depth is True, a leaf next to the root gets returned later, if False a leaf next to the root will be returned earlier

Parameters: by_depth – True if the distance from the root is used to determine ordering, False if distance from the leaf (i.e. shallowness) is used to determine ordering

bushify(bushify_additional_rule=<function StructureElement.<lambda>>)[source]

Make the tree bushier and less straggly by putting single children in place of their parents

Parameters: bushify_additional_rule – Extra rule to apply to decide if a StructureElement is eliminated or not

e.g.

A +-B | +-C | +-D +-E

+-F +-G

becomes…

A +-D +-E

+-F +-G

eliminating the unnecessary total elements B and C

property calculation: The calculation of the Empower Element underpinning this StructureElement.

property calculation_status: The calculation_status of the Empower Element underpinning this StructureElement. Can be one of ‘Real’ or ‘Calculated’ (i.e. virtual).

property children: The children of this

property colour: The colour of the Empower Element underpinning this StructureElement.

compare(other, shortcode_translations=None, reverse_translations=None)[source]

Compare this StructureElement to another, essentially doing a diff Also get a list of new, moved and removed elements

Return a StructureElementComparison object

Parameters

other – StructureElement to compare self to
shortcode_translations – dictionary for translating shortcodes of “other” structure elements to shortcodes of “self” structure elements, so that similar hierarchies can be compared efficiently
reverse_translations – You shouldn’t need to specify this. It exists so that we don’t have to calculate the reverse translation for every _recursive_ call of this function

consolidate()[source]: Create a consolidation calculation, and set the underlying Element’s calculation to the sparse sum of the children

copy(element_shortname_filter_out_list=[])[source]: Return a copy of the hierarchy

cut()[source]: Remove this structure element from its parent and return it. This function is useful when we are about to ‘paste’ the element into another spot

property day: For Time StructureElements only. The day of the underlying Time Element. See Element.day for information

property depths: return a dictionary of depths (from root) and list of StructureElements at that depth

descend(by_depth=True)[source]

Traverse tree from trunk (root) to leaves

By depth determines if the primary consideration is the depth from the root (by_depth = True) or the shallowness from the leaves

Parents always get returned before children, but if by_depth is True, a leaf next to the root gets returned first, if False a leaf next to the root will be returned last

Parameters: by_depth – True if the distance from the root is used to determine ordering, False if distance from the leaf (i.e. shallowness) is used to determine ordering

property descendants: return a magic object which allows descendants to be indexed by shortname

property description: The description of the Empower Element underpinning this StructureElement

diff(other, shortcode_translations=None, reverse_translations=None)[source]

Compare this StructureElement to another, essentially doing a diff If an element is new or has been removed then record this information. If an element is in the same position or has been moved, record the information and then proceed to checking the children Return a StructureElementComparison object

Parameters

other – StructureElement to compare self to
shortcode_translations – dictionary for translating shortcodes of “other” structure elements to shortcodes of “self” structure elements, so that similar hierarchies can be compared efficiently
reverse_translations – You shouldn’t need to specify this. It exists so that we don’t have to calculate the reverse translation for every _recursive_ call of this function

property dimension: The Empower Dimension this StructureElement belongs to

property element: The Empower Element underpinning this StructureElement

embellish(mappings, element_type_field=None, parent_type=None, parent_element_id_fields=[], parent_element_id_mappings=[], child_type=None, child_element_id_fields=[], child_element_id_mappings=[], child_longname_mapping=None)[source]

Add new elements in a layer to a StructureElement. This way StructureElement trees can be built incrementally, rather than setting the relationships at once

Parameters

mappings – A pandas DataFrame or dictionary containing the parent-child mappings
element_type_field – if set, the Dimension field that holds the type of element we wish to include as either parent or child elements. Typically this dimension field is called ‘Type’
parent_type – The value in the type field for parent elements. If set, only elements in the tree with the element_type_field set to parent_field will have children attached to them.
parent_element_id_fields – The dimension Element field(s) that holds the identity of the parents we want to attach to
parent_element_id_mappings – The columns in a pandas.DataFrame or keys in a Dictionary that identify the parent elements, and correspond to the parent_element_id_fields
child_type – The value in the type field for child elements. Elements with this element_type_field set to child_field will be candidates for attaching to the tree. If not found in the relevant dimension, new elements will be created with element_type_field set to this value
child_element_id_fields – The dimension Element field(s) that holds the identity of the children we want to attach
child_element_id_mappings – The columns in a pandas.DataFrame or keys in a Dictionary that identify the child elements, and correspond to the child_element_id_fields
child_longname_mapping – The longname of the child, as found in the mappings DataFrame or Dictionary - used to create new Elements when they do not exist in the relevant Dimension

If parent_type, parent_element_id_fields and parent_element_id_mappings are not set, then children will be attached to all nodes in the tree. This behaviour is most useful when adding the first layer to an ALL or TOTAL node.

>>>

property empower_period_number: Applies to time elements only. A read only property that returns the Empower Period type number (e.g. 3 for a Month)

property fields: A dictionary like object giving access to the underlying element’s fields. See the api documentation for Element.fields

filter(filter_rule=None, shortcode_list=None, filter_in=True)[source]

Filter out (or filter in) all elements of the subtree that do not (or do) conform to the filter rule or are not (or are) in the shortcode_list. filter_in determines whether the elements appearing in the list or conforming to the rule get filtered in or out

The shortcode list is applied first, followed by the filter rule

Parameters

filter_rule – a function that takes a StructureElement and returns True if it is to be kept, False, otherwise
shortcode_list – list of shortcodes to be used to filter the tree, alternative to using a filter rule
filter_in – True if we wish to include shortcodes in the shortcode_list, False if we wish to exclude them from the tree

get_elements(shortname)[source]: Get all of the elements in this hierarchy with the given shortname

get_leaves(subtree_shortname=None, permissive=True)[source]: Yield the leaf StructureElements in a ragged hierarchy, below the given shortname :param subtree_shortname: Empower Short Name of the Structure Element we want to start yielding items from. Defaults to the root of the tree.

get_subtree_translation_df(subtree_shortname, column_prefix=None, field_shortname=None)[source]

Starting at self (a root node) return a pandas DataFrame of shortname and physids for translating rollups for the sub-tree specified by the shortname

The returned DataFrame will have columns [‘Short Name’,’ID’,’level n physid’,…,’level m physid’] where level n is the level of the supplied subtree_shortname parameter For shortnames which are not at the extreme leaves of the tree, the [‘level m’] column plus some higher levels will have physid = -2 Joining the DataFrame that this function returns to transactional data will create a dataframe that can be used as the basis of a standard explode and load We can use ‘Short Name’ or ‘ID’ to do our join

Parameters: subtree_shortname – Empower Short Name of the Structure Element we want to create a flattened translation below
Returns: pandas DataFrame [‘Short Name’,’ID’,’level n physid’,…,’level m physid’]

get_unique_leaves(subtree_shortname=None)[source]: Yield unique leaf DimensionElements in a ragged hierarchy, below the given shortname :param subtree_shortname: Empower Short Name of the Structure Element we want to start yielding items from. Defaults to the root of the tree.

graft_on(scion_hierarchy, element_graft_rule=<function StructureElement.<lambda>>, scion_copied_once_only=False, return_copy=False, trace_element=None)[source]

When grafting apple trees together, you graft a scion (twig or branch) onto a rootstock tree. This function uses that terminology. Create an output hierarchy that takes the rootstock hierarchy and grafts on subtrees from the scion hierarchy. Scion StructureElement nodes are grafted on according to a rule which is passed in as a parameter: element_graft_rule. An example of an appropriate function to pass in, is one that looks at the underlying fields in the DimensionElements of both hierarchies and decides based on the fields whether a subtree is grafted on to the master tree

Parameters

scion_hierarchy – A StructureElement which is the root of the scion hierarchy
element_graft_rule – A function which has 2 parameters - rootstock element, scion element and return True if the scion element belongs under the rootstock element and False otherwise
scion_copied_once_only – Boolean - does the element merge rule only copy single copies of the scion elements? If so we can optimize by marking nodes as fully transcribed from the scion to the output hierarchy, and avoid visiting them again
return_copy – Boolean - don’t graft the scion onto self - rather return a copy of self, with the scion grafted on
trace_element – shortcode or StructureElement. When the grafted tree is coming out with unexpected results you may wish to turn on log tracing for one of the rootstock elements (and its subtree)

property group_only: ‘Group’ if this is a Group Only StructureElement. A GroupOnly element does not have a calculation, and cannot have data associated with it

property has_children: If this StructureElement has at least one childStructureElement, then return True, otherwise returns False

property interval: For Time StructureElements only. The interval of the underlying Time Element. See Element.interval for information

property interval_amount: For Time StructureElements only. The interval_amount of the underlying Time Element. See Element.interval_amount for information

property interval_index: For Time StructureElements only. The interval_index of the underlying Time Element. See Element.interval_index for information

property is_leaf: If this StructureElement has no children it is a ‘leaf element’, so return True, otherwise returns False

property leaves: Yield the leaf StructureElements in a ragged hierarchy, below the given shortname

property level: return the zero-based depth of this structure from the root

property longname: The longname of the Empower Element underpinning this StructureElement

property month: For Time StructureElements only. The month of the underlying Time Element. See Element.month for information

property offset: For Time StructureElements only. The offset of the underlying Time Element. See Element.offset for information

property parent

The Parent StructureElement of this StructureElement.

Will return None if this StructureElement has no parent

property path

Route from the structure to this StructureElement

Returns a string with the Structure shortname, then a dot, followed by Element shortnames down the hierarchy separated by forward slashes. >>> my_structure_element.path() ‘SPAM.BACON/EGGS’

property physid: The physical identity of the underlying Element. See the api documentation for Element.physid for information

print_hierarchy(prefix_string='', counter=None)[source]

Deprecated, Use the python print() function instead. Prints out the StructureElement in text form.

>>> print(site.dimensions[0].structures['SPAM'].hierarchies['EGGS'])
EGGS
+-BACON

remove_child(child_structure_element)[source]: Remove a Child StructureElement. If a shortcode is passed in, remove the final child StructureElement with that shortcode

remove_children()[source]: Remove all children from this structure element/ Same as .children.clear()

replace_child(child_structure_element, replacements=None)[source]: Replace one of the child structure elements with one or more structure elements in the same spot If there are no replacements, this function will behave in the same way as remove_child - only it will throw a KeyError if the child does not exist :param child_structure_element: Structure element in children to replace - if not found a KeyError will be raised :param replacements: a StructureElement or list of StructureElements to replace

property resolution: For Time StructureElements only. The resolution of the underlying Time Element. See Element.resolution for information

property security: The security of the underlying Element. See the api documentation for Element.security for information

set_sort_function(sort_function)[source]: Deprecated - the sort function is no longer used

set_tree(relationships, update=False)[source]

Set all of the relationships in the tree below this StructureElement. Old relationships will get thrown away

Parameters

relationships – a list of parent child tuples, a dictionary of {child:parent} or a dataframe with columns ‘Short Name’ or ‘PhysID’ and ‘Parent Short Name’ or ‘Parent PhysID’
update – if set to True, the structure is updated, otherwise it is replaced (default)

property shallownesses: return a dictionary of shallownesses (from leaf) and list of StructureElements at that depth

property shortcode: The shortname of the Empower Element underpinning this StructureElement

property shortname: The shortname of the Empower Element underpinning this StructureElement

property site: The site this StructureElement belongs to

slurp_up_field(fieldname, optimisation_lookup={})[source]

From the leaves of a StructureElement to that StructureElement, copy the value in the children’s field to the parent StructureElement’s field, if and only if all of the fields on the children match.

Fieldname: The name of the field whos values we want copied up the Structure

property string_to_root: A string, similar to .path, of all ancestor StructureElements shortnames starting at the root ancestor StructureElement and seperated with ‘ -> ‘. Last shortname is this StructureElement’s shortname

property structure: The Empower Structure that this StructureElemtn belongs to. When this is set, all children have their structure set to the same Structure

swap_elements(shortcode_element_dictionary)[source]: Swap out elements in the tree for new ones If self not in the shortcode_element_dictionary, then return a copy of self

trickle_down_field(fieldname, value)[source]

Set the value of a field on this StructureElement and all its descendents

Parameters

fieldname – Name of the Element field that we want to set
value – Value we want to set the element field to

trickle_down_fields(fieldname, value)[source]: Deprecated. Use trickle_down_field() instead

update_tree(relationships)[source]

Add new relationships in the tree below this StructureElement. Children will be moved to new parents. Order will be preserved

Parameters: relationships – a list of parent child tuples, a dictionary of {child:parent} or a dataframe with columns ‘Short Name’ or ‘PhysID’ and ‘Parent Short Name’ or ‘Parent PhysID’

walk(level=None, permissive=True)[source]

Visit every descendant element in a Structure element in turn. The tree is traversed depth-first, with the first child of the first child of the first child being visited before the second child of the first child of the first child is visited

Parameters

level – Deprecated - do not set this
permissive – Deprecated

walk_subtree(subtree_shortname, permissive=True)[source]

Walk a tree starting at self (a root node) returning only the sub-tree specified by the shortname

Parameters

subtree_shortname – Empower Short Name of the Structure Element we want to start yielding items from
permissive – If we know that we have an unambiguous element then do not assert that we are using a root node - this is especially good in get_leaves() when we don’t care

walk_with_levels(level=0, permissive=True)[source]

Yield all elements in a structure, beginning with the root. At the same time yield the level that we are in in the hierarchy.

Parameters

level – Initial level we are counting from. Defaults to 0
permissive – Deprecated

property year: For Time StructureElements only. The year of the underlying Time Element. See Element.year for information

class pympx.pympx.Element(shortname=None, longname=None, description=None, physid=None, group_only=None, calculation_status=None, calculation=None, colour=None, measure=None, fields=None, override_shortname_length_rule=False, dimension=None)[source]

An Empower Element. The Element is as would be found on the [All] Structure in Empower.

Element’s don’t have parents or children - that is what a StructureElement has.

Attributes

calculation: A string containing the Empower ‘Calculation’ for this Element.
calculation_status: The Empower ‘Calculation Status’ for this Element, will be ‘Real’ or ‘Calculated’
colour: The Empower ‘Colour’ of this Element
date: Applies to time elements only.
day
description: The Empower ‘Description’ for this Element
edited: True if this Element has been changed since creation, or since reading it from Empower.
empower_period_number
fields: Returns a dictionary-like object containing the Empower fields (a.k.a.
group_only: The Empower ‘Group Only’ for this Element, will be ‘Group’ or None
interval_index
longname: The Empower’ Long Name’ for this Element
mastered: True if this element has been created in Empower, False otherwise.
measure: The Empower ‘Measure’ for this Element
month
quarter
security: Returns a Security object, which has python sets of users shortnames for .viewers, .modifiers and .data_viewers
shortcode: Synonym of shortname, the Empower shortname for this Element
shortname: The Empower ‘Short Name’ for this Element
synched: True if all of the attributes of this element have been synchronised with Empower.
year

Methods

`copy`()	Create a copy of self, not including the physid or shortname
`merge`(other[, fields_to_merge])	Merge another element into this one

__init__(shortname=None, longname=None, description=None, physid=None, group_only=None, calculation_status=None, calculation=None, colour=None, measure=None, fields=None, override_shortname_length_rule=False, dimension=None)[source]

Create a new Empower Element.

Parameters

shortname – A ten-character (or shorter) string with the shortname for the Element. If this is not set, Empower will create one when this Element is synchronised.
longname – The name of the Element, as will be displayed in dashboards
description – A longer description of the Element, as stored in Empower
physid – the physical identifier of the Empower element - there is no need to set this, as Empower will set it automatically when this Element is synchronised.
group_only – Set to ‘Group’ if this is a group-only Element
calculation_status – ‘Real’ or ‘Calculated’
calculation – The Empower calculation for this element, as a string. This can be None for non-calculated elements
colour – Empower colour of the Element
measure – Empower measure for the Element
fields – A dictionary of fields. Keys must be the field longname as used in Empower.
override_shortname_length_rule – Allows elements to be created in python with shortnames longer than 10 characters. These shortnames will be overwritten by Empower when the elements are synchronised with Empower.
dimension – pympx.Dimension object that this element belongs to

property calculation: A string containing the Empower ‘Calculation’ for this Element. May be None

property calculation_status: The Empower ‘Calculation Status’ for this Element, will be ‘Real’ or ‘Calculated’

property colour: The Empower ‘Colour’ of this Element

copy()[source]: Create a copy of self, not including the physid or shortname

property date: Applies to time elements only. A read only property that returns a date based on year, month, day and interval_type

property description: The Empower ‘Description’ for this Element

property edited: True if this Element has been changed since creation, or since reading it from Empower.

property fields: Returns a dictionary-like object containing the Empower fields (a.k.a. attributes) for this Element. Entries are of the form Long Name:String Value

property group_only: The Empower ‘Group Only’ for this Element, will be ‘Group’ or None

property longname: The Empower’ Long Name’ for this Element

property mastered: True if this element has been created in Empower, False otherwise. See .synched for the synchronisation (i.e. saved) status

property measure: The Empower ‘Measure’ for this Element

merge(other, fields_to_merge=None)[source]: Merge another element into this one

property security: Returns a Security object, which has python sets of users shortnames for .viewers, .modifiers and .data_viewers

property shortcode: Synonym of shortname, the Empower shortname for this Element

property shortname: The Empower ‘Short Name’ for this Element

property synched: True if all of the attributes of this element have been synchronised with Empower. Will be true after reading the Element from Empower, or after synchronisation. Will be False if the Element has been edited, or does not exist in Empower at all.

class pympx.pympx.Viewpoint(shortname, structure_0=None, structure_1=None, structure_2=None, structure_3=None, structure_4=None, structure_5=None, structure_6=None, structure_7=None, structure_8=None, structure_9=None, structure_10=None, structure_11=None, structure_12=None, site=None, longname=None, description=None, physid=None)[source]

An Empower Viewpoint. A viewpoint specifies a subcube of the entire Empower cube. We read and load data from Viewpoints. Viewpoints are a collection of structures, with one structure per dimension.

Methods

load

__init__(shortname, structure_0=None, structure_1=None, structure_2=None, structure_3=None, structure_4=None, structure_5=None, structure_6=None, structure_7=None, structure_8=None, structure_9=None, structure_10=None, structure_11=None, structure_12=None, site=None, longname=None, description=None, physid=None)[source]

class pympx.pympx.ElementSecurity(element, viewers={}, data_viewers={}, modifiers={}, initialise_synched=False, initialise_as_default=True)[source]

Encapsulate Element security, to make viewers, data_viewers and modifiers

Attributes

data_viewers
edited
modifiers
viewers

__init__(element, viewers={}, data_viewers={}, modifiers={}, initialise_synched=False, initialise_as_default=True)[source]

class pympx.pympx.FieldDefinition(longname, shortname=None, description=None)[source]

Definition of a Dimension Field. Belongs to a Dimension, not to an Element

__init__(longname, shortname=None, description=None)[source]

Site and Focus Loader objects

class pympx.pympx.Loader(source=None, site=None, logging_queue=None, delta=True, identifier_columns=None, name='loader_0', safe_load=True, empower_period_type=3, empower_importer_executable='C:\\Program Files\\Metapraxis\\Empower 9.9\\Empower Importer Console.exe')[source]

Transactional data is loaded into Empower Sites - this object loads it

Attributes

site

Methods

explode([dimension_0, dimension_1, ...])

Explode data by the dimension expansions given, and prepare for delta bulk loading

load() does .explode, .shard and .load_shards()

param dimension_0: string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants

shard([files_to_shard])

Shard all of the delta files for all of the subloads to create files ready to be loaded

load_shards
start_sharder

__init__(source=None, site=None, logging_queue=None, delta=True, identifier_columns=None, name='loader_0', safe_load=True, empower_period_type=3, empower_importer_executable='C:\\Program Files\\Metapraxis\\Empower 9.9\\Empower Importer Console.exe')[source]

If delta is set to True, (which is the default) then this loader will perform delta loads

Parameters

source – A pandas Dataframe to be used as the source data
identifier_columns – Columns in the source which are useful in debugging
safe_load – only move Data Files after loading at the last moment - this makes the process perfectly restartable

explode(dimension_0=None, dimension_1=None, dimension_2=None, dimension_3=None, dimension_4=None, dimension_5=None, dimension_6=None, dimension_7=None, mode=None, base=None, time=None, metric=None, value_column=None, subload_name=None, empower_period_type=None, source_dataframe=None, ignore_zero_values=True)[source]

Explode data by the dimension expansions given, and prepare for delta bulk loading

Parameters

dimension_0 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_1 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_2 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_3 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_4 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_5 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_6 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_7 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
mode – string, list, pympx.Element, or pympx.Constant
base – string, pympx.Element, or pympx.Constant
time – string, pympx.Element, or pympx.Constant or datetime
metric – Either a string naming the metric column, or a dictionary of column names to metric shortnames
value_column – When using a metric column containing metric (indicator) shortcode or physids, then put the name of the value column in here. If metrics are in different columns leave this parameter as None
subload_name –
source_dataframe –
ignore_zero_values – Usually we do not wish to load zero values into Empower. This flag prevents the zero values being loaded into Empower

load() does .explode(), .shard() and .load_shards()[source]

Parameters

dimension_0 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_1 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_2 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_3 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_4 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_5 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_6 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
dimension_7 – string, list, pympx.Element, pympx.Constant or pympx.StructureMapper. String represents a column name, a Constant can be either a physid or shortname, a Structure mapper represents a hierarchy tree. List can be either a list of strings or Constants
mode – string, list, pympx.Element, or pympx.Constant
base – string, list, pympx.Element, or pympx.Constant
time – string, list, pympx.Element, or pympx.Constant
metric – Either a string naming the metric column which should contain metric shortnames or physids, or a dictionary of column names to metric shortnames
value – When using a metric column containing metric (indicator) shortcode or physids, then put the values in here. If metrics are in different columns leave this parameter as None
ignore_zero_values – Usually we do not wish to load zero values into Empower in order to save time and space, since most Empower cube implementations display N/As as zero anyway

load_shards(subloads=None)[source]

shard(files_to_shard=None)[source]: Shard all of the delta files for all of the subloads to create files ready to be loaded

class pympx.pympx.FocusLoader(source=None, target=None, mappings=None, safe_load=True, identifier_columns=None, ignore_zero_values=True, clear_focus_before_loading=True, _defer_mapper_creation=False)[source]

Loads transactions into an Empower focus

Attributes

mappings
site
target

Methods

`delete_target_data`()	BlockSet the Focus to N/A.
`explode`([dimension_0, dimension_1, ...])	Explode data by the dimension expansions given, and prepare for delta bulk loading
`load`() does .delete_target_data, .explode, ...)
`shard`([files_to_shard])	Shard all of the delta files for all of the subloads to create files ready to be loaded

load_shards
start_sharder

__init__(source=None, target=None, mappings=None, safe_load=True, identifier_columns=None, ignore_zero_values=True, clear_focus_before_loading=True, _defer_mapper_creation=False)[source]

Create a new FocusLoader

Parameters

source –
target –
mappings –
safe_load –
identifier_columns –
ignore_zero_values – Don’t load Zero values into the cube - leave N/As in place
clear_focus_before_loading –

delete_target_data()[source]: BlockSet the Focus to N/A. This is a mighty powerful command, to be used with caution

load() does .delete_target_data(), .explode(), .shard() and .load_shards()[source]

class pympx.pympx.CubeMapper(mappings=None, target=None, source=None)[source]

Class which maps a table (pandas DataFrame) to a Focus Contains the logic for turning dictionaries into more complex mapping objects which are Empower structure aware, and for inferring mapping information

Attributes

columns
effective_comparison_elements
effective_currency_elements
effective_dim0_elements
effective_dim1_elements
effective_dim2_elements
effective_dim3_elements
effective_dim4_elements
effective_dim5_elements
effective_dim6_elements
effective_dim7_elements
effective_indicator_elements
effective_time_elements
effective_transform_elements: Get the effective Structure Elements from the Transform dimension
site
source
target

Methods

effective_dimension_elements
effective_unit_dimension_elements

__init__(mappings=None, target=None, source=None)[source]

property effective_transform_elements: Get the effective Structure Elements from the Transform dimension We just want the first ‘Raw’ element in the Viewpoint - we don’t care how many hierarchies the viewpoint has - since all Raw elements are utterly equivalent

Mappers for Site Loader objects

When loading transactional data into Empower using a Loader the following classes are used to map the hierarchies being loaded.

class pympx.pympx.Constant(constant=None)[source]

Object for for use with `Loader`s, designed to add a column to a pandas DataFrame containing a single physical identifier for the single Empower Element we want to load against.

Methods

map_dataframe(dataframe, dimension, loader)

Transform a pandas DataFrame, adding in a column containing an Empower Element physid (physical identifier) that can be used in an Empower bulk load process.

__init__(constant=None)[source]

Object for use with `Loader`s,for easily adding the physical identifier of a constant element to the dataframe

Parameters: constant – A string containing the shortcode of the Empower Element we want to load against

map_dataframe(dataframe, dimension, loader)[source]

Transform a pandas DataFrame, adding in a column containing an Empower Element physid (physical identifier) that can be used in an Empower bulk load process.

Returns a list of the names of the columns that have been created by the mapping process.

Parameters

dataframe – The pandas dataframe being transformed.
dimension – Dimension being mapped. Since we only know the shortname being mapped we need the dimension to translate the string value
loader – Deprecated

class pympx.pympx.ColumnMapper(column_name, column_type, field_shortname)[source]

Utility object for for use with `Loader`s, designed to map columns in a pandas DataFrame to the physical identifiers of the Empower Elements we want to load against.

Methods

map_dataframe(dataframe, dimension, loader)

Transform a pandas DataFrame, adding in a column containing Empower Element physids (physical identifiers) that can be used in an Empower bulk load process.

__init__(column_name, column_type, field_shortname)[source]

Create a new ColumnMapper, a Utility object for for use with `Loader`s, designed to map columns in a pandas DataFrame to the physical identifiers of the Empower Elements we want to load against.

Maps a DataFrame column holding either, shortname, longname or field value for leaf level translation

Parameters

column_name – The name of the column in the pandas DataFrame
column_type – one of ‘physid’, ‘shortname’, ‘longname’ or ‘field’
field_shortname – When this is set, the values in the column will be translated from the field in the dimension with that shortname. Use with column_type = ‘field’

map_dataframe(dataframe, dimension, loader)[source]

Transform a pandas DataFrame, adding in a column containing Empower Element physids (physical identifiers) that can be used in an Empower bulk load process.

Returns a list of the names of the columns that have been created by the mapping process.

Parameters

dataframe – The pandas dataframe being transformed.
dimension – Dimension being mapped. Since we only know the shortname, longname or field being mapped we need the dimension to translate the string values
loader – Deprecated

class pympx.pympx.StructureMapper(shortname_column=None, subtree=None, longname_column=None, field_shortname=None, field_column=None, path=None)[source]

Object for use with `Loader`s,for easily mapping and aggregating up structures

Methods

map_dataframe(dataframe, dimension, loader)

Transform a pandas DataFrame, adding in a column containing Empower Element physids (physical identifiers) that can be used in an Empower bulk load process.

__init__(shortname_column=None, subtree=None, longname_column=None, field_shortname=None, field_column=None, path=None)[source]

Object for use with `Loader`s,for easily mapping and aggregating up structures A column will be added for each level of hierarchy from the leaf to the StructureElement specified in the constructor (i.e. the __init__ method)

Maps a DataFrame column holding either, shortname, longname or field value for leaf level translation Only one of shortname_column, longname_column or a combination of field_column and field_shortname needs to be supplied

Parameters

shortname_column – The column (series) in the pandas DataFrame that will be mapped which holds the leaf shortname
longname_column – The column (series) in the pandas DataFrame that will be mapped which holds the leaf longname
field_column – The column (series) in the pandas DataFrame that will be mapped which holds the leaf field
field_shortname – The shortname of the dimension field holding the translation
subtree – a tuple of (structure shortname, root element shortname,subtree root shortname). Used for exploding data up a structure hierarchy. For backward compatibility only. Use path instead.
path – path to a StructureElement e.g. ‘MyStruct.Hier/Elemn1/Elemen2’ - An alternative to the subtree parameter

map_dataframe(dataframe, dimension, loader)[source]

Transform a pandas DataFrame, adding in a column containing Empower Element physids (physical identifiers) that can be used in an Empower bulk load process. A column will be added for each level of hierarchy from the leaf to the StructureElement specified in the constructor (i.e. the __init__ method)

Returns a list of the names of the columns that have been created by the mapping process.

Parameters

dataframe – The pandas dataframe being transformed.
dimension – Dimension being mapped. Since we only know the shortname, longname or field being mapped we need the dimension to translate the string values
loader – Deprecated