plt_mcmc_ detailed function guide

Python Version License
astrogeofit.plt_mcmc_SR_per_num_knots()
plt_mcmc_SR_per_num_knots(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    x_axis_plot_limits: Optional[list],
    y_axis_plot_limits: Optional[list],
    ignore_weights: bool,
    types_of_saving: list,
    output_path: str,
)

Plot the inverse sedimentation rate (SR⁻¹) derived from MCMC simulations for different numbers of knots in the age-depth model.

This function loads the results of an AstroGeoFit analysis, specifically the MCMC sampling results for different age-depth model complexities (defined by number of knots). It visualizes the median inverse sedimentation rate profiles, confidence intervals, MAP estimates, and optionally the nominal model.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used for the AstroGeoFit analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the result files. If None, the default folder defined in the configuration file is used.

  • file_with_the_resultsstr or None

    Specific filename for the results. If None, a default filename is assumed.

  • x_axis_plot_limitslist or None

    Optional [xmin, xmax] for the depth axis. If None, limits are automatically inferred.

  • y_axis_plot_limitslist or None

    Optional [ymin, ymax] for the inverse SR axis. If None, limits are automatically inferred.

  • ignore_weightsbool

    If True, ignore the sampling weights when drawing MCMC samples.

  • types_of_savinglist of str

    List of file formats to save the resulting plot (e.g., [“png”, “pdf”]). If empty, the figure will not be saved.

  • output_pathstr

    Output path where the figure will be saved. If “default” or empty, the figures subfolder inside the output folder defined in the configuration file is used.

astrogeofit.plt_mcmc_aic_logprob_and_loglike_per_number_knots()
plt_mcmc_aic_logprob_and_loglike_per_number_knots(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    types_of_saving: list,
    output_path: str,
)

Plot AIC, Logprob and Loglike metrics for MCMC-inferred models with varying numbers of knots.

This function evaluates the model fit for each number of knots used in an age-depth model by calculating the Akaike Information Criterion (AIC) and the coefficient of determination (R²) using MCMC posterior samples. The metrics are plotted together using a dual y-axis plot.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used for the AstroGeoFit analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the result files. If None, the default folder specified in the configuration is used.

  • file_with_the_resultsstr or None

    Specific filename for the results. If None, the default name is assumed.

  • types_of_savinglist of str

    List of file formats in which to save the resulting plot (e.g., [“png”, “pdf”]).

  • output_pathstr

    Directory where the figure should be saved. If “default” or empty, it defaults to a figures folder inside the output folder defined in the configuration.

astrogeofit.plt_mcmc_aic_and_r2_per_number_knots()
plt_mcmc_aic_and_r2_per_number_knots(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    types_of_saving: list,
    output_path: str,
)

Plot AIC and R² metrics for MCMC-inferred models with varying numbers of knots.

This function evaluates the model fit for each number of knots used in an age-depth model by calculating the Akaike Information Criterion (AIC) and the coefficient of determination (R²) using MCMC posterior samples. The metrics are plotted together using a dual y-axis plot.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used for the AstroGeoFit analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the result files. If None, the default folder specified in the configuration is used.

  • file_with_the_resultsstr or None

    Specific filename for the results. If None, the default name is assumed.

  • types_of_savinglist of str

    List of file formats in which to save the resulting plot (e.g., [“png”, “pdf”]).

  • output_pathstr

    Directory where the figure should be saved. If “default” or empty, it defaults to a figures folder inside the output folder defined in the configuration.

astrogeofit.plt_mcmc_eccentricity_correlation_with_solution()
plt_mcmc_eccentricity_correlation_with_solution(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    t0_offset_range_plot: Optional[list],
    ecc_time_range: Optional[list],
    name_eccentricity_solution: Optional[str],
    types_of_saving: list,
    output_path: str,
)

Plot the results of eccentricity from MCMC runs and compare them with an astronomical solution.

This function generates a multi-panel figure showing: - The mean square weighted deviation (MSWD) across different t0 offsets. - The aligned time offset between relative and absolute time. - The fitted eccentricity envelope overlaid with a reference astronomical solution.

It also logs relevant metrics and saves the resulting figure in the specified formats.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used in the analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the MCMC result files. Can be None if file_with_the_results is provided.

  • file_with_the_resultsstr or None

    Specific path to a result file. Can be None if folder_with_the_results is provided.

  • t0_offset_range_plotlist or None

    Range of t0 offsets to evaluate MSWD. Should be a list of two floats [min_offset, max_offset]. If None, it is inferred from the nominal age model if available.

  • ecc_time_rangelist or None

    Time range for plotting the eccentricity envelope. If None, it’s automatically inferred from the dataset.

  • save_eccentricity_solutions: bool

    Flag indicating whether to save the reconstructed eccentricity solutions and their parameters to output files. If set to True, the function will generate:

    A .txt file containing the depth, age, proxy values, and statistical summaries (MAP, median, 5th, and 95th percentiles) of the eccentricity.

    A .sol file containing the frequency components, their amplitudes (beta coefficients), and phase information derived from the MAP (maximum a posteriori) solution.

    These files allow post-analysis use of the eccentricity time series, e.g., for replication, comparison, or modeling.

    If False, these outputs are skipped.

  • save_eccentricity_solutions_comment: str or None

    A user-defined comment or note to be included in the header of the saved eccentricity solution output files (e.g., .txt and .sol). This allows users to annotate saved results with context, version information, data origin, or other metadata

  • name_eccentricity_solutionstr or None

    Label for the astronomical solution being compared (e.g., “La2004”, “Astronomical Solution”). Default is “Astronomical Solution”.

  • types_of_savinglist

    List of formats in which to save the output figure (e.g., [‘pdf’, ‘png’]).

  • output_pathstr

    Directory where the output figures and logs should be saved. If ‘default’, uses the default output folder specified in the analysis configuration.

PRE-REQUISITES: This function needs the results of data_obtain_mcmc_results_per_a_number_of_knots.

astrogeofit.plt_mcmc_summary_of_results()
plt_mcmc_summary_of_results(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    x_axis_limits_peridogram: Optional[list],
    y_axis_limits_peridogram: Optional[list],
    peridogram_scale_x_axis: Optional[str],
    peridogram_scale_y_axis: Optional[str],
    x_axis_limits_depth: Optional[list],
    types_of_saving: list,
    output_path: str,
)

Generate a comprehensive summary plot from MCMC results in astrochronological analysis.

This function plots five panels:

  1. Spectral power analysis of log-likelihood for each number of knots.

  2. Median time model with 95% confidence interval.

  3. Inverse sedimentation rate over time with credible intervals.

  4. Fit of data in the time domain with posterior predictive samples.

  5. Decomposition of the ETP (Eccentricity, Tilt, Precession) signal using fitted knots.

The figure is saved in the specified formats and the output path is determined by the provided configuration.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used in the analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the MCMC result files. Can be None if file_with_the_results is provided.

  • file_with_the_resultsstr or None

    Specific path to a result file. Can be None if folder_with_the_results is provided.

  • x_axis_limits_peridogramlist or None

    Limits for the x-axis in the peridogram plot. Should be [min, max] in frequency units. If None, defaults are used.

  • y_axis_limits_peridogramlist or None

    Limits for the y-axis in the peridogram plot. Should be [min, max]. If None, auto-scaled from data.

  • peridogram_scale_x_axisstr or None

    Scale for the x-axis of the peridogram plot. Can be “linear” or “log”. Defaults to “linear”.

  • peridogram_scale_y_axisstr or None

    Scale for the y-axis of the peridogram plot. Can be “linear” or “log”. Defaults to “linear”.

  • x_axis_limits_depthlist or None

    Limits for the x-axis (depth) used in multiple plots. Should be [min_depth, max_depth]. If None, it spans the dataset range.

  • file_with_the_resultslist of str

    List of file formats to save the final plot. Supported formats include “png”, “pdf”, and “svg”. “tab” is ignored.

  • output_pathstr

    Path where the output plot should be saved. If “default”, it’s inferred from the configuration file.

PRE-REQUISITES: This function needs the results of data_obtain_mcmc_results_per_a_number_of_knots.

astrogeofit.plt_mcmc_prior_frequencies_distributions()
plt_mcmc_prior_frequencies_distributions(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    types_of_saving: list,
    output_path: str,
)

Plot the prior and posterior distributions of the frequencies explored by MCMC.

This function generates subplots of the marginal prior and posterior distributions for the different orbital frequencies (precession, obliquity, etc.) used in the astrochronological model. It overlays the MAP value, the current astronomical values, and posterior statistics such as the weighted median and standard deviation.

It also logs summary statistics (MAP, median, std) for each frequency and saves the plot in one or more formats.

Parameters:
  • configuration_file_pathstr

    Path to the YAML configuration file used to run the analysis.

  • folder_with_the_resultsstr or None

    Path to the folder containing the result files. If file_with_the_results is given, this can be None.

  • file_with_the_resultsstr or None

    Path to a specific result file. If provided, folder_with_the_results can be None.

  • file_with_the_resultslist

    List of file formats to save the plot in. Supported formats are image types like [‘png’, ‘pdf’, ‘svg’], etc. ‘tab’ is ignored with a warning.

  • output_pathstr

    Directory where the figure(s) and logs should be saved. If set to “default”, uses the default output folder specified in the configuration file.

PRE-REQUISITES: This function needs the results of data_obtain_mcmc_results_per_a_number_of_knots.

astrogeofit.plt_mcmc_phase_of_frequencies()
plt_mcmc_phase_of_frequencies(
    configuration_file_path:str,
    folder_with_the_results:Optional[str],
    file_with_the_results:Optional[str],
    types_of_saving: list,
    output_path: str
)

Generate and save a multi-panel plot showing the phases of orbital frequencies derived from MCMC solutions applied to astronomical time scale inference.

This function loads the results of an MCMC analysis (using AstroGeoFit), computes the phase of orbital frequencies (such as eccentricity, obliquity, and precession), and plots histograms of the sampled phase distributions along with the MAP (maximum a posteriori) and median values. It also logs summary statistics to a file.

Parameters:
  • configuration_file_pathstr

    Path to the configuration file used for the AstroGeoFit model run.

  • folder_with_the_resultsstr or None

    Path to the folder containing the output results of the MCMC run. Can be None if file_with_the_results is specified instead.

  • file_with_the_resultsstr or None

    Path to a specific result file to load instead of an entire folder. Can be None if folder_with_the_results is provided.

  • file_with_the_resultslist of str

    A list of file formats to save the final phase plot (e.g., [‘png’, ‘pdf’]). If ‘tab’ is included, it is ignored for this plot type.

  • output_pathstr

    Directory path to store the generated plot and the log file. If empty or set to “default”, the output directory defined in the configuration will be used.

PRE-REQUISITES: This function needs the results of data_obtain_mcmc_results_per_a_number_of_knots.