Workspace

class pyhf.workspace.Workspace(spec, validate: bool = True, **config_kwargs)

Bases: pyhf.mixins._ChannelSummaryMixin, dict

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

__init__(spec, validate: bool = True, **config_kwargs)

Workspaces hold the model, data and measurements.

Parameters:

• spec (jsonable) – The HistFactory JSON specification

• validate (bool) – Whether to validate against a JSON schema

• config_kwargs – Possible keyword arguments for the workspace configuration

Returns:

The Workspace instance

Return type:

model (Workspace)

Attributes

channel_nbins

Dictionary mapping channel name to number of bins in the channel.

channel_slices

Dictionary mapping channel name to the bin slices in the model.

channels

Ordered list of channel names in the model.

modifiers

Ordered list of pairs of modifier name/type in the model.

samples

Ordered list of sample names in the model.

valid_joins: ClassVar[list[str]] = ['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)

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 list of modifiers to prune.

• prune_modifier_types – A list of modifier types to prune.

• prune_samples – A list of samples to prune.

• prune_channels – A list of channels to prune.

• prune_measurements – 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', validate: bool = True)

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

• validate (bool) – Whether to validate against a JSON schema

Returns:

A new workspace object

Return type:

Workspace

classmethod combine(left, right, join='none', merge_channels=False, validate: bool = True)

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.

• validate (bool) – Whether to validate against a JSON schema.

Returns:

A new combined workspace object

Return type:

Workspace

data(model, include_auxdata=True)

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)

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)

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)

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 list of modifiers to prune.

• modifier_types – A list of modifier types to prune.

• samples – A list of samples to prune.

• channels – A list of channels to prune.

• measurements – 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)

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)

Return a new workspace specification that is sorted.

Parameters:

workspace (Workspace) – A workspace to sort

Returns:

A new sorted workspace object

Return type:

Workspace