microcalorimetry.analysis ========================= .. py:module:: microcalorimetry.analysis .. autoapi-nested-parse:: This module contains high-level routines for performing microcalorimetry analysis. This module should contain static functions which take in configuration objects, and primative types (strings, numbers) that are then used to process the data. Where possible, they should use math functions defined in the math module. These functions should be interfaceable via either a command line interface or a GUI where the user can only enter string-like inputs. These function should utilize DataModelContainers when referring to inputs that represent inputs that cant be described by a short string (i.e. something convenient for a command line interface). This enables the passing of in-memory representations of data via the DataModelContainers so that it isn't required to serialize the output of one function in order to pass it to the input of another. .. !! processed by numpydoc !! Functions --------- .. autoapisummary:: microcalorimetry.analysis.make_correction_factor microcalorimetry.analysis.gc_from_model microcalorimetry.analysis.review_correction_factor microcalorimetry.analysis.fit_thermoelectric microcalorimetry.analysis.make_eta microcalorimetry.analysis.review_eta microcalorimetry.analysis.make_eta_repeatability_model microcalorimetry.analysis.make_classical_eta_unc_model microcalorimetry.analysis.dc_lead_correction microcalorimetry.analysis.apply_uncertainty_model microcalorimetry.analysis.compression_check Package Contents ---------------- .. py:function:: make_correction_factor(gc_regressor_rows: microcalorimetry.configs.CorrectionFactorModelInputs, correction_terms: int, calc_thermal_weights: bool = False, make_plots: bool = True, nominals: bool = False, cache_s11: bool = True, freq_resolution: int = 4) -> tuple[microcalorimetry.configs.GCLike, list[matplotlib.pyplot.Figure]] Calculate the correction factor for a given sensor model. The normal_standards and special_standards are used to generate the regressor matrix. All possible combinations of connect cycles that use the same splitter_id are used to build the regressor matrix. :param gcinputs: Dictionary of CorrectionFactorDataInputs. :type gcinputs: configs.CorrectionFactorDataInputs :param correction_terms: Number of terms in correction factor. Usually 1. :type correction_terms: int :param calc_thermal_weights: If true, returns thermal weighting coefficients isntead of the correction factors (g_ci = wi/W0) where W0 is the sensitivity of the calorimeter. :type calc_thermal_weights: bool, optional :param make_plots: Makes plots. The default is True. :type make_plots: bool, optional :param nominals: If true, propagates uncertainties. :type nominals: bool, optional :param cache_s11: If true, read ins every s-parameter file once to avoid redundant loading of files, memory intensive. :type cache_s11: bool, optional :returns: * **gc** (*RMEMeas*) -- Correction factor in RMEMeas format. * **figs** (*list[Figure]*) -- Matplotlib figures generated (if asked to make plots.) .. !! processed by numpydoc !! .. py:function:: gc_from_model(frequency: numpy.array, model: microcalorimetry.configs.PythonFunction, terms: int = 1) -> tuple[microcalorimetry.configs.GCLike, matplotlib.pyplot.Figure] Supply a parsed RF sweep and a python function to generate a GC model. :param frequency: Frequencies to evaluate model at. :type frequency: np.array :param model: Python function that takes in a frequency (GHz) list and outputs correction factor values with the same shape. :type model: configs.PythonFunction :param terms: How many terms int he gc model. Default is 1. :type terms: int, optional :raises NotImplementedError: Only 1 term currently supported. :returns: * **gc** (*configs.GCLike*) -- Correction factor object. * **fig** (*plt.Figure*) -- Plot of the generated GC. .. !! processed by numpydoc !! .. py:function:: review_correction_factor(gc: microcalorimetry.configs.GCLike, units: str = '', budget: bool = True) -> list[matplotlib.pyplot.Figure, ...] Review a correction factor model. :param gc: Correction factor model. :type gc: configs.GCLike :param units: Units string for y-axis. The default is ''. :type units: str, optional :param budget: Plot the uncertainty budget. The default is True. :type budget: bool, optional :returns: List of figures generated. :rtype: list[plt.Figure,...] .. !! processed by numpydoc !! .. py:function:: fit_thermoelectric(parsed_dcsweep: microcalorimetry.configs.ParsedDCSweep, thermometer_corrected: bool = False, constrain_zero: bool = False, p_of_e: bool = False, deg: int = 2, min_p: float = 0.001, make_plots: bool = True) -> tuple[rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.KDCTemInd | microcalorimetry.arrays.KDCTempDep], matplotlib.pyplot.Figure] Fit sensitivity coefficients to a dcsweep measurement of a thermoelectric. Takes in a parsed dc measurement and generates sensitivity coefficients. :param parsed_dcsweep: Steps parsed from sensitivity measurement. The first field is the applied voltage, the second field is the applied current, and the last field is the measure thermopile voltage. :type parsed_dcsweep: microcalorimetry.configs.ParsedDCSweep :param thermometer_corrected: Use a thermometer corrected model. Requires a thermometer voltage and current to be present in the parsed DC sweep. The default is False. :type thermometer_corrected: bool, optional :param constrain_zero: Constrains the fit to zero, only applies to non-thermometer corrected models. The default is False. :type constrain_zero: bool, optional :param p_of_e: Fit power as a function of thermopile voltage if True. If False, fits thermopile voltage as a function of power. Only applies to non thermometer corrected models. The default is False. :type p_of_e: bool, optional :param deg: Fit degrees of polynomial for non thermometer corrected models. Only applies to non thermometer corrected models. The default is 2. :type deg: int, optional :param min_p: The minimum power value to include in the fit. Values below this will be included as part of the residuals. The default is 0.001 (1 mW). :type min_p: float, optional :param make_plots: Output plots if True. :type make_plots: bool, optional :returns: * **sensitivity** (*RMEMeas[arrays.KDCTemInd | arrays.KDCTempDep]*) -- Sensitivity coefficients * **figures** (*list[plt.Figure]*) -- List of figures generated (empty if not made). Fit and residuals. .. !! processed by numpydoc !! .. py:function:: make_eta(gc: microcalorimetry.configs.GCLike, s11: microcalorimetry.configs.S11Like, parsed_rfsweep: microcalorimetry.configs.ParsedRFSweep, clrm_sensitivity: microcalorimetry.configs.KDCLike = None, repeatability_model: microcalorimetry.configs.EtaLike = None, extra_eta_uncertainties: list[pathlib.Path] = None, historical_data: microcalorimetry.configs.EtaHistorical = None, legacy_uncertainties: bool = False, make_plots: bool = True) -> tuple[list[matplotlib.pyplot.Figure] | None, rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.Eta]] Make an effective efficiency measurement. :param gc: Calorimetric correction factor terms. :type gc: configs.GCLike :param s11: Reflection coefficient of the sensor. :type s11: configs.S11Like :param parsed_rfsweep: Parsed RF sweep output. :type parsed_rfsweep: configs.ParsedRFSweep :param clrm_sensitivity: If provided, assumes the correction factor is weighted by the calorimeters sensitivity and provide in units of (V/W). These coefficents will be used to calculate the dimensionless correction factor. The default is None. :type clrm_sensitivity: configs.KDCLike, optional :param repeatability_model: Supply a repeatability model of the microcalorimeter to apply as uncertainty mechanisms and use in review charts. The default is None. :type repeatability_model: configs.EtaLike, optional :param extra_eta_uncertainties: Supply additional uncertainty models of eta that should be applied after the correction. The default is None. :type extra_eta_uncertainties: list[Path], optional :param historical_data: Supply a historical Eta configuration object to use a reference measurements in the review charts. The default is None. :type historical_data: configs.EtaHistorical, optional :param legacy_uncertainties: If legacy uncertainties are selected, than uncertainties will not be carried forward from the supplied reflection coefficient, correction factor, dc measurements, and or sensitivity model. All uncertainties are expected to be supplied via the extra_eta_uncertainties or repeatability_model options. This is to support legacy microcalorimeter systems which do not forward propagate uncertainties from their measurement. The default is False. :type legacy_uncertainties: bool, optional :param make_plots: Make plots during the analsysis,otherwise figs will be an empty list. The default is True. Plots are made by passing off to the review eta function. :type make_plots: bool, optional :returns: * **fig** (*List[plt.Figure] | None*) -- Any figures generated. * **eta** (*RMEMeas[arrays.Eta]*) -- Effective efficiency. .. !! processed by numpydoc !! .. py:function:: review_eta(eta: microcalorimetry.configs.EtaLike, historical_data: microcalorimetry.configs.EtaHistorical = None, repeatability_model: microcalorimetry.configs.EtaLike = None, k: int = 2, frequency_precision: int = 4, max_hist_legend: int = None, hist_avg: bool = True) -> tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Figure] Make review plots of effective efficiency data. :param eta: Effective efficiency being reviewed. :type eta: configs.EtaLike :param historical_data: Historical data to review against. :type historical_data: configs.EtaHistorical :param repeatability_model: Model of calorimeter's repeatability to plot. :type repeatability_model: configs.EtaLike :param k: Expansion factor, by default 2 :type k: int, optional :param frequency_precision: Precision (decimal places) to round off frequencies to before averaging and comparing measurements. :type frequency_precision: int, optional :param max_hist_legend: Maxmium number of historical measurmeents to include in the legend. If None, will include all. Many historical measurements will result in large legends. :type max_hist_legend: int, optional :param hist_avg: If True, include the average of historical measurements in the plot. :type hist_avg: bool, optional :returns: * *fig_hist* -- Figure of effectice efficiency measurement plotted against reference data provided. * *fig_budget* -- Figure of uncertainty budget for effective efficiency measurement. .. !! processed by numpydoc !! .. py:function:: make_eta_repeatability_model(historical_data: dict[microcalorimetry.configs.EtaHistorical], make_plots: bool = True, dist: str = 'gaussian', coverage: float = 2, ddof: int = 1, min_points: int = 3, model_type: str = 'expanding_quadratic', categories: dict = {'Type': 'A', 'Origin': 'Repeatability'}, umech_id_basename: str = 'Repeatability', frequencies: numpy.array = None) -> tuple[rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.Eta], list[matplotlib.pyplot.Figure], rmellipse.uobjects.RMEMeas] Generate a historical repeatability model from sensor data. :param historical_data: List of EtaHistorical configuration objects for different sensors. The key of each entry is the name of a sensor, and the values are the EtaHistorical objects. :type historical_data: dict[configs.EtaHistorical] :param make_plots: Generate figures if True. :type make_plots: bool, optional :param dist: Assume a type of distribution. Options are 'guassian' or 'uniform'. By default 'gaussian'. :type dist: str, optional :param coverage: Attempts to have 1 std uncertainty meet this coverage factor. The default is 2. :type coverage: int, optional :param ddof: Delta degrees of freedom when calculating standard uncertainty frequency by frequency, only relevant for gaussian distributions. :type ddof: int, optional :param min_points: Minimum number of required samples per frequency point to be included as part of the fit. The default is 3. :type min_points: int, optional :param model_type: Type of repeatability model to use. Expanding models are a constant value up to a cut off frequency, at which point they transition to a increasing function. One of 'expanding_quadratic','expanding_quadratic_linear','quadratic','constant','line'. :type model_type: str, optional, {'expanding_quadratic','expanding_quadratic_linear','quadratic','constant','line'} :param categories: Create category metadata for uncertainy mechnisms. The default is {'Type': 'A', 'Origin':'Repeatability'}. :type categories: dict, optional :param umech_id_basename: Basename for the umech_id generated. :type umech_id_basename: str, optional :param frequencies: If provided, will apply the repeatability model to the provided frequencies. :type frequencies: np.array, optional :returns: * **hist_model** (*RMEMeas*) -- RMEMeas object of eff centered at 0 with uncertainties describing historical repeatability. Can be added to an effective efficiency measurement to add repeatability uncertainties. * **fig** (*plt.Figure*) -- Figure reporting the model. None if no figure * **coeffs** (*RMEMeas*) -- Fit coefficients generated from the repeatability model. .. !! processed by numpydoc !! .. py:function:: make_classical_eta_unc_model(frequency: numpy.array, model: microcalorimetry.configs.PythonFunction, u_type: str, correlate_frequencies: bool = True, make_plots: bool = True) -> tuple[rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.Eta], matplotlib.pyplot.Figure] Generate a classical uncertainty model for an eta measurement. uA_model and uB_model are python functions that take in a frequency list and output a standard uncertainty (Type A and B respectively). This model can be used to apply uncertainties to an eta calculate after it has been calculated. Is is zero nominal, so uncertainties are added to an eta measurement by simply adding it to to an effective efficiency measurement. Uncertainties are assumed to be independent across frequency. :param frequency: Frequency in GHz. :type frequency: np.array :param model: Python function that outputs type B uncertainty. :type model: configs.PythonFunction :param u_type: Type of uncertainty (A or B) :type u_type: str :param correlate_frequencies: Treat uncertainties as correlated if True. The default is True. :type correlate_frequencies: bool, optional :param make_plots: If True, make plots. :type make_plots: bool, optional :returns: * **eta_unc** (*RMEMeas[arrays.Eta]*) -- Eta configuration object with zero nominal and uncertainties derived from uA_model and uB_model. * **fig** (*plt.Figure | None*) -- Matplotlib figure object generated. .. !! processed by numpydoc !! .. py:function:: dc_lead_correction(eta: microcalorimetry.configs.EtaLike, R_lead: float, R_bolo: float, R_lead_min_coverage: float = 0.14) -> tuple[rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.Eta]] Applies a dc lead correction. Corrects for heat lost between the dc connector and the 4-wire connection of a resistor inside the sensor. See ERROR IN CALORIMETRIC EFFECTIVE EFFICIENCY MEASUREMENTS DUE TO DC LOSSES, T.P Crowley and B.F. Riddle for more details. :param eta: Path to an effective efficiency measurement to apply the correction to. :type eta: configs.EtaLike :param R_lead: Sum of resistance for Force and Sense leads of sensor, positive and negative sides. :type R_lead: float :param R_bolo: Bolometer resistance, usually 200 ohms for bolometer sensors. :type R_bolo: float :param R_lead_min_coverage: Uncertainties applied as a result of the dc lead correction will cover a minimun lead resistance of this value. If the lead resistance is greater than this value, then the associated uncertainty will be calculated useing the provided R_lead. The default value is 0.14 Ohms. :type R_lead_min_coverage: float, optional :returns: **eta** -- Corrected eta value :rtype: RMEMeas[arrays.Eta] .. !! processed by numpydoc !! .. py:function:: apply_uncertainty_model(eta: microcalorimetry.configs.EtaLike, model: microcalorimetry.configs.EtaLike, make_unique: bool = False) -> rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.Eta] Applies uncertainty models of effective efficiency measurements. Uncertainties are applied by adding model to eta, assuming model is zero nominal. :param eta: Eta that will have unertainties applied. :type eta: configs.EtaLike :param model: Model of uncertainties that will be applied to eta. Should be nominaly zero. :type model: configs.EtaLike :param make_unique: If True, renames all uncertainty mechanisms so they are unique and independent from all other uncertainty mechanisms. Should be set to True for repeatability models. :type make_unique: bool, optional :returns: **eta** -- Same nominal as the input eta, but with new uncertainties. :rtype: RMEMeas[arrays.Eta] .. !! processed by numpydoc !! .. py:function:: compression_check(power: microcalorimetry.configs.RFSweepLike, power_minus_1dB: microcalorimetry.configs.RFSweepLike, k: int = 2) -> tuple[rmellipse.uobjects.RMEMeas[microcalorimetry.arrays.RFSweep], matplotlib.pyplot.Figure] Check the compression ratio of of a measurement. Requires a parsed rfsweep at desired power, and another at the same frequency list backed off on the source by 1 dBm. :param power: Power of sensor at desired output. :type power: configs.RFSweepLike :param power_minus_1dB: Power measured by sensor backed off by 1dB at source from desired output. :type power_minus_1dB: configs.RFSweepLike :param k: Expansion factor to plot. The default is 2. :type k: int, optional :returns: * **compression_ratio** (*RMEMeas[arrays.RFSweep]*) -- Compression ratio. * **fig** (*plt.Figure*) -- Figure object. .. !! processed by numpydoc !!