Workspace

class pyhf.workspace.Workspace(spec, **config_kwargs)[source]

Bases: pyhf.mixins._ChannelSummaryMixin, dict

A JSON-serializable object that is built from an object that follows the workspace.json schema.

__init__(spec, **config_kwargs)[source]

Workspaces hold the model, data and measurements.

Attributes

valid_joins = ['none', 'outer', 'left outer', 'right outer']

Methods

_prune_and_rename(prune_modifiers=None, prune_modifier_types=None, prune_samples=None, prune_channels=None, prune_measurements=None, rename_modifiers=None, rename_samples=None, rename_channels=None, rename_measurements=None)[source]

Return a new, pruned, renamed workspace specification. This will not modify the original workspace.

Pruning removes pieces of the workspace whose name or type matches the user-provided lists. The pruned, renamed workspace must also be a valid workspace.

A workspace is composed of many named components, such as channels and samples, as well as types of systematics (e.g. histosys). Components can be removed (pruned away) filtering on name or be renamed according to the provided dict mapping. Additionally, modifiers of specific types can be removed (pruned away).

This function also handles specific peculiarities, such as renaming/removing a channel which needs to rename/remove the corresponding observation.

Parameters
  • prune_modifiers – A str or a list of modifiers to prune.

  • prune_modifier_types – A str or a list of modifier types to prune.

  • prune_samples – A str or a list of samples to prune.

  • prune_channels – A str or a list of channels to prune.

  • prune_measurements – A str or a list of measurements to prune.

  • rename_modifiers – A dict mapping old modifier name to new modifier name.

  • rename_samples – A dict mapping old sample name to new sample name.

  • rename_channels – A dict mapping old channel name to new channel name.

  • rename_measurements – A dict mapping old measurement name to new measurement name.

Returns

A new workspace object with the specified components removed or renamed

Return type

Workspace

Raises

InvalidWorkspaceOperation – An item name to prune or rename does not exist in the workspace.

classmethod build(model, data, name='measurement')[source]

Build a workspace from model and data.

Parameters
  • model (Model) – A model to store into a workspace

  • data (tensor) – A array holding observations to store into a workspace

  • name (str) – The name of the workspace measurement

Returns

A new workspace object

Return type

Workspace

classmethod combine(left, right, join='none', merge_channels=False)[source]

Return a new workspace specification that is the combination of the two workspaces.

The new workspace must also be a valid workspace. A combination of workspaces is done by combining the set of:

  • channels,

  • observations, and

  • measurements

between the two workspaces. If the two workspaces have modifiers that follow the same naming convention, then correlations across the two workspaces may be possible. In particular, the lumi modifier will be fully-correlated.

If the two workspaces have the same measurement (with the same POI), those measurements will get merged.

Raises

InvalidWorkspaceOperation – The workspaces have common channel names, incompatible measurements, or incompatible schema versions.

Parameters
  • left (Workspace) – A workspace

  • right (Workspace) – Another workspace

  • join (str) – How to join the two workspaces. Pick from “none”, “outer”, “left outer”, or “right outer”.

  • merge_channels (bool) – Whether or not to merge channels when performing the combine. This is only done with “outer”, “left outer”, and “right outer” options.

Returns

A new combined workspace object

Return type

Workspace

data(model, include_auxdata=True)[source]

Return the data for the supplied model with or without auxiliary data from the model.

The model is needed as the order of the data depends on the order of the channels in the model.

Raises

KeyError – Invalid or missing channel

Parameters
  • model (Model) – A model object adhering to the schema model.json

  • include_auxdata (bool) – Whether to include auxiliary data from the model or not

Returns

data

Return type

list

get_measurement(measurement_name=None, measurement_index=None)[source]

Get a measurement object.

The following logic is used:

  1. if the measurement name is given, find the measurement for the given name

  2. if the measurement index is given, return the measurement at that index

  3. if there are measurements but none of the above have been specified, return the 0th measurement

Raises

InvalidMeasurement – If the measurement was not found

Parameters
  • measurement_name (str) – The name of the measurement to use

  • measurement_index (int) – The index of the measurement to use

Returns

A measurement object adhering to the schema defs.json#/definitions/measurement

Return type

dict

model(measurement_name=None, measurement_index=None, patches=None, **config_kwargs)[source]

Create a model object with/without patches applied.

See pyhf.workspace.Workspace.get_measurement() and pyhf.pdf.Model for possible keyword arguments.

Parameters
  • measurement_name (str) – The name of the measurement to use in get_measurement().

  • measurement_index (int) – The index of the measurement to use in get_measurement().

  • patches (list of jsonpatch.JsonPatch or pyhf.patchset.Patch) – A list of patches to apply to the model specification.

  • config_kwargs – Possible keyword arguments for the model configuration. See Model for more details.

  • poi_name (str or None) – Specify this keyword argument to override the default parameter of interest specified in the measurement. Set to None for a POI-less model.

Returns

A model object adhering to the schema model.json

Return type

Model

prune(modifiers=None, modifier_types=None, samples=None, channels=None, measurements=None)[source]

Return a new, pruned workspace specification. This will not modify the original workspace.

The pruned workspace must also be a valid workspace.

Parameters
  • modifiers – A str or a list of modifiers to prune.

  • modifier_types – A str or a list of modifier types to prune.

  • samples – A str or a list of samples to prune.

  • channels – A str or a list of channels to prune.

  • measurements – A str or a list of measurements to prune.

Returns

A new workspace object with the specified components removed

Return type

Workspace

Raises

InvalidWorkspaceOperation – An item name to prune does not exist in the workspace.

rename(modifiers=None, samples=None, channels=None, measurements=None)[source]

Return a new workspace specification with certain elements renamed.

This will not modify the original workspace. The renamed workspace must also be a valid workspace.

Parameters
  • modifiers – A dict mapping old modifier name to new modifier name.

  • samples – A dict mapping old sample name to new sample name.

  • channels – A dict mapping old channel name to new channel name.

  • measurements – A dict mapping old measurement name to new measurement name.

Returns

A new workspace object with the specified components renamed

Return type

Workspace

Raises

InvalidWorkspaceOperation – An item name to rename does not exist in the workspace.

classmethod sorted(workspace)[source]

Return a new workspace specification that is sorted.

Parameters

workspace (Workspace) – A workspace to sort

Returns

A new sorted workspace object

Return type

Workspace