Module TrendAnalysis

Make a diagnostic plot for a series of stars, where Imb for transitions of a given molecule are compared with their upper level energies.

Line strengths are always scaled with distance squared. Additional scaling can be requested.

Three plots are made: One with scaling versus distance and two with scaling versus distance and the CO line strength of the J=15-14 and J=30-29 lines respectively. The comparison with CO line strengths is not scaled except with distance.

Parameters:

• sg (list[Star()]) - The stellar models, in which the transitions have been matched with integrated line strengths.
• molec (str) - The molecule for which this is done, shorthand notation.
• scaling (list[string]) - Scale the line strengths also with a keyword given here. 'MDOT_GAS', etc. Assumes a Star() object knows the keyword.

  (default:[])

• combine_water (bool) - Combine both ortho and para water in a single plot

  (default: 0)

• edists (list[float]) - Include errors for distance estimates of stars here.

  (default: [])

• escaling (list[list]) - Include relative errors of extra scaling parameters as lists. len is len of scaling, len of an element is len of sg

  (default: [])

• pfn_path (str) - Output folder for diagnostic plots. Default if to be stored locally.

  (default: '')

Make a diagnostic plot of either measured line strengths or intrinsic parameters versus measured line strengths or intrinsic parameters.

Ratios are possible for line strengths. Not for intrinsic parameters.

Requires preparatory work done for the Pacs() and the Star() objects.

Parameters:

• sg (list[Star()]) - The stellar models, in which the transitions have been matched with integrated line strengths. If both models and data are combined, the data Star() objects are assumed to be listed first.
• xpar (string/int) - The parameter on the x-axis. Can be either a string (Star() keyword), or an index (of the transition in the first object in the sg list) for line strengths, or a float giving the wavelength of the continuum point. When looking at line strengths in a combo mode (cint or ctmb) this means it is the index in the transition list of the data objects rather than the model objects. Transitions in objects other than the first 1 can have different indices. Note the essential difference between floats and integers!
• ypar (string/int) - The parameter on the y-axis. Can be either a string (Star() keyword), or an index (of the transition in the first object in the sg list) for line strengths, or a float giving the wavelength of the continuum point. When looking at line strengths inn a combo mode (cint or ctmb) this means it is the index in the transition list of the data objects rather than the model objects. Transitions in objects other than the first 1 can have different indices. Note the essential difference between floats and integers!
• xratios (list[int/str]) - If xpar is a line strength or a continuum point, multiple ratios can be requested to be plotted in succession. Therefore, this gives the indices (if int, refers to the 1st Star() object in sg) or 'mdot' (if ratio wrt Mdot) or float (in case of a continuum wavelength point) for the x-axis ratio.

  (default: [])

• yratios (list[int/str]) - If ypar is a line strength, multiple ratios can be requested to be plotted in succession. Therefore, this gives the indices (if int, refers to the 1st Star() object in sg) or 'mdot' (if ratio wrt Mdot) or float (in case of a continuum wavelength point) for the y-axis ratio

  (default: [])

• emdot (list[float]) - Include errors for the x/yratio quantity if it is mdot. Not used for error estimation on mdot as a parameter! The mdot errors are given in log scale.

  (default: [])

• expar (array) - The error on the x-parameter if it is a Star() key and if mode is cint or dint. Number of entries in array is equal to the number of data Star() objects.

  (default: [])

• eypar (array) - The error on the y-parameter if it is a Star() key and if mode is cint or dint. Number of entries in array is equal to the number of data Star() objects.

  (default: [])

• exparlog (bool) - The xpar error is given in logscale. Only relevant for the d and c modes.

  (default: 0)

• eyparlog (bool) - The ypar error is given in logscale. Only relevant for the d and c modes.

  (default: 0)

• edists (list[float]) - Include errors for distance estimates of stars here. These distances are only used to rescale line strengths if they are not in a ratio.

  (default: [])

• mode (str) - The mode in which line strengths are selected, ie either from data or from models. Either 'dint', 'mint', 'mtmb' or 'dtmb' values. A combination of both is possible by setting this key to 'cint' or 'ctmb'. Then the extra keyword 'n_data' is required, which indicates how many Star() objects are associated with data. The method assumes they are the first objects in the list of Star() objects. In case only continuum wavelengths are requested (a combination is possible!), only the first letter really matters.

  (default: 'dint')

• n_data (int) - The number of data Star() objects, assuming they are the first in the star_grid. Only required if mode == 'combo'. This number, if given, must be equal to the number of seds, if given.

  (default: 0)

• extra_mpar (list[string]) - If extra conditional parameters are requested for models, the plot is colour coded based on them. For instance, Star() object keywords can serve as conditionals. Note that these are only applied when mode == mtmb, mint, cint or ctmb.

  (default: [])

• extra_dpar (list[string]) - If extra conditional parameters are requested for data, the plot is colour coded based on them. For instance, Star() object keywords can serve as conditionals. Note that these are only applied when mode == dtmb, dint, cint or ctmb.

  (default: [])

• seds (list[Sed()]) - The SEDs of the data objects. Only used when xpar or ypar is a float (and thus continuum points are required). The number of SEDs given must be equal to n_data, or the number of Star() objects if mode[0] == 'd'. An error is thrown otherwise.

  (default: [])

• deredden (bool) - Deredden the SEDs before plotting, in case of continuum flux points. This is never done in case only one data object is given and reddening is requested in models to avoid double correction.

  (default: 0)

• cfg (string/dict) - config filename read as a dictionary, can replace any keyword given to plotCols. Can also be a dictionary itself, in which case no file is read and the kwargs are updated with the content of cfg

  (default: '')

• add_linear_fit (bool) - Add a linear fit to the figures. The fit is done through corrSG method, of which extra arguments can be given in kwargs. (xpar_co, ypar_co) Only works in dint or cint mode if xratios or yratios has len less than 2.

  (default: 0)

• pfn_path (str) - Output folder for diagnostic plots. Default if to be stored locally.

  (default: '')

• alf_xmin (float) - The minimum x value for the linear fit plot, if requested. (This is not the cut off value for the fitting routine itself!) Has to be given if a linear fit is requested.

  (default: None)

• alf_xmax (float) - The maximum x value for the linear fit plot, if requested. (This is not the cut off value for the fitting routine itself!) Has to be given if a linear fit is requested.

  (default: None)

• **kwargs (dict) - extra keywords needed for the linear fit, if requested.

Returns: str

The filename of the produced plot is returned.

Guess a ratio of given values with error bars a given number of times.

For both components of the ratio, values are drawn from a Gaussian distribution around the given value, with the error as sigma.

Can be used for error analysis, or for estimating errors on ratios in case the errors on the separate components are difficult to propagate properly.

The option to guess a value within error bars in log space is possible. The resulting value is then converted back to linear space, after which the ratio is taken.

Negative values can occur, due to the Gaussian nature of the guesses. Keep this in mind when taking the log of output values. If you do not want negative values, this van be requested via the positive keyword.

A guess of the ratio, and a standard deviation, can be calculated by taking the mean and std of the columns in the ouput array.

Parameters:

• line1 (array) - Values of the first parameter on the y-axis
• line1_err (array) - Uncertainties on line1, assuming they are in a normal distribution (1-sigma)
• line2 (array) - Values of the second parameter on the y-axis. Can be an empty array in case you want to fit a correlation between par and line1 without any ratio involved. Pass an empty array if you simply want to randomize a single array, instead of a ratio.
• line2_err (array) - Uncertainties on line2, assuming they are in a normal distribution (1-sigma)
• line1_log (bool) - If line 1 is in log scale. In the ratio, 10**line1 is then taken.

  (default: 0)

• line2_log (bool) - if line 2 is in log scale. In the ratio, 10**line1 is then taken.

  (default: 0)

• n_fit (int) - The number of times the correlation is fitted.

  (default: 10000)

• positive (bool) - In some cases, you may want to disallow negative values, eg when you take the log of the results. This switch allows you to exclude negative values from the output. Use this with caution! In some case, this will severely affect the Gaussian distribution.

  (default: 0)

Returns: array((n_fit,len(line1)))

The n_fit guesses of the requested ratio.

Fit a polynomial to a data set.

The data set can consist of straight up values or of ratios on both the x and y axis (in log space).

Takes into account errors in both dimensions.

Can be used for e.g. error estimation on a correlation.

Parameters:

• par1 (array) - Values of the first parameter on x-axis.
• par1_err (array) - Uncertainties on par, assuming they are in a normal distribution (1-sigma)
• par2 (array) - Values of the second parameter on the x-axis. Can be an empty array in case you don't want a ratio on the x-axis.
• par2_err (array) - Uncertainties on par2, assuming they are in a normal distribution (1-sigma)
• line1 (array) - Values of the first parameter on the y-axis
• line1_err (array) - Uncertainties on line1, assuming they are in a normal distribution (1-sigma)
• line2 (array) - Values of the second parameter on the y-axis. Can be an empty array in case you don't want a ratio on the x-axis.
• line2_err (array) - Uncertainties on line2, assuming they are in a normal distribution (1-sigma)
• par1_log (bool) - If par is in log scale. If not, the log will be taken of par, since this method fits log log correlations.

  (default: 0)

• par2_log (bool) - If par2 is in log scale. If not, the log will be taken of par2, since this method fits log log correlations.

  (default: 0)

• line1_log (bool) - If line 1 is in log scale. In the ratio, 10**line1 is then taken.

  (default: 0)

• line2_log (bool) - if line 2 is in log scale. In the ratio, 10**line1 is then taken.

  (default: 0)

• n_fit (int) - The number of times the correlation is fitted.

  (default: 10000)

• poly_degree (int) - The degree of the polynomial that is fitted.

  (default: 1)

• show (bool) - Show a plot with the results. If cfg is given, the plot is adapted, including the filename.

  (default: 0)

• fn_plt (str) - The filename of the plot, in case show is True, and a saved plot is requested.

  (default: '')

• x_for_yratio (bool) - Use the par grid as the second component in the y ratio. This can be useful for instance if the ratio has Mdot as numerator, while Mdot is also on the x axis. In this case, you want to use the same random value for the same point on both x and y.

  (default: 0)

• y_for_xratio (bool) - Use the line1 grid as the second component in the x ratio. This can be useful for instance if the ratio has Mdot as numerator, while Mdot is also on the y axis. In this case, you want to use the same random value for the same point on both x and y.

  (default: 0)

Returns: array

The fit results are returned for all n_fit fitted functions. The parameters are the output of np.polyfit and the amount depends on the polynomial degree.

Tool for selecting data from a star_grid. Mainly used by corrStarGrid() to define input arrays for the correlation study.

Parameters:

• sg (list[Star()]) - The grid of Star() objects.
• par (str/int) - The requested parameter. If a string, a Star() keyword is used and if MDOT_GAS then the error bars are set as log10(3)/3. If an integer, it is the index of a Transition() in the Star() and the line strength and -error on it- of the line is taken.
• epar (array) - The 1-sigma error bar of the parameter. Only relevant if par is a string Star() keyword that is not MDOT_GAS.
• par_co (array) - Define cutoff values here. Always given as an array of size 2. If a lower and/or upper boundary is not needed, it is set as None. In case of MDOT_GAS==xpar, these values are converted to log scale. Can be set as None if no cutoff is needed. Only relevant if par is a string.

  (default: None)

• edist (array) - Give the relative error of the distance here. Used to estimate an uncertainty on the rescaled line strengths according to distance (down to 100 pc). Not relevant when par is a string. An empty array implies no scaling.

  (default: [])

Returns: (arr,arr,arr,bool)

The values for the requested parameter, as well as the uncertainty, the cutoff values and the log request, ie all keywords needed for the fitCorrPolyLog method.

A method focused on finding correlations between parameters and/or data of multiple Star() objects.

Parameters:

• sg (list[Star()]) - The grid of Star() objects.
• xpar (str/int) - The parameter on x-axis. If a string, a Star() keyword is used and if MDOT_GAS then the error bars are set as log10(3)/3. If an integer, it is the index of a Transition() in the Star() and the line strength and -error on it- of the line is taken. If the same as yratio, the same guesses are used for both.
• ypar (int/str) - The parameter on y-axis. If a string, a Star() keyword is used and if MDOT_GAS then the error bars are set as log10(3)/3. If an integer, it is the index of a Transition() in the Star() and the line strength and -error on it- of the line is taken. If the same as xratio, the same guesses are used for both.
• expar (array) - The 1-sigma error bar of the parameter on the xaxis. Only relevant if xpar is a string Star() keyword that is not MDOT_GAS.

  (default: [])

• eypar (array) - The 1-sigma error bar of the parameter on the yaxis. Only relevant if ypar is a string Star() keyword that is not MDOT_GAS.

  (default: [])

• xratio (int/str) - If a ratio on the x-axis is requested, this is the second component. Input syntax same as xpar.

  (default: None)

• exratio (array) - The relative error bars on the xratio parameter are given here. Only relevant if xratio is a string Star() keyword that is not MDOT_GAS.

  (default: [])

• yratio (int/str) - If a ratio on the y-axis is requested, this is the second component. Input syntax same as ypar.

  (default: None)

• eyratio (array) - The relative error bars on the yratio parameter are given here. Only relevant if yratio is a string Star() keyword that is not MDOT_GAS.

  (default: [])

• edist (array) - Give the relative error of the distance here. Used to estimate an uncertainty on the rescaled line strengths according to distance (down to 100 pc). Not relevant when a line ratio is requested.

  (default: [])

• xpar_co (array) - Define cutoff values here. Always given as an array of size 2. If a lower and/or upper boundary is not needed, it set as None. In case of MDOT_GAS==xpar, these values are converted to log scale.

  (default: array(None,None))

• ypar_co (array) - Define cutoff values here. Always given as an array of size 2. If a lower and/or upper boundary is not needed, it set as None. In case of MDOT_GAS==ypar, these values are converted to log scale.

  (default: array(None,None))

• kwargs (dict) - Extra keywords relevant for fitLinearCorr or fitCorrPolyLog

Returns: dict()

The resulting fit parameters are returned. NYI if poly_degree!=1.