Welcome to the Reaction Plane Fit documentation!

Documentation

Documentation on the modules of the Reaction Plane Fit package are available below. For getting started, take a look at reaction_plane_fit.example.run_fit().

base module

Utility functions for the reaction plane fit.

class reaction_plane_fit.base.FitType(region: str, orientation: str)

Bases: object

Describes the fit parameters of a particular component.

region

Describes the region in which the data for the fit originates. It should be either “signal” or “background” dominated.

orientation

Describe the reaction plane orientation of the data. For data which does not select or orientation, it should be described as “inclusive”. Otherwise, the values are up to the particular implementation. As an example, for three RP orientations, they are known as “in_plane”, “mid_plane”, and “out_of_plane”.

class reaction_plane_fit.base.ReactionPlaneParameter(orientation: str, phiS: float, c: float)

Bases: object

Parameters that defined a reaction plane.

orientation

Reaction plane orientation.

Type:str

phiS

Center of the reaction plane bin.

Type:float

c

Width of the reaction plane bin.

Type:float

reaction_plane_fit.base.component_fit_result_from_rp_fit_result(fit_result: pachyderm.fit.base.FitResult, component: fit.FitComponent) → pachyderm.fit.base.BaseFitResult

Create a component fit result from the fit component and the RP fit result.

Parameters:

• fit_result – Fit result from the RP fit.
• component – Fit component for this fit result.

Returns:

Constructed component fit result.

reaction_plane_fit.base.format_input_data(data: Union[Dict[str, Dict[str, Union[Any, pachyderm.histogram.Histogram1D]]], Dict[FitType, pachyderm.histogram.Histogram1D]]) → Dict[reaction_plane_fit.base.FitType, pachyderm.histogram.Histogram1D]

Convert input data into a more convenient format.

By using FitType, we can very easily check that all fit components have the appropriate data.

Parameters:data – Input data to be formatted. Returns:Properly formatted data, with FitType keys and histograms as values.

functions module

Based functions shared by all fit implementations.

The fit functions (ie all functions defined here except those to determine_...(...) functions) are called repeatedly for each value in an array by iminuit.

reaction_plane_fit.functions.background_wrapper(phi: float, c: float, resolution_parameters: Dict[str, float], background_function: Callable[[...], float]) → Callable[[...], float]

Wrapper around the RPF background function to allow the specification of relevant parameters.

This allows the more standard background function to be used without having to pass these fixed parameters to the function every time.

Parameters:

• phi (float) – Center of the reaction plane bin. Matches up to phi_s in the RPF paper.
• c (float) – Width of the reaction plane bin. Matches up to c in the RPF paper.
• resolution_parameters (dict) – Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82”.
• background_function (Callable) – Background function to be wrapped.

Returns:

Wrapper around the actual background function with the specified parameters.

Return type:

function

reaction_plane_fit.functions.determine_background_fit_function(rp_orientation: str, resolution_parameters: Dict[str, float], reaction_plane_parameter: base.ReactionPlaneParameter, rp_background_function: Callable[[...], float], inclusive_background_function: Callable[[...], float]) → Callable[[...], float]

Determine the background fit function.

For inclusive RP orientations, this is a Fourier series (but may include additional constraints). For other RP orientations, it is an RPF function.

Note

If the RP orientation is inclusive, it is assumed to be labeled as “inclusive”.

Parameters:

• rp_orientation (str) – The reaction plane orientation.
• resolution_parameters (dict) – Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82”. Only used for RPF.
• reaction_plane_parameter (base.ReactionPlaneParameter) – Reaction plane parameters for the selected reaction plane.
• rp_background_function (function) – RP orientation dependent background fit function.
• inclusive_background_function (function) – Inclusive RP orientation background fit function.

Returns:

The background function.

Return type:

function

reaction_plane_fit.functions.determine_signal_dominated_fit_function(rp_orientation: str, resolution_parameters: Dict[str, float], reaction_plane_parameter: base.ReactionPlaneParameter, rp_background_function: Callable[[...], float], inclusive_background_function: Callable[[...], float]) → Callable[[...], float]

Determine the signal fit function.

This function consists of near-side and away side gaussians representing the signal added to a function to describe the background. For inclusive RP orientations, this is a Fourier series, while for other RP orientations, this is a RPF function.

Parameters:

• rp_orientation (str) – The reaction plane orientation.
• resolution_parameters (dict) – Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82”. Only used for RPF.
• reaction_plane_parameter (base.ReactionPlaneParameter) – Reaction plane parameters for the selected reaction plane.
• rp_background_function (function) – RP orientation dependent background fit function.
• inclusive_background_function (function) – Inclusive RP orientation background fit function.

Returns:

The signal fit function.

Return type:

Callable

reaction_plane_fit.functions.fourier(x: float, BG: float, v2_t: float, v2_a: float, v4_t: float, v4_a: float, v1: float, v3: float, **kwargs) → float

Fourier decomposition for use in describing the background.

Note

B was renamed to BG in the args so the argument would be decoupled (ie separate) from the background of the RPF! This is needed because iminuit routes the arguments based on these names.

Parameters:

• BG (float) – Overall multiplicative background level.
• v2_t (float) – Trigger v_{2}.
• v2_a (float) – Associated v_{2}.
• v4_t (float) – Trigger v_{4}.
• v4_a (float) – Associated v_{4}
• v1 (float) – v1 parameter.
• v3 (float) – v3 parameter.
• kwargs (dict) – Used to absorbs extra possible parameters from Minuit (especially when used in conjunction with other functions).

Returns:

Values calculated by the function.

Return type:

float

reaction_plane_fit.functions.signal(x: float, A1: float, A2: float, s1: float, s2: float, pedestal: float) → float

Function for fitting the signal region of the reaction plane fit.

The signal function consists of two gaussian peaks (one at the NS (0.0) and one at the AS (np.pi)), along with a pedestal. Gaussians are normalized and are of the form:

\[1/(\sigma*\sqrt(2*\pi) * e^{-(x-0.0)^{2}/(2*\sigma^{2})}\]

Parameters:

• x (float) – Delta phi value for which the signal will be calculated.
• A1 (float) – Near-side gaussian amplitude.
• A2 (float) – Away-side gaussian amplitude.
• s1 (float) – Near-side gaussian sigma.
• s2 (float) – Away-side gaussian sigma.
• pedestal (float) – Pedestal on which the signal sits.

Returns:

Value calculated by the function.

Return type:

float

reaction_plane_fit.functions.signal_wrapper(x: float, ns_amplitude: float, as_amplitude: float, ns_sigma: float, as_sigma: float, signal_pedestal: float, **kwargs) → float

Wrapper for use with iminuit that basically reassigns descriptive parameter names to shorter names.

These shorter names make the function definition less verbose to look and therefore easier to understand.

Parameters:

• x (float) – Delta phi value for which the signal will be calculated.
• ns_amplitude (float) – Near-side gaussian amplitude.
• as_amplitude (float) – Away-side gaussian amplitude.
• ns_sigma (float) – Near-side gaussian sigma.
• as_sigma (float) – Away-side gaussian sigma.
• signal_pedestal (float) – Pedestal on which the signal sits.
• kwargs (dict) – Used to absorbs extra possible parameters from Minuit (especially when used in conjunction with other functions).

Returns:

Value calculated by the function.

Return type:

float

fit module

Defines the basic components of the reaction plane fit.

class reaction_plane_fit.fit.BackgroundFitComponent(rp_orientation: str, *args, **kwargs)

Bases: reaction_plane_fit.fit.FitComponent

Fit component in the background region.

Parameters:

• rp_orientation (str) – Reaction plane orientation for the component.
• *args (list) – Only use named args.
• **kwargs (dict) – Named arguments to be passed on to the base component.

determine_fit_function(resolution_parameters: Dict[str, float], reaction_plane_parameter: reaction_plane_fit.base.ReactionPlaneParameter) → None

Use the class parameters to determine the fit and background functions and store them.

set_data_limits(hist: pachyderm.histogram.Histogram1D) → pachyderm.histogram.Histogram1D

Set the limits of the fit to only use near-side data (ie dPhi < pi/2)

Only the near-side will be used for the fit to avoid the signal at large dPhi on the away-side.

Parameters:hist (histogram.Histogram1D) – The input data. Returns:The data limited to the near-side. Return type:histogram.Histogram1D

class reaction_plane_fit.fit.FitComponent(fit_type: reaction_plane_fit.base.FitType, resolution_parameters: Dict[str, float], use_log_likelihood: bool = False)

Bases: abc.ABC

A component of the fit.

Parameters:

• fit_type (FitType) – Type (region and orientation) of the fit component.
• resolution_parameters (dict) – Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82”
• use_log_likelihood (bool) – If true, use log likelihood cost function. Often used when statistics are limited. Default: False

fit_type

Overall type of the fit.

Type:FitType

use_log_likelihood

True if the fit should be performed using log likelihood.

Type:bool

fit_function

Function of the component.

Type:function

cost_func

Cost function associated with the fit component.

Type:pachyderm.fit.CostFunctionBase

calculate_background_function_errors(x: numpy.ndarray) → numpy.ndarray

Calculate the background function errors based on values from the fit.

Parameters:x – x values where the errors will be evaluated. Returns:The calculated error values.

calculate_fit_errors(x: numpy.ndarray) → numpy.ndarray

Calculate the fit function errors based on values from the fit.

Parameters:x – x values where the errors will be evaluated. Returns:The calculated error values.

determine_fit_function(resolution_parameters: Dict[str, float], reaction_plane_parameter: reaction_plane_fit.base.ReactionPlaneParameter) → None

Use the class parameters to determine the fit and background functions and store them.

determine_parameters_limits() → Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]

Determine the parameter seed values, limits, step sizes for the component.

Note

These values should be specified with the proper names so that they will be recognized by Minuit. This is the user’s responsibility.

Parameters:None. – Returns:Dictionary of the function arguments which specifies their

evaluate_background(x: numpy.ndarray) → numpy.ndarray

Evaluates the background components of the fit function.

In the case of a background component, this is identical to evaluate_fit(...). However, in the case of a signal component, this describes the background contribution to the signal.

Parameters:x – x values where the fit component will be evaluated. Returns:Background function values at the given x values.

evaluate_fit(x: numpy.ndarray) → numpy.ndarray

Evaluate the fit component.

Parameters:x – x values where the fit component will be evaluated. Returns:Function values at the given x values.

region

rp_orientation

set_data_limits(hist: pachyderm.histogram.Histogram1D) → pachyderm.histogram.Histogram1D

Extract the data from the histogram.

set_fit_type(region: Optional[str] = None, orientation: Optional[str] = None) → None

Update the fit type.

Will use the any of the existing parameters if they are not specified.

Parameters:

• region (str) – Region of the fit type.
• orientation (str) – Orientation of the fit type.

Returns:

The fit type is set in the component.

Return type:

None

class reaction_plane_fit.fit.ReactionPlaneFit(resolution_parameters: Dict[str, float], use_log_likelihood: bool, signal_region: Optional[Tuple[float, float]] = None, background_region: Optional[Tuple[float, float]] = None, use_minos: bool = False, verbosity: int = 3)

Bases: abc.ABC

Contains the reaction plane fit for one particular set of data and fit components.

Parameters:

• resolution_parameters (dict) – Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82” (even RP only).
• use_log_likelihood (bool) – If true, use log likelihood cost function. Often used when statistics are limited. Default: False
• signal_region – Min and max extraction range for the signal dominated region. Should be provided as the absolute value (ex: (0., 0.6)).
• background_region – Min and max extraction range for the background dominated region. Should be provided as the absolute value (ex: (0.8, 1.2)).
• use_minos – Calculate the errors using Minos in addition to Hesse.
• verbosity – Minuit verbosity level. Default: 3. This is extremely verbose, but it’s quite useful. 1 is commonly when you would like less verbose output.

resolution_parameters

Maps resolution parameters of the form “R22” (for the R_{2,2} parameter) to the value. Expects “R22” - “R82” (even RP only).

Type:dict

use_log_likelihood

If true, use log likelihood cost function. Often used when statistics are limited. Default: False

Type:bool

signal_region

Min and max extraction range for the signal dominated region. Should be provided as the absolute value (ex: (0., 0.6)).

background_region

Min and max extraction range for the background dominated region. Should be provided as the absolute value (ex: (0.8, 1.2)).

use_minos

Calculate the errors using Minos in addition to Hesse. It will give a better error estimate, but it will be much slower. Errors will be printed but not stored because we don’t store the errors directly (rather, we store the covariance matrix, which one cannot extract from Minos). By printing out the values, the use can check that the Hesse and Minos errors are similar, which will indicate that the function is well approximated by a hyperparabola at the minima (and thus Hesse errors are okay to be used).

fit_result

Result of the RP fit.

cost_func

Cost function for the RP fit.

Type:Callable

create_full_set_of_components(input_data: Dict[FitType, pachyderm.histogram.Histogram1D]) → Dict[str, reaction_plane_fit.fit.FitComponent]

Create the full set of fit components.

fit(data: Union[Dict[str, Dict[str, Union[Any, pachyderm.histogram.Histogram1D]]], Dict[FitType, pachyderm.histogram.Histogram1D]], user_arguments: Optional[Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]] = None, skip_hesse: bool = False) → Tuple[bool, Dict[reaction_plane_fit.base.FitType, pachyderm.histogram.Histogram1D], iminuit._libiminuit.Minuit]

Perform the actual fit.

Parameters:

• data – Input data to be used for the fit. The keys should either be of the form [region][orientation] or [FitType]. The values can be uproot or ROOT 1D histograms.
• user_arguments – User arguments to override the arguments to the fit. Default: None.
• skip_hesse – This should be used rarely and only with care! True if the hesse should _not_ be explicitly run. This is useful because sometimes it fails without a clear reason. If skipped, Minos will automatically be run, and it’s up to the user to ensure that the symmetric error estimates from Hesse run during the minimization are close to the Minos errors. If they’re not, it indicates that something went wrong in the error calculation and Hesse was failing for good reason. Default: False.

Returns:

(fit_success, formatted_data, minuit) where fit_success (bool) is True if the fitting

procedure was successful, formatted_data (dict) is the data reformatted in the preferred format for the fit, and minuit (iminuit.Minuit) is the minuit object, which is provided it is provided for specialized use cases. Note that the fit results (which contains most of the information in the minuit object) are stored in the class.

Return type:

tuple

reaction_plane_parameters = {}

read_fit_object(filename: str, data: Union[Dict[str, Dict[str, Union[Any, pachyderm.histogram.Histogram1D]]], Dict[FitType, pachyderm.histogram.Histogram1D]], user_arguments: Optional[Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]] = None, y: ruamel.yaml.main.YAML = None) → Tuple[bool, Dict[reaction_plane_fit.base.FitType, pachyderm.histogram.Histogram1D]]

Read the fit results and setup the entire RPF object.

Using this method, the RPF object should be fully setup. The only step that isn’t performed is actually running the fit using Minuit. To read just the fit results into the object, use read_fit_results(...).

Parameters:

• filename – Name of the file under which the fit results are saved.
• data – Input data that was used for the fit. The keys should either be of the form [region][orientation] or [FitType]. The values can be uproot or ROOT 1D histograms.
• user_arguments – User arguments to override the arguments to the fit. Default: None.
• y – YAML object to be used for reading the result. If none is specified, one will be created automatically.

Returns:

(read_success, formatted_data) where read_success is True if the reading was successful, and formatted_data

is the input data reformatted according to the fit object format (ie. same as formatted_data returned when performing the fit). The results will be read into the fit object.

read_fit_results(filename: str, y: ruamel.yaml.main.YAML = None) → bool

Read all fit results from the specified filename using YAML.

We don’t read the entire object from YAML because they we would have to deal with serializing many classes. Instead, we read the fit results, with the expectation that the fit object will be created independently, and then the results will be loaded.

To reconstruct the entire fit object, use read_fit_object(...).

Parameters:

• filename – Name of the file under which the fit results are saved.
• y – YAML object to be used for reading the result. If none is specified, one will be created automatically.

Returns:

True if the reading was successful. The results will be read into the fit object.

rp_orientations

Get the RP orientations (excluding the inclusive, which is the last entry).

write_fit_results(filename: str, y: ruamel.yaml.main.YAML = None) → bool

Write all fit results to the specified filename using YAML.

We don’t write the entire object to YAML because they we would have to deal with serializing many classes. Instead, we write the results, with the expectation that the fit object will be created independently, and then the results will be loaded.

Parameters:

• filename – Name of the file under which the fit results will be saved.
• y – YAML object to be used for writing the result. If none is specified, one will be created automatically.

Returns:

True if the writing was successful.

class reaction_plane_fit.fit.SignalFitComponent(rp_orientation: str, *args, **kwargs)

Bases: reaction_plane_fit.fit.FitComponent

Fit component in the signal region.

Parameters:

• rp_orientation (str) – Reaction plane orientation for the component.
• *args (list) – Only use named args.
• **kwargs (dict) – Named arguments to be passed on to the base component.

determine_fit_function(resolution_parameters: Dict[str, float], reaction_plane_parameter: reaction_plane_fit.base.ReactionPlaneParameter) → None

Use the class parameters to determine the fit and background functions and store them.

three_orientations module

Implements the three RP orientation fit.

class reaction_plane_fit.three_orientations.BackgroundFit(*args, **kwargs)

Bases: reaction_plane_fit.three_orientations.ReactionPlaneFit

RPF for background region in 3 reaction plane orientations.

This is a simple helper class to define the necessary fit component. Contains fit components for 3 background RP orientations.

Parameters:as for ReactionPlaneFit. (Same) –

create_full_set_of_components(input_data: Dict[FitType, pachyderm.histogram.Histogram1D]) → Dict[str, reaction_plane_fit.fit.FitComponent]

Create the full set of fit components.

class reaction_plane_fit.three_orientations.BackgroundFitComponent(rp_orientation: str, *args, **kwargs)

Bases: reaction_plane_fit.fit.BackgroundFitComponent

Background fit component for three RP orientations.

determine_fit_function(resolution_parameters: Dict[str, float], reaction_plane_parameter: reaction_plane_fit.base.ReactionPlaneParameter) → None

Use the class parameters to determine the fit and background functions and store them.

class reaction_plane_fit.three_orientations.InclusiveSignalFit(*args, use_constrained_inclusive_background: bool = False, **kwargs)

Bases: reaction_plane_fit.three_orientations.ReactionPlaneFit

RPF for inclusive signal region, and background region in 3 reaction planes orientations.

This is a simple helper class to define the necessary fit component. Contains an inclusive signal fit, and 3 background RP orientations.

Parameters:as for ReactionPlaneFit. (Same) –

create_full_set_of_components(input_data: Dict[FitType, pachyderm.histogram.Histogram1D]) → Dict[str, reaction_plane_fit.fit.FitComponent]

Create the full set of fit components.

class reaction_plane_fit.three_orientations.ReactionPlaneFit(resolution_parameters: Dict[str, float], use_log_likelihood: bool, signal_region: Optional[Tuple[float, float]] = None, background_region: Optional[Tuple[float, float]] = None, use_minos: bool = False, verbosity: int = 3)

Bases: reaction_plane_fit.fit.ReactionPlaneFit

Base class for reaction plane fit for 3 reaction plane orientations.

_rp_orientations

List of the reaction plane orientations.

reaction_plane_parameter

Reaction plane parameters, including the orientation, center, and width.

reaction_plane_parameters = {'in_plane': ReactionPlaneParameter(orientation='in_plane', phiS=0, c=0.5235987755982988), 'inclusive': ReactionPlaneParameter(orientation='inclusive', phiS=0, c=1.5707963267948966), 'mid_plane': ReactionPlaneParameter(orientation='mid_plane', phiS=0.7853981633974483, c=0.2617993877991494), 'out_of_plane': ReactionPlaneParameter(orientation='out_of_plane', phiS=1.5707963267948966, c=0.5235987755982988)}

class reaction_plane_fit.three_orientations.SignalFit(*args, **kwargs)

Bases: reaction_plane_fit.three_orientations.ReactionPlaneFit

RPF for signal and background regions with 3 reaction plane orientations.

This is a simple helper class to define the necessary fit component. Contains 3 signal orientations and 3 background RP orientations.

Parameters:as for ReactionPlaneFit. (Same) –

create_full_set_of_components(input_data: Dict[FitType, pachyderm.histogram.Histogram1D]) → Dict[str, reaction_plane_fit.fit.FitComponent]

Create the full set of fit components.

class reaction_plane_fit.three_orientations.SignalFitComponent(inclusive_background_function: Callable[[...], float], *args, **kwargs)

Bases: reaction_plane_fit.fit.SignalFitComponent

Signal fit component for three RP orientations.

Parameters:inclusive_background_function – Background function for the inclusive RP orientation. By default, one should use fourier, but when not fitting the inclusive orientation, one should use the constrained fourier which sets the background level.

determine_fit_function(resolution_parameters: Dict[str, float], reaction_plane_parameter: reaction_plane_fit.base.ReactionPlaneParameter) → None

Use the class parameters to determine the fit and background functions and store them.

reaction_plane_fit.three_orientations.background(x: float, phi: float, c: float, resolution_parameters: Dict[str, float], B: float, v2_t: float, v2_a: float, v4_t: float, v4_a: float, v1: float, v3: float, **kwargs) → float

The background function is of the form specified in the RPF paper.

Resolution parameters implemented include R{2,2} through R{8,2}, which denotes the resolution of an order m reaction plane with respect to n = 2 reaction plane. R{8,2} is the highest value which should contribute to v_4^{eff}.

Parameters:

• x (float) – Delta phi value for which the background will be calculated.
• phi (float) – Center of the reaction plane bin. Matches up to phi_s in the RPF paper
• c (float) – Width of the reaction plane bin. Matches up to c in the RPF paper
• resolution_parameters (dict) – Contains the resolution parameters with respect to the n = 2 reaction plane. Note the information about the parameters above. The expected keys are “R22” - “R82”.
• B (float) – Overall multiplicative background level.
• v2_t (float) – Trigger v_{2}.
• v2_a (float) – Associated v_{2}.
• v4_t (float) – Trigger v_{4}.
• v4_a (float) – Associated v_{4}
• v1 (float) – v1 parameter.
• v3 (float) – v3 parameter.
• kwargs (dict) – Used to absorbs extra possible parameters from Minuit (especially when used in conjunction with other functions).

Returns:

Values calculated by the function.

Return type:

float

reaction_plane_fit.three_orientations.constrained_inclusive_background(x: Union[numpy.ndarray, float], B: float, v2_t: float, v2_a: float, v4_t: float, v4_a: float, v1: float, v3: float, **kwargs) → float

Background function for inclusive signal component when performing the background fit.

Includes the trivial scaling factor of B / 3 because there are 3 RP orientations and that background level is set by the individual RP orientations. So when they are added together, they are (approximately) 3 times more. This constrain is not included by default because there is additional information in the relative scaling of the various EP orientations.

Parameters:

• x (float) – Delta phi value for which the background will be calculated.
• B (float) – Overall multiplicative background level.
• v2_t (float) – Trigger v_{2}.
• v2_a (float) – Associated v_{2}.
• v4_t (float) – Trigger v_{4}.
• v4_a (float) – Associated v_{4}
• v1 (float) – v1 parameter.
• v3 (float) – v3 parameter.
• kwargs (dict) – Used to absorbs extra possible parameters from Minuit (especially when used in conjunction with other functions).

Returns:

Values calculated by the function.

Return type:

float

reaction_plane_fit.three_orientations.unconstrained_inclusive_background(x: Union[numpy.ndarray, float], B: float, v2_t: float, v2_a: float, v4_t: float, v4_a: float, v1: float, v3: float, **kwargs) → float

Background function for inclusive signal component when performing the background fit.

This basically just forwards the arguments onto the Fourier series, but it renames the background variable. It doesn’t include the trivial scaling factor of approximately B / 3 that occurs when adding the three event plane orientations to compare against the inclusive because that information can be useful to further constrain the fits.

Parameters:

• x – Delta phi value for which the background will be calculated.
• B – Overall multiplicative background level.
• v2_t – Trigger v_{2}.
• v2_a – Associated v_{2}.
• v4_t – Trigger v_{4}.
• v4_a – Associated v_{4}
• v1 – v1 parameter.
• v3 – v3 parameter.
• kwargs – Used to absorbs extra possible parameters from Minuit (especially when used in conjunction with other functions).

Returns:

Values calculated by the function.

Return type:

float

example module

Example of how to use the Reaction Plane Fit package.

Provides example for fitting only the background, or fitting the inclusive signal.

reaction_plane_fit.example.run_background_fit(input_filename: str, user_arguments: Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]) → Tuple[reaction_plane_fit.fit.ReactionPlaneFit, Dict[str, reaction_plane_fit.fit.FitComponent], Dict[FitType, pachyderm.histogram.Histogram1D], iminuit.Minuit]

Run the background example fit.

Parameters:

• input_filename – Path to the input data to use.
• user_arguments – User arguments to override the arguments to the fit.

Returns:

(rp_fit, full_components, data, minuit), where rp_fit (fit.ReactionPlaneFit) is the reaction plane

fit object from the fit, full_components is the full set of fit components (one for each RP orientation), data (dict) is the formated data dict used for the fit, and minuit is the minuit fit object.

Return type:

tuple

reaction_plane_fit.example.run_differential_signal_fit(input_filename: str, user_arguments: Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]) → Tuple[reaction_plane_fit.fit.ReactionPlaneFit, Dict[str, reaction_plane_fit.fit.FitComponent], Dict[FitType, pachyderm.histogram.Histogram1D], iminuit.Minuit]

Run the differential signal example fit.

Parameters:

• input_filename – Path to the input data to use.
• user_arguments – User arguments to override the arguments to the fit.

Returns:

(rp_fit, full_components, data, minuit), where rp_fit (fit.ReactionPlaneFit) is the reaction plane

fit object from the fit, full_components is the full set of fit components (one for each RP orientation), data (dict) is the formated data dict used for the fit, and minuit is the minuit fit object.

Return type:

tuple

reaction_plane_fit.example.run_fit(fit_object: Type[reaction_plane_fit.fit.ReactionPlaneFit], input_data: Dict[str, Dict[str, Union[Any, pachyderm.histogram.Histogram1D]]], user_arguments: Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]) → Tuple[reaction_plane_fit.fit.ReactionPlaneFit, Dict[str, reaction_plane_fit.fit.FitComponent], Dict[FitType, pachyderm.histogram.Histogram1D], iminuit.Minuit]

Driver function for performing the fit.

Note

Here we just set the resolution parameters to 1 for convenience of the example, but they are an extremely important part of the fit!

Parameters:

• fit_object – Fit object to be used.
• data – Input data for the fit, labeled as defined in setup_data().
• user_arguments – User arguments to override the arguments to the fit.

Returns:

(rp_fit, full_components, data, minuit), where rp_fit (fit.ReactionPlaneFit) is the reaction plane

fit object from the fit, full_components is the full set of fit components (one for each RP orientation), data (dict) is the formated data dict used for the fit, and minuit is the minuit fit object.

Return type:

tuple

reaction_plane_fit.example.run_inclusive_signal_fit(input_filename: str, user_arguments: Dict[str, Union[bool, float, Tuple[float, float], Tuple[int, int]]]) → Tuple[reaction_plane_fit.fit.ReactionPlaneFit, Dict[str, reaction_plane_fit.fit.FitComponent], Dict[FitType, pachyderm.histogram.Histogram1D], iminuit.Minuit]

Run the inclusive signal example fit.

Parameters:

• input_filename – Path to the input data to use.
• user_arguments – User arguments to override the arguments to the fit.

Returns:

(rp_fit, full_components, data, minuit), where rp_fit (fit.ReactionPlaneFit) is the reaction plane

fit object from the fit, full_components is the full set of fit components (one for each RP orientation), data (dict) is the formated data dict used for the fit, and minuit is the minuit fit object.

Return type:

tuple

reaction_plane_fit.example.setup_data(input_filename: str) → Dict[str, Dict[str, Union[Any, pachyderm.histogram.Histogram1D]]]

Setup the example input data.

Read the data using uproot so we can avoid an explicit dependency on ROOT. Histograms are assumed to be named {region}_{orientation} (for example, “signalDominated_inclusive”).

Parameters:input_filename – Path to the input data to use. Returns:Containing the input data. Return type:dict

Some additional helpful links:

• Index
• Module Index
• Search Page

For any code contributions, please be certain to document:

• New functions, arguments, and classes.
• New attributes of classes.

All of the above can be documented in the source, with the exception of adding new modules to the docs. The new modules must be added in the docs/api folder.

Reaction plane fit

DOI Documentation Status Build Status codecov

Implements the reaction plane (RP) fit described in Phys. Rev. C 93, 044915 (or on the arxiv) to characterize and subtract background contributions to correlation functions measured in heavy ion collisions. It allows for fits to the background dominated region, as well as the option of fitting the RP inclusive signal dominated region or the RP dependent signal dominated region. This package implements the fit for three orientations relative to the RP, with the possibility of straightforward extension to other sets of orientations.

Sample reaction plane fit

Installation

This package requires python 3.6 and above. A few prerequisites are required which unfortunately cannot be resolved solely by pip because of the packaging details of probfit.

$ pip install numpy cython

The package is available on PyPI and is available via pip.

$ pip install reaction_plane_fit

You may want to consider installing this to your user directory (--user) or better, within a virtual environment.

Usage

Performing a fit with this package only requires a few lines of code. Below is sufficient to define and run a fit with some sample values:

from reaction_plane_fit import three_orientations
# Define the fit object.
rp_fit = three_orientations.BackgroundFit(
    resolution_parameters = {"R22": 0.6, "R42": 0.3, "R62": 0.1, "R82": 0.1},
    use_log_likelihood = False,
    signal_region = (0, 0.6),
    background_region = (0.8, 1.2),
)
# Load or otherwise provide the relevant histograms here.
# The structure of this dictionary is important to ensure that the proper data ends up in the right place.
# Note that the data must already be projected into the background or signal dominated regions.
data = {"background": {"in_plane": ROOT.TH1.., "mid_plane": ROOT.TH1..., "out_of_plane": ROOT.TH1...}}
# Perform the actual fit.
success, _ = rp_fit.fit(data = data)
# Print the fit results
print("Fit result: {fit_result}".format(fit_result = rp_fit.fit_result))

For best fit results, the data should not be normalized by the number of triggers before performing the fit. Afterwards, the fit needs to be scaled by the number of triggers in order to make it comparable to the scaled data. Examples for fitting an inclusive reaction plane orientation signal alongside the background, or for fitting only the background are both available in reaction_plane_fit.example. This module can also be run directly in the terminal via:

$ python -m reaction_plane_fit.example [-b] [-i dataFilename]

If fit data is not specified, it will use some sample data. For further information, including all possible fit function combinations, please see the full documentation.

But I don’t like python!

You might not be so happy about using Python. That’s okay - we can work around this using ROOT, although it will be much more painful than using python directly. To do so, it should look something like (the code below is untested, so it may need some minor modifications):

// Setup the input data.
std::map<std::string, std::map<std::string, TH1*>> inputData;
inputData["background"]["in_plane"] = my_in_plane_hist;
// Fill in the rest of your input data.
...
// Setup the fit objects.
TPython::Exec("from reaction_plane_fit import three_orientations");
TPython::Exec("rp_fit = three_orientations.BackgroundFit("
    "resolution_parameters = {'R22': 0.6, 'R42': 0.3, 'R62': 0.1, 'R82': 0.1},"
    "use_log_likelihood = False,"
    "signal_region = (0, 0.6),"
    "background_region = (0.8, 1.2),)"
);
// Perform the actual fit.
TPython::Exec("success, _ = rp_fit.fit(data = data)");
// Print the fit results.
TPython::Exec("print('Fit result: {fit_result}'.format(fit_result = rp_fit.fit_result))")
// Access values back in c++.
int chi_2 = double(TPython::Eval("rp_fit.fit_result.minimum_val"))
// It will require some attention to extract all of the relevant values.
// You can extract a number of types (see TPyResult), but it doens't appear that you can extract complex objects.
// So this could still be a somewhat painful process.

(Don’t forgot that we’re calling Minuit underneath, so this package should be fast enough for this fit).

Fits implemented

There are three possible types of fits:

• Background dominated region only: This fits only regions on the near-side at large dEta which are dominated by background contributions. Called BackgroundFit in each set of orientations implementation.
• Inclusive signal region: This fits to the RP inclusive signal dominated region, as well as fitting the RP dependent background dominated regions. Called InclusiveSignalFit in each set of orientations implementation.
• RP dependent signal region: This fits to the RP dependent signal dominated region, as well as fitting the RP dependent background dominated regions. Called SignalFit in each set of orientations implementation.

Three orientation (in-, mid-, and out-of-plane)

This package implements the fit for three orientations relative to the reaction plane:

• in-plane (0<|Δφ|<π/6)
• mid-plane (π/6<|Δφ|<π/3)
• and out-of-plane (π/3<|Δφ|<π/2)

These fits are implemented in the reaction_plane_fit.three_orientations module.

Notes on fitting

This package makes it possible to use Minos rather than Hesse errors. Minos errors can be calculated when Hesse errors become inaccurate (when the function around the minima is not approximately a hyperparabola), but they can take much longer to calculate and cannot be described via a covariance matrix (which makes error propagation much more difficult). If the Hesse and Minos errors are similar, then the function is well approximately by a hyperparabola and you can safely use Hesse errors. For more, see the iminuit tutorials.

Development

If developing the packaging, clone the repository and then install with

$ pip install -e .[dev,tests]

Note that python 3.6 and above is required because this package uses dataclasses (which has a python 3.6 backport), and it relies on dictionaries being ordered (which is true for cpython 3.6 and is required for python 3.7 in general).

Citation

Please cite the paper (Phys. Rev. C 93, 044915), as well as this implementation:

@misc{raymond_ehlers_2018_1599239,
  author       = {Raymond Ehlers},
  title        = {reactionPlaneFit - RPF implementation},
  month        = nov,
  year         = 2018,
  doi          = {10.5281/zenodo.1599239},
  url          = {https://doi.org/10.5281/zenodo.1599239}
}

Acknowledgments

Code started from implementation work done by M. Arratia. Thanks to C. Nattrass and J. Mazer for help and discussions.

Testing the Reaction Plane Fit package

Tests are implemented using pytest. To execute the testing, I tend to use something like:

$ pytest -l --cov=reaction_plane_fit --cov-report html --cov-branch --durations=5 --mpl tests/

This assumes you are running from the root repository folder and will report on which tests are the slowest as well as provide a coverage report for (in this case) the entire reaction_plane_fit module. The branch coverage is particularly useful to help avoid missing coverage over control flow.

There are two particularly noteworthy classes of marked tests:

• ROOT: Tests which require ROOT.
• slow: Tests which are slow, as they run the entire fit code. These are particularly slow because of the error calculation.

Recall that a particular class of tests (named CLASS in this example) can be skipped by passing -m "not CLASS" argument to pytest.

Installing the test dependencies

Beyond ROOT (which is required for tests marked as “ROOT”), the package test dependencies can be installed with:

$ pip install -e .[tests]

Image comparisons

Image comparisons are performed via pytest-mpl. To generate the comparison images, run in the tests directory:

$ pytest --mpl-generate-path=baseline

This will create comparison images in the tests/baseline directory. Once the comparisons have been created, you can compare the images by passing the option --mpl to pytest. Note that if the argument is not passed, the test code itself will be run, but the image won’t be compared.

Note that if a new figure is added, it is up to you to generate and add the baseline image locally. Travis will only do the comparison, not the generation.

The Reaction Plane Fit (RPF) package implements the Reaction Plane Fit method described in Phys. Rev. C 93, 044915 (or on the arxiv), with an additional extension to fitting the near and away-side signals. The package implements the three reaction plane orientation fit, but extensions to further sets of orientations requires just writing down the background fit function and defining the reaction plane orientation properties.

For further information on the purpose of the package, quick start information, as well as an example, please see the README. Documentation of the RPF package is available on the detailed code documentation page.