API overhaul about fooof

[parenthetical-e]

(e)

On Dec 20, 2017, at 8:56 AM, Tom ***@***.***> wrote: Suggested API overhaul, responding to point 1 in #53 <#53>: I've gone back and forth on this a little in my mind, and I think it comes down to the appropriate level of abstraction to use. Part of it comes down to how we recommend thinking about 'oscillations', and I think we've sort of broken that abstraction, in that at times we do sort of need people to acknowledge that fitting gaussians != (separate) oscillations. That said, I think I've come around to 'peaks'. We have two components to the fit: 'background' and 'peaks'. We don't need to imply that 'peaks' == 'oscillations', that's a layer of interpretation left to the user (and again, the main issue is that overlapping gaussians may be used to constitute what we would otherwise want to call '1 oscillation'), but we can talk about 'peaks' consistently, as a middle ground, without having to talk about 'below' (gaussians) or 'above' (oscillations). This does abstract away the gaussian aspect, helpfully, in so far as there is nothing fundamental about gaussians being used here (and this could even change in the future).

Before recommending some of these, I spent a while pondering this exact abstraction. I chose peaks for just the reasons you say. I very seriously considered putting oscillations throughout. But 1. I didn’t want to claim that and 2. one syllable (peaks) is much better than oscillations (4) in reading/thinking about the arguments. I will say, it does bother me still that we talk about peaks, but FOOOF is named for oscillations.

Now this is a pretty total API overhaul, slightly annoying to anyone who has started on our current version but, oh well, still better to do this now.

Yeah, breaking this much sucks. Let’s make sure it is worth it.

Note: following sklearn, the trailing are reserved for results from fitting the model. Everything below is the API for the FOOOF object (public & private), except for the FOOOFGroup particulars at the end. I don't think this overhaul effects any external functions within the fooof module, but after we settle this here, I'll do a run through of the rest to make sure it's all consistent. This is like, legitimately, the last thing - so please tear it apart, and then I'll push through the last things, and update everything with that. So, full API description, and planned overhaul: Settings (public attributes) amp_std_thresh -> min_peak_threshold This is an amplitude threshold for peaks, defined in terms of standard deviation of the flattened spectrum. Any clearer suggestions for name are welcome. bandwidth_limits -> peak_width_limits bg_use_knee -> background_mode Turn into a string. Options: 'knee', 'fixed'. max_n_gauss -> max_n_peaks min_amp -> min_peak_amplitude verbose -> same Data (public attributes) freqs -> same freq_range -> same Note: This is used to select a frequency range (FOOOF can trim PSDs), so useful / important, I think. freq_res -> same Note: Only used internally, but (I think) useful to have, as it's quite relevant to fit / settings. psd -> power_spectrum Well, you maybe shouldn't FOOOF raw fft's (they probably aren't smooth enough), but sure, lets go a little more general / verbose. Model fit results (public attributes) background_params_ -> same error_ -> rmse_error_ Be a bit more descriptive. oscillation_params_ -> peak_params_ psd_fit_ -> fooofed_psd_ My only nitpicky hesitation here is I think of a FOOOFed PSD as representing the model, as in the parameters results, where as this is more a representation/instantiation of a FOOOFed PSD, but sure, we can run with it.

I agree Tom. I spent a while trying to come us with something that obviously implies that this is the fooof approximated spectrum (that isn’t `fooof_approx_spectrum_`). And, BTW, we are dropping psd above so should change that as well. Perhaps `fooofed_spectrum`?

r2_ -> r_squared Be a bit more descriptive. (It's R^2 of the fit, not r^2 error.) Public Methods add_data -> same add_results -> same create_report -> save_report I sorta don't like how this makes it similar, and un-cleanly differentiated from 'save', but it is more specific... fit -> same load -> same get_results -> same plot -> same print_report_issue -> same print_results -> same print_settings -> same report -> same save -> same

:thumbs up:

Private Methods: _add_from_dict -> same _bg_fit_func -> same _check_bw -> same _check_loaded_results -> same _check_loaded_settings -> same _clear_settings -> same _clean_background_fit -> _robust_bg_fit Quick & Clean are not super description labels for bg-fitting. Robust, as this deals with outliers. Update to consistently use 'bg' in private methods/attributes. _create_bg_fit -> same _create_osc_fit -> _create_peak_fit _create_osc_params -> _create_peak_params _drop_osc_cf -> _drop_peak_cf _drop_osc_overlap -> _drop_peak_overlap _fit_osc_guess -> _fit_peak_guess _fit_oscs -> _fit_peaks _infer_knee -> _infer_bg_mode _prepare_data -> same _quick_background_fit -> _simple_bg_fit Quick & Clean are not super description labels for bg-fitting. Simple, as in 'non-robust'. Update to consistently use 'bg' in private methods/attributes. _r_squared -> _calc_r_sqaured Make more action-oriented, to emphasize it's a method, not an attribute. _regenerate_model -> same _reset_data -> same _reset_settings -> same _rmse_error -> _calc_rmse_error Make more action-oriented, to emphasize it's a method, not an attribute. Private Attributes: Note: mixture of private settings and intermediate model stuff. _background_fit -> _bg_fit For consistency, use 'bg' for all private methods/attributes. _bg_amp_thresh -> same _bg_bounds -> same _bg_guess -> same _bw_std_edge -> same _cf_bound -> same _gaussian_params -> same _oscillation_fit -> _peak_fit _psd_flat -> _spectrum_flat _psd_osc_rm -> _spectrum_peak_rm _std_limits -> same FOOOFGroup Particulars: _fit -> same _get_results -> same _reset_group_results -> same get_all_data -> same get_fooof -> same group_results -> same psds -> power_spectra

:thumbs up:

…

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#59>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABIxh6DdUIdfyTPqxJw2EIaTNtCwrYj4ks5tCTxXgaJpZM4RIrcO>.

[TomDonoghue]

"I will say, it does bother me still that we talk about peaks, but FOOOF is named for oscillations."

DAMNIT. I hadn't even thought of that, and now it's going to bug me.
"Fitting-oscillation-&-one-over-f" in which we fit power spectra as a background process & peaks.
Oh well, name is grandfathered in now. FBPP doesn't have the same ring to it...

Anyways, thanks @parenthetical-e for checking over. Yep, it'll be 'fooofed_spectrum_', missed the update of that one from psd. I'll take this as your sign-off on to push the update.

@voytek : once you get a chance to check in, and sign-off on this (and/or make suggestions, etc), then I'll update the codebase, and fix up the tutorials accordingly.

[voytek]

I'm happy with the changes. Amused by the "peaks" v "oscillations" angst.

[parenthetical-e]

Voytek: A passion for _scientific_ _consistency_ is not **angst**!

…

On Dec 21, 2017, at 6:51 PM, Bradley Voytek ***@***.***> wrote: I'm happy with the changes. Amused by the "peaks" v "oscillations" angst. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#59 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/ABIxh3Ey7xuLUFsv3ZVJKWVVieUHaRPPks5tCxkWgaJpZM4RIrcO>.

[TomDonoghue]

Done in #61