Note
Go to the end to download the full example code.
Exporting Model Results¶
This example covers utilities for extracting and exporting model fit results.
Note that the functionality to export to pandas DataFrames was added in version 1.1, and requires the optional dependency pandas to be installed.
# Import model objects, and Bands object to define bands of interest
from specparam import SpectralModel, SpectralGroupModel, Bands
# Import simulation functions to create some example data
from specparam.sim import sim_power_spectrum, sim_group_power_spectra
Exporting Results¶
In this example we will explore available functionality for extracting model fit results, specifically the options available for exporting results to pandas objects.
Note that the main use case of exporting models to pandas DataFrames is for
analysis across models. If you are just trying to access the model fit results from
a fit model, you may want the get_results() and/or
get_params() methods.
Defining Oscillation Bands¶
A difficulty with exporting and collecting model results across model fits is that the models may be different sizes - most notably, they may contain different numbers of peaks.
This means that we need to define some kind of strategy to organize the peak
parameters across different models. Across these examples, this will include using the
Bands object to define oscillations bands of interest.
# Initialize bands object, defining alpha band
bands1 = Bands({'alpha' : [7, 14]})
# Initialize model object
fm = SpectralModel()
# Simulate example power spectrum
freqs, powers = sim_power_spectrum([1, 50], [0, 10, 1], [10, 0.25, 2], freq_res=0.25)
# Fit model to power spectrum
fm.fit(freqs, powers)
The to_df() method supports exporting model
fit results to pandas objects.
# Export results
fm.to_df(None)
offset -0.893708
exponent 0.489264
error 0.026236
r_squared 0.979900
dtype: float64
In the above, we export the model fit results to a pandas Series.
Note that we explicitly passed in None to the peak_org argument, meaning we did not define a strategy for managing peaks. Because of this, the export did not include any peak parameters.
Next, let’s can try exporting again, this time passing in an integer to define the number of peaks to extract.
# Export results - extracting 1 peak
fm.to_df(1)
offset -0.893708
exponent 0.489264
cf_0 10.164700
pw_0 0.311485
bw_0 5.726545
error 0.026236
r_squared 0.979900
dtype: float64
Using Band Definitions¶
In the above, we extract the results specifying to extract 1 peak. By default, this approach will extract the dominant (highest power) peak.
Notably, specifying a set number of peaks to extract does allow for combining across peaks (in terms of enforcing the same model size), but may not be the ideal way to examine across peaks (since the dominant extract peak may vary across model fits).
Therefore, we may often want to instead define a set of band definitions to organize peaks, as can be done by passing a Bands object in to the to_df method.
offset -0.893708
exponent 0.489264
alpha_cf 10.164700
alpha_pw 0.311485
alpha_bw 5.726545
error 0.026236
r_squared 0.979900
dtype: float64
Note that there are limitations to using the bands definitions - notably that doing so necessarily requires extracting at most 1 peak per band. In doing so, the extraction will select the dominant peak per band. However, this may not fully reflect the full model fit if there are, for example, multiple peaks fit within a band.
Example on Group Object¶
In the above, we used the model object to show the basic exporting functionalities.
This functionality is more useful when considering multiple model fits together, such
as can be done using the to_df() method from the Group object,
which allows for exporting DataFrames of organized model fit parameters across power spectra.
As with the above, keep in mind that for some cases you may want the
get_results() and/or
get_params() methods instead of doing a DataFrame export.
# Simulate an example group of power spectra
freqs, powers = sim_group_power_spectra(5, [1, 50], [0, 1], [10, 0.25, 2])
# Initialize a group model object and fit power spectra
fg = SpectralGroupModel(verbose=False)
fg.fit(freqs, powers)
# Export results to dataframe, with no peak definition
fg.to_df(None)
# Export results to dataframe, specifying to export a single peak
fg.to_df(1)
In the above examples, we showed the same exports on the Group object as we previously explored on the single spectrum in the model object.
Note that we can also define new bands objects to change the peak output organization, as demonstrated in the following example.
That covers the pandas export functionality available from the model objects.
Total running time of the script: (0 minutes 0.171 seconds)