Outputs

This module contains the Results objects and the relevant objects to retrieve results data from the C++ module.

Converts results from the compiled RAT code to python dataclasses.

class ratapi.outputs.BayesResults(reflectivity, simulation, shiftedData, backgrounds, resolutions, sldProfiles, layers, resampledLayers, calculationResults, contrastParams, fitParams, fitNames, predictionIntervals, confidenceIntervals, dreamParams, dreamOutput, nestedSamplerOutput, chain)

The results of a Bayesian RAT calculation.

Parameters:

• predictionIntervals (PredictionIntervals) – The prediction intervals.

• confidenceIntervals (ConfidenceIntervals) – The 65% and 95% confidence intervals for the best fit results.

• dreamParams (DreamParams) – The parameters used by DREAM, if relevant.

• dreamOutput (DreamOutput) – The output from DREAM if DREAM was used.

• nestedSamplerOutput (NestedSamplerOutput) – The output from nested sampling if ns was used.

• chain (np.ndarray) – The MCMC chains for each parameter. The i’th column of the array contains the chain for parameter fitNames[i].

• reflectivity (list)

• simulation (list)

• shiftedData (list)

• backgrounds (list)

• resolutions (list)

• sldProfiles (list)

• layers (list)

• resampledLayers (list)

• calculationResults (CalculationResults)

• contrastParams (ContrastParams)

• fitParams (ndarray)

• fitNames (list[str])

save(filepath='./results.json')

Save the BayesResults object to a JSON file.

Parameters:

filepath (str or Path) – The path to where the results file will be written.

class ratapi.outputs.CalculationResults(chiValues, sumChi)

The goodness of fit from the Abeles calculation.

Parameters:

• chiValues (np.ndarray) – The chi-squared value for each contrast.

• sumChi (float) – The sum of the chiValues array.

class ratapi.outputs.ConfidenceIntervals(percentile95, percentile65, mean)

The 65% and 95% confidence intervals for the best fit results.

Parameters:

• percentile95 (np.ndarray) – The 95% confidence intervals for each fit parameter.

• percentile65 (np.ndarray) – The 65% confidence intervals for each fit parameter.

• mean (np.ndarray) – The mean values for each fit parameter.

class ratapi.outputs.ContrastParams(scalefactors, bulkIn, bulkOut, subRoughs, resample)

The experimental parameters for each contrast.

Parameters:

• scalefactors (np.ndarray) – The scalefactor values for each contrast.

• bulkIn (np.ndarray) – The bulk in values for each contrast.

• bulkOut (np.ndarray) – The bulk out values for each contrast.

• subRoughs (np.ndarray) – The substrate roughness values for each contrast.

• resample (np.ndarray) – An array containing whether each contrast was resampled.

class ratapi.outputs.DreamOutput(allChains, outlierChains, runtime, iteration, AR, R_stat, CR)

The diagnostic output information from DREAM.

Parameters:

• allChains (np.ndarray) –

  An nGenerations x nParams + 2 x nChains size array, where chain_k = DreamOutput.allChains[:, :, k] is the data of chain k in the final iteration; for generation i of the final iteration, chain_k[i, j] represents:

  • the sampled value of parameter j for j in 0:nParams;

  • the associated log-prior for those sampled values for j = nParams + 1;

  • the associated log-likelihood for those sampled values for j = nParams + 2.

• outlierChains (np.ndarray) – A two-column array where DreamOutput.AR[i, 1] is the index of a chain and DreamOutput.AR[i, 0] is the length of that chain when it was removed for being an outlier.

• runtime (float) – The runtime of the DREAM algorithm in seconds.

• iteration (float) – The number of iterations performed.

• AR (np.ndarray) – A two-column array where DreamOutput.AR[i, 0] is an iteration number and DreamOutput.AR[i, 1] is the average acceptance rate of chain step proposals for that iteration.

• R_stat (np.ndarray) – An array where DreamOutput.R_stat[i, 0] is an iteration number and DreamOutput.R_stat[i, j] is the convergence statistic for parameter j at that iteration (where chains are indexed 1 to nParams inclusive).

• CR (np.ndarray) – A four-column array where DreamOutput.CR[i, 0] is an iteration number, and DreamOutput.CR[i, j] is the selection probability of the j’th crossover value for that iteration.

class ratapi.outputs.DreamParams(nParams, nChains, nGenerations, parallel, CPU, jumpProbability, pUnitGamma, nCR, delta, steps, zeta, outlier, adaptPCR, thinning, epsilon, ABC, IO, storeOutput, R)

The parameters used by the inner DREAM algorithm.

Parameters:

• nParams (float) – The number of parameters used by the algorithm.

• nChains (float) – The number of MCMC chains used by the algorithm.

• nGenerations (float) – The number of DE generations calculated per iteration.

• parallel (bool) – Whether the algorithm should run chains in parallel.

• CPU (float) – The number of processor cores used for parallel chains.

• jumpProbability (float) – A probability range for the size of jumps when performing subspace sampling.

• pUnitGamma (float) – The probability that the scaling-down factor of jumps will be ignored and a larger jump will be taken for one iteration.

• nCR (float) – The number of crossovers performed each iteration.

• delta (float) – The number of chain mutation pairs proposed each iteration.

• steps (float) – The number of MCMC steps to perform between conversion checks.

• zeta (float) – The ergodicity of the algorithm.

• outlier (str) – What test should be used to detect outliers.

• adaptPCR (bool) – Whether the crossover probability for differential evolution should be adapted by the algorithm as it runs.

• thinning (float) – The thinning rate of each Markov chain (to reduce memory intensity)

• epsilon (float) – The cutoff threshold for Approximate Bayesian Computation (if used)

• ABC (bool) – Whether Approximate Bayesian Computation is used.

• IO (bool) – Whether the algorithm should perform IO writes of the model in parallel.

• storeOutput (bool) – Whether output model simulations are performed.

• R (np.ndarray) – An array where row i is the list of chains with which chain i can mutate.

class ratapi.outputs.NestedSamplerOutput(logZ, logZErr, nestSamples, postSamples)

The output information from the Nested Sampler (ns).

Parameters:

• logZ (float) – The natural logarithm of the evidence Z for the parameter values.

• logZErr (float) – The estimated uncertainty in the final value of logZ.

• nestSamples (np.ndarray) –

  NestedSamplerOutput.nestSamples[i, j] represents the values sampled at iteration i, where this value is:

  • the value sampled for parameter j, for j in 0:nParams,

  • the minimum log-likelihood for j = nParams + 1.

• postSamples (np.ndarray) – The posterior values at the points sampled in NestedSamplerOutput.nestSamples.

class ratapi.outputs.PredictionIntervals(reflectivity, sld, sampleChi)

The Bayesian prediction intervals for 95% and 65% confidence.

For reflectivity and sld, each list item is an array with five rows. The rows represent:

• 0: the 5th percentile;

• 1: the 35th percentile;

• 2: the mean value of the interval;

• 3: the 65th percentile;

• 4: the 95th percentile.

Parameters:

• reflectivity (list) – The prediction interval data for reflectivity of each contrast.

• SLD (list) – The prediction interval data for SLD of each contrast.

• sampleChi (np.ndarray) – The value of sumChi at each point of the Markov chain.

• sld (list)

class ratapi.outputs.RATResult

A mixin class which truncates arrays when the class is displayed.

class ratapi.outputs.Results(reflectivity, simulation, shiftedData, backgrounds, resolutions, sldProfiles, layers, resampledLayers, calculationResults, contrastParams, fitParams, fitNames)

The results of a RAT calculation.

Parameters:

• reflectivity (list) – The reflectivity curves for each contrast, with the same range as the data (data_range in the contrast’s Data object)

• simulation (list) – The reflectivity curves for each contrast, which can be a wider range to allow extrapolation (simulation_range in the contrast’s Data object).

• shiftedData (list) – The data with scalefactors and background corrections applied.

• backgrounds (list) – The background for each contrast defined over the simulation range.

• resolutions (list) – The resolution for each contrast defined over the simulation range.

• sldProfiles (list) – The SLD profiles for each contrast.

• layers (list) – The array of layer parameter values for each contrast.

• resampledLayers (list) – If resampling is used, the array of layer parameter values for each contrast after resampling has been performed.

• calculationResults (CalculationResults) – The chi-squared fit results from the final calculation and fit.

• contrastParams (ContrastParams) – The experimental parameters for the contrasts.

• fitParams (np.ndarray) – The best fit value of the parameter with name fitNames[i].

• fitNames (list[str]) – The names of the fit parameters, where fitNames[i] is the name of the parameter with value given in fitParams[i].

classmethod load(path)

Load a Results object from file.

Parameters:

path (str or Path) – The path to the results json file.

Return type:

Results | BayesResults

save(filepath='./results.json')

Save the Results object to a JSON file.

Parameters:

filepath (str or Path) – The path to where the results file will be written.

ratapi.outputs.get_field_string(field, value, array_limit)

Return a string representation of class fields where large arrays are represented by their shape.

An array will be displayed as just its shape if it is multidimensional or 1D and longer than array_limit.

Parameters:

• field (str) – The name of the field in the RAT output class.

• value (Any) – The value of the given field in the RAT output class.

• array_limit (int) – The maximum length of 1D arrays which will be fully displayed.

Returns:

field_string – The string representation of the field in the RAT output class.

Return type:

str

Examples

>>> get_field_string("data", 130, 5)
"data = 130"

>>> get_field_string("data", array([1, 2, 3, 4, 5]), 10)
"data = [1 2 3 4 5]"

>>> get_field_string("data", array([1, 2, 3, 4, 5]), 3)
"data = Data array: [5],"

>>> get_field_string("data", array([[1, 2, 3], [4, 5, 6]]), 10)
"data = Data array: [2 x 3],"

ratapi.outputs.make_results(procedure, output_results, bayes_results=None)

Initialise a python Results or BayesResults object using the outputs from a RAT calculation.

Parameters:

• procedure (Procedures) – The procedure used by the calculation.

• output_results (ratapi.rat_core.OutputResult) – The C++ output results from the calculation.

• bayes_results (Optional[ratapi.rat_core.OutputBayesResult]) – The optional extra C++ Bayesian output results from a Bayesian calculation.

Returns:

A result object containing the results of the calculation, of type Results for non-Bayesian procedures and BayesResults for Bayesian procedures.

Return type:

Results or BayesResults

ratapi.outputs.read_bayes_results_fields(results_dict)

Modify the values of the fields that appear only in BayesResults when loading a json file.

Parameters:

results_dict (Optional[dict]) – The dictionary containing the json input.

Returns:

results_dict – The input json dict with the fields that appear in both Results and BayesResults converted to numpy arrays where necessary.

Return type:

dict

ratapi.outputs.read_core_results_fields(results_dict)

Modify the values of the fields that appear in both Results and BayesResults when loading a json file.

Parameters:

results_dict (Optional[dict]) – The dictionary containing the json input.

Returns:

results_dict – The input json dict with the fields that appear in both Results and BayesResults converted to numpy arrays where necessary.

Return type:

dict

ratapi.outputs.write_core_results_fields(results, json_dict=None)

Modify the values of the fields that appear in both Results and BayesResults when saving to a json file.

Parameters:

• results (Union[Results, BayesResults]) – The results or BayesResults object we are writing to json.

• json_dict (Optional[dict]) – The dictionary containing the json output.

Returns:

json_dict – The output json dict updated with the fields that appear in both Results and BayesResults.

Return type:

dict