Tools and helpers for thermogravimetric (TG) analysis workflows, including Coats–Redfern (CR) ramp fits, isothermal extraction, and report-ready plots. This README documents the main functions and the simplest execution paths through the codebase.

The simplest way to run the analysis is to execute main.py, which drives the entire pipeline.

main.py:main()
  -> tg_loader.load_all_thermogravimetric_data(BASE_DIR, SPEC)
  -> report_data_helper.run_char(char, char_data, cfg)
       -> tg_math.estimate_global_coats_redfern_with_o2(...)  # CR fits
       -> tg_helpers.compare_cr_to_char_isothermals(...)      # CR vs iso
       -> tg_helpers.fit_isothermal_global_from_char_data(...) # iso global
       -> tg_helpers.compare_cr_vs_isothermal_global_on_isothermals(...)
       -> report_data_helper.build_hold_usability_table(...)
       -> tg_plotting.plot_global_coats_redfern_o2_fit(...)
  -> tg_helpers.simulate_isothermal_holds_from_cr(...)        # optional
  -> tg_helpers.plot_linear_ramp_overlays_from_cr(...)        # optional
  -> report_data_helper.create_tg_graphs_all(...)             # optional
  -> report_data_helper.create_tg_plots_last_segment_all(...) # optional

Outputs:

• out/<char>/tables/ – CSV/LaTeX tables for CR fits, iso extraction, and comparisons.
• out/<char>/figures/ – CR overlays, TG curves, and diagnostic plots.
• out/summary_fit_params.csv – cross-characterization summary.

Purpose: Configure the global analysis, run every characterization, and collect summary outputs.

• main() – Orchestrates the pipeline. Reads TG data, runs run_char per feedstock, optionally generates simulated overlays and TG graphs.

Purpose: Load raw TG data from Excel/CSV into consistent dataframes.

• load_thermogravimetric_data(path) – Load a single dataset file (Excel/CSV) into a normalized dataframe.
• load_all_thermogravimetric_data(base_dir, spec) – Walk the configured directory tree and return a nested dict keyed by characterization name and regime (e.g., linear, isothermal_225). This is the entry point used by main().

Purpose: High-level report generation and per-characterization workflows.

• ReportConfig – Configuration dataclass for ramp windows, conversion settings, and section toggles.
• run_char(char, char_data, cfg=None) – Primary per-characterization pipeline. Creates output directories, performs CR fits, compares to isothermal data, and writes tables/plots. Returns a dict of results (CR fits, iso fit, comparison tables).
• plot_cr_vs_isothermal_k_table_local(tbl, title, save_prefix, ...) – Local plotting helper for CR-vs-isothermal comparisons.
• build_hold_usability_table(char_name, tbl_cr_vs_iso, raw_char_data, ...) – Builds a compact table indicating whether isothermal holds show measurable oxidation.
• create_tg_graphs_for_char(...) / create_tg_graphs_all(...) – Generate TG conversion curves for one or all characterizations.
• create_tg_plots_last_segment_all(...) – Plot the last segment of each TG run for quick inspection.

Purpose: Utility helpers around conversion windows, isothermal extraction, CR prediction, and simulation.

Key functions:

• compare_cr_to_char_isothermals(cr_fit, char_data, ...) – Extract isothermal holds and compare observed k values to CR-predicted k for a characterization.
• fit_isothermal_global_from_char_data(char_data, ...) – Global Arrhenius fit for isothermal data for a single characterization.
• compare_cr_vs_isothermal_global_on_isothermals(cr_fit, iso_fit, tbl) – Compare CR predictions to the global isothermal fit at isothermal conditions.
• infer_isothermal_time_window(df, ...) / refine_window_to_mass_peak(...) – Identify usable time windows inside isothermal holds.
• simulate_isothermal_holds_from_cr(cr_fit, char_data, ...) – Simulate isothermal conversion using CR parameters and compare to observed data.
• plot_linear_ramp_overlays_from_cr(cr_fit, char_data, ...) – Simulate ramp curves at specified O2 fractions and overlay them on observed data.

Purpose: Numerical fitting and thermokinetic calculations.

Core functions used in the default pipeline:

• estimate_global_coats_redfern_with_o2(ramp_dfs, o2_fractions, ...) – Global CR fit over ramp datasets with O2 dependence. Returns the parameters used in run_char.
• estimate_global_arrhenius_with_o2_from_isothermal_datasets(...) – Fit Arrhenius parameters from isothermal datasets with oxygen-order dependence.
• simulate_alpha_ramp(...) – Simulate conversion vs time for a linear ramp.
• alpha_to_mass_pct(...) / compute_dtg_curve(...) – Utility conversions between alpha, mass, and derivative TG signals.

Purpose: Plotting utilities for CR fits, Arrhenius trends, TG curves, and comparison visuals.

Common entry points:

• plot_global_coats_redfern_o2_fit(res, save_path, title) – CR diagnostic overlay for global fits.
• plot_tg_curve_time(df, ...) / plot_Xc_curve_time(df, ...) – TG conversion curves vs time.
• plot_coats_redfern_global(...) / plot_coats_redfern_overlays(...) – CR plots across datasets or windows.

Run the full pipeline (expects TG data in TG_Data/):

python main.py

Outputs land in out/.