Investigation Database Structure

This page describes the nested dictionary format used to store raw thermal analysis data, metadata, and results associated with the pyrolysis kinetics computations. This structure is initialized using initialize_investigation_skeleton() and modified by other functions like add_isothermal_tga(), combine_repetitions() or compute_Ea_KAS(). This data structure provides a standardised ordering of the data and allows the various functions to easily find the data they need, as well as provides a location where they can store their results.

Overview over the Structure

The dictionary is expected to collect data from a single set of related experiments, such as integral thermogravimetric analysis (TGA) runs using either isothermal or constant heating rate temperature programs.

Below is an example showing both temperature programs for illustration:

{
    "general_information": {
        "material": "Unobtainium",
        "investigator": "John Doe, Miskatonic University",
        "instrument": "ACME TGA 9000",
        "date": "Stardate: 42.69",
        "notes": "It has a colour out of space",
        "signal": {"name": "Mass", "unit": "mg"}
    },
    "experiments": {
        "TGA": {
            "isothermal": {
                "300_C": {
                    "raw": {
                        "Rep_1": pd.DataFrame,
                        "Rep_2": pd.DataFrame
                    },
                    "set_value": {"value": 300, "unit": "C"},
                    "data_type": "integral",
                    "combined": pd.DataFrame,
                    "conversion": pd.DataFrame,
                    "conversion_levels": pd.DataFrame
                },
                "350_C": { ... }
            },
            "constant_heating_rate": {
                "10_Kmin": {
                    "raw": {
                        "Rep_1": pd.DataFrame,
                        "Rep_2": pd.DataFrame
                    },
                    "set_value": {"value": 10, "unit": "K/min"},
                    "data_type": "integral",
                    "combined": pd.DataFrame,
                    "conversion": pd.DataFrame,
                    "conversion_levels": pd.DataFrame
                },
                "20_Kmin": { ... }
            },
            "Ea_results_KAS": pd.DataFrame
        }
    }
}

How to Populate this Structure

The structure can be initialized using initialize_investigation_skeleton(). At this stage, optional metadata such as material name, investigator, and signal description can already be provided.

Next, raw data from the experimental files must be read into Pandas DataFrames. These are added to the structure using add_isothermal_tga() or add_constant_heating_rate_tga(), depending on the temperature program used. The data will be stored under the appropriate program, set value (e.g., “300_C”), and repetition (e.g., “Rep_1”).

Use combine_repetitions() to merge repetitions for a given condition. This function computes the mean and standard deviation of the signal (e.g., mass) and sample temperature. It creates a new DataFrame that includes: - Time, - Raw values per repetition, - Averages, - Standard deviations.

This provides users with insight into intermediate processing steps and not just final results.

Conversion is calculated with compute_conversion(), which uses the combined data as input.

To enable isoconversional analysis, conversion levels must be interpolated across temperature programs. This is done via compute_conversion_levels().

Finally, apparent activation energies \(E_a\) can be determined—for example, using the Kissinger-Akahira-Sunose method with the Starink improvement by calling compute_Ea_KAS(). This function generates a new DataFrame with: - Conversion levels, - Apparent activation energies \(E_a\), - Linear fit coefficients, - Fit statistics such as RMSE and \(R^2\), - The data points used for each regression.

The specific columns may vary depending on the method used.