session Module

Experimental design for handling provenance using W3C PROV.

class indica.session.Session(user_id)

Manages the a particular run of the software.

Has the following uses: - keep information about version of package and dependencies - hold provenance information - track the data read/calculated and operators instantiated - allow that data to be exported and reloaded

TODO: Consider whether some of these behaviours should be spun off into separate classes which are then aggregated into this one.

Parameters

user_id (str) – Something with which to identify the user. Recommend either an email address or an ORCiD ID.

data

All of the data which has been read in or calculated during this session.

Type

Dict[str, DataArray]

equilibria

All of the equilibrium objects which have been created during this session.

Type

Dict[str, Equilibrium]

operators

All of the operators which have been instantiated during this session.

Type

Dict[str, AbstractOperator]

prov

The document containing all of the provenance information for this session.

Type

prov.model.ProvDocument

readers

Type

Dict[str, DataReader]

session

The provenance Activity object representing this session. It should contain information about versions of different libraries being used.

Type

prov.model.ProvActivity

property agent: prov.model.ProvAgent

The agent (person or piece of software) currently in immediate control of execution.

Returntype

prov.model.ProvAgent

classmethod begin(user_id)

Sets up a global session, without bothering with a context manager.

Parameters

user_id (str) – An identifier, such as an email address or ORCiD ID, for the person using the software.

export(filename)

Write all of the data and operators from this session into a file, for reuse later.

Parameters

filename (str) –

new_agent(agent)

A context manager for temporarily adding an agent to the session. This is useful to ensure the agent will be removed even if there is an exception thrown.

Parameters

agent (prov.model.ProvAgent) –

Return type

prov.model.ProvAgent

pop_agent()

Take responsibility back from the Agent that it was most recently delegated to.

The Agent which the responsibility was delegated by will now appear to be in control of execution and will be the one returned by the agent() property.

Returns

The agent that responsibility was taken away from.

Return type

prov.ProvAgent

push_agent(agent)

Delegate responsibility to another agent.

They will appear to be in control of execution now and will be returned by the agent() property.

Parameters

agent (prov.model.ProvAgent) – The new agent to delegate responsibilityt to.

classmethod reload(filename)

Create a session from a saved which was written to filename. Thanks to some Python voodoo, any local variables in __main__ will be recreated.

Parameters

filename (str) –

Return type

indica.session.Session

indica.session.generate_prov(pass_sess=False)

Decorator to be applied to functions generating xarray.DataArray output. It will produce PROV data and attach it as an attribute.

This should only be applied to stateless functions, as the PROV data it generates will not accurately describe anything else.

Parameters

pass_sess (bool) – Indicates whether, if a keyword argument called sess is present, it should be passed to func.

indica.session.get_dependency_data()

A generator for provenance data on dependencies.

indica.session.hash_vals(**kwargs)

Produces an SHA256 hash from the key-value pairs passed as arguments.

Parameters

kwargs (Any) – The data to use for the hash.

Returns

A hexadecimal representation of the hash.

Return type

str

indica.session.package_provenance(doc, package_name)

Returns provenance for the requested package. This provenance will include version information for all dependencies. Returns a tuple of the provenance for the package in general and the specific installation being used here.

Parameters

• doc (prov.model.ProvDocument) –

• package_name (str) –

Return type

Tuple[prov.model.ProvEntity, prov.model.ProvEntity]