|
| 1 | +""" |
| 2 | +Exporting Model Results |
| 3 | +======================= |
| 4 | +
|
| 5 | +This example covers utilities for extracting and exporting model fit results. |
| 6 | +
|
| 7 | +Note that the functionality to export to pandas DataFrames was added in version 1.1, |
| 8 | +and requires the optional dependency `pandas` to be installed. |
| 9 | +""" |
| 10 | + |
| 11 | +################################################################################################### |
| 12 | + |
| 13 | +# Import model objects, and Bands object to define bands of interest |
| 14 | +from fooof import FOOOF, FOOOFGroup, Bands |
| 15 | + |
| 16 | +# Import simulation functions to create some example data |
| 17 | +from fooof.sim import gen_power_spectrum, gen_group_power_spectra |
| 18 | + |
| 19 | +################################################################################################### |
| 20 | +# Exporting Results |
| 21 | +# ----------------- |
| 22 | +# |
| 23 | +# In this example we will explore available functionality for extracting model fit results, |
| 24 | +# specifically the options available for exporting results to pandas objects. |
| 25 | +# |
| 26 | +# Note that the main use case of exporting models to pandas DataFrames is for |
| 27 | +# analysis across models. If you are just trying to access the model fit results from |
| 28 | +# a fit model, you may want the :meth:`~fooof.FOOOF.get_results` and/or |
| 29 | +# :meth:`~fooof.FOOOF.get_params` methods. |
| 30 | +# |
| 31 | +# Defining Oscillation Bands |
| 32 | +# ~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 33 | +# |
| 34 | +# A difficulty with exporting and collecting model results across model fits is that the |
| 35 | +# models may be different sizes - most notably, they may contain different numbers of peaks. |
| 36 | +# |
| 37 | +# This means that we need to define some kind of strategy to organize the peak |
| 38 | +# parameters across different models. Across these examples, this will include using the |
| 39 | +# :class:`~fooof.Bands` object to define oscillations bands of interest. |
| 40 | +# |
| 41 | + |
| 42 | +################################################################################################### |
| 43 | + |
| 44 | +# Initialize bands object, defining alpha band |
| 45 | +bands1 = Bands({'alpha' : [7, 14]}) |
| 46 | + |
| 47 | +# Initialize model object |
| 48 | +fm = FOOOF() |
| 49 | + |
| 50 | +################################################################################################### |
| 51 | + |
| 52 | +# Simulate example power spectrum |
| 53 | +freqs, powers = gen_power_spectrum([1, 50], [0, 10, 1], [10, 0.25, 2], freq_res=0.25) |
| 54 | + |
| 55 | +# Fit model to power spectrum |
| 56 | +fm.fit(freqs, powers) |
| 57 | + |
| 58 | +################################################################################################### |
| 59 | +# |
| 60 | +# The :meth:`~fooof.FOOOF.to_df` method supports exporting model fit results to pandas objects. |
| 61 | +# |
| 62 | + |
| 63 | +################################################################################################### |
| 64 | + |
| 65 | +# Export results |
| 66 | +fm.to_df(None) |
| 67 | + |
| 68 | +################################################################################################### |
| 69 | +# |
| 70 | +# In the above, we export the model fit results to a pandas Series. |
| 71 | +# |
| 72 | +# Note that we explicitly passed in `None` to the `peak_org` argument, meaning we did not define |
| 73 | +# a strategy for managing peaks. Because of this, the export did not include any peak parameters. |
| 74 | +# |
| 75 | +# Next, let's can try exporting again, this time passing in an integer to define the number |
| 76 | +# of peaks to extract. |
| 77 | +# |
| 78 | + |
| 79 | +################################################################################################### |
| 80 | + |
| 81 | +# Export results - extracting 1 peak |
| 82 | +fm.to_df(1) |
| 83 | + |
| 84 | +################################################################################################### |
| 85 | +# Using Band Definitions |
| 86 | +# ~~~~~~~~~~~~~~~~~~~~~~ |
| 87 | +# |
| 88 | +# In the above, we extract the results specifying to extract 1 peak. By default, this approach |
| 89 | +# will extract the dominant (highest power) peak. |
| 90 | +# |
| 91 | +# Notably, specifying a set number of peaks to extract does allow for combining across peaks |
| 92 | +# (in terms of enforcing the same model size), but may not be the ideal way to examine across |
| 93 | +# peaks (since the dominant extract peak may vary across model fits). |
| 94 | +# |
| 95 | +# Therefore, we may often want to instead define a set of band definitions to organize peaks, |
| 96 | +# as can be done by passing a `Bands` object in to the `to_df` method. |
| 97 | +# |
| 98 | + |
| 99 | +################################################################################################### |
| 100 | + |
| 101 | +# Export results - extracting peaks based on bands object |
| 102 | +fm.to_df(bands1) |
| 103 | + |
| 104 | +################################################################################################### |
| 105 | +# |
| 106 | +# Note that there are limitations to using the bands definitions - notably that doing so |
| 107 | +# necessarily requires extracting at most 1 peak per band. In doing so, the extraction will |
| 108 | +# select the dominant peak per band. However, this may not fully reflect the full model fit |
| 109 | +# if there are, for example, multiple peaks fit within a band. |
| 110 | +# |
| 111 | + |
| 112 | +################################################################################################### |
| 113 | +# Example on Group Object |
| 114 | +# ~~~~~~~~~~~~~~~~~~~~~~~ |
| 115 | +# |
| 116 | +# In the above, we used the model object to show the basic exporting functionalities. |
| 117 | +# |
| 118 | +# This functionality is more useful when considering multiple model fits together, such |
| 119 | +# as can be done using the :meth:`~fooof.FOOOFGroup.to_df` method from the Group object, |
| 120 | +# which allows for exporting DataFrames of organized model fit parameters across power spectra. |
| 121 | +# |
| 122 | +# As with the above, keep in mind that for some cases you may want the |
| 123 | +# :meth:`~fooof.FOOOFGroup.get_results` and/or :meth:`~fooof.FOOOFGroup.get_params` methods |
| 124 | +# instead of doing a DataFrame export. |
| 125 | +# |
| 126 | + |
| 127 | +################################################################################################### |
| 128 | + |
| 129 | +# Simulate an example group of power spectra |
| 130 | +freqs, powers = gen_group_power_spectra(5, [1, 50], [0, 1], [10, 0.25, 2]) |
| 131 | + |
| 132 | +# Initialize a group model object and fit power spectra |
| 133 | +fg = FOOOFGroup(verbose=False) |
| 134 | +fg.fit(freqs, powers) |
| 135 | + |
| 136 | +################################################################################################### |
| 137 | + |
| 138 | +# Export results to dataframe, with no peak definition |
| 139 | +fg.to_df(None) |
| 140 | + |
| 141 | +################################################################################################### |
| 142 | + |
| 143 | +# Export results to dataframe, specifying to export a single peak |
| 144 | +fg.to_df(1) |
| 145 | + |
| 146 | +################################################################################################### |
| 147 | + |
| 148 | +# Export results to dataframe, using bands definition with defines the alpha band |
| 149 | +fg.to_df(bands1) |
| 150 | + |
| 151 | +################################################################################################### |
| 152 | +# |
| 153 | +# In the above examples, we showed the same exports on the Group object as we previously |
| 154 | +# explored on the single spectrum in the model object. |
| 155 | +# |
| 156 | +# Note that we can also define new bands objects to change the peak output organization, |
| 157 | +# as demonstrated in the following example. |
| 158 | +# |
| 159 | + |
| 160 | +################################################################################################### |
| 161 | + |
| 162 | +# Define a new bands object, specifying both the alpha and beta band |
| 163 | +bands2 = Bands({'alpha' : [7, 14], |
| 164 | + 'beta' : [15, 30]}) |
| 165 | + |
| 166 | +################################################################################################### |
| 167 | + |
| 168 | +# Export results to dataframe, using bands object with alpha & beta |
| 169 | +fg.to_df(bands2) |
| 170 | + |
| 171 | +################################################################################################### |
| 172 | +# |
| 173 | +# That covers the pandas export functionality available from the model objects. |
| 174 | +# |
0 commit comments