diff --git a/doc/api.rst b/doc/api.rst index f7c2f384..89d055dc 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -174,6 +174,17 @@ Metric Object Metric check_metrics +Metric Functions (GoF) +~~~~~~~~~~~~~~~~~~~~~~ + +.. currentmodule:: specparam.metrics.gof + +.. autosummary:: + :toctree: generated/ + + compute_r_squared + compute_adj_r_squared + Metric Functions (Error) ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -187,16 +198,31 @@ Metric Functions (Error) compute_root_mean_squared_error compute_median_abs_error -Metric Functions (GoF) -~~~~~~~~~~~~~~~~~~~~~~ +Metric Functions (Pointwise error) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. currentmodule:: specparam.metrics.gof +**Object Inputs** + +The following functions take in model objects directly. + +.. currentmodule:: specparam.metrics.pointwise .. autosummary:: - :toctree: generated/ + :toctree: generated/ - compute_r_squared - compute_adj_r_squared + compute_pointwise_error + compute_pointwise_error_group + +**Array Inputs** + +The following functions operate on arrays of models and data, which may be useful for more custom work-flows. + +.. currentmodule:: specparam.metrics.pointwise + +.. autosummary:: + :toctree: generated/ + + compute_pointwise_error_arr Data Objects ------------ @@ -276,51 +302,42 @@ An object for defining frequency band definitions. Bands -Measures --------- - -Functionality to analyze power spectrum models and the results parameters / components. - -Model Errors -~~~~~~~~~~~~ - -Functions for analyzing the error of model fits. +Parameters +---------- -**Object Inputs** +Functionality for working with and converting parameters. -The following functions take in model objects directly. +Converters +~~~~~~~~~~ -.. currentmodule:: specparam.measures.pointwise +.. currentmodule:: specparam.params.converter .. autosummary:: :toctree: generated/ - compute_pointwise_error - compute_pointwise_error_group - -**Array Inputs** + AperiodicParamConverter + PeriodicParamConverter -The following functions operate on arrays of models and data, which may be useful for more custom work-flows. +Aperiodic Parameters +~~~~~~~~~~~~~~~~~~~~ -.. currentmodule:: specparam.measures.pointwise +.. currentmodule:: specparam.params.aperiodic .. autosummary:: :toctree: generated/ - compute_pointwise_error_arr - -Parameters -~~~~~~~~~~ + compute_knee_frequency + compute_time_constant -Measures & utilities for working with and converting parameters. +Periodic Parameters +~~~~~~~~~~~~~~~~~~~ -.. currentmodule:: specparam.measures.params +.. currentmodule:: specparam.params.periodic .. autosummary:: :toctree: generated/ - compute_knee_frequency - compute_time_constant + compute_peak_height Simulation Code --------------- diff --git a/doc/conf.py b/doc/conf.py index c4d2a7dc..c5b76fdb 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -23,7 +23,7 @@ # Set project information project = 'specparam' -copyright = '2018-{}, VoytekLab'.format(date.today().year) +copyright = '2018-{}'.format(date.today().year) author = 'Thomas Donoghue' # Get and set the current version number diff --git a/doc/make_doc_plots.py b/doc/make_doc_plots.py index f7faaf33..2e3cb9da 100644 --- a/doc/make_doc_plots.py +++ b/doc/make_doc_plots.py @@ -9,7 +9,7 @@ from specparam.sim.gen import gen_power_spectrum from specparam.plts.utils import check_ax from specparam.plts.spectra import plot_spectrum -from specparam.utils.download import load_example_data +from specparam.demo.download import load_example_data ################################################################################################### ################################################################################################### diff --git a/examples/analyses/plot_dev_demo.py b/examples/analyses/plot_dev_demo.py index dffde294..321978a5 100644 --- a/examples/analyses/plot_dev_demo.py +++ b/examples/analyses/plot_dev_demo.py @@ -48,7 +48,7 @@ from specparam.measures.pointwise import compute_pointwise_error, compute_pointwise_error_group # Import helper utility to access data -from specparam.utils.download import fetch_example_data +from specparam.demo.download import fetch_example_data ################################################################################################### # Access Example Data @@ -302,7 +302,7 @@ ################################################################################################### # Print out the group results and plots of fit parameters -fg.print_results() +fg.print() fg.plot() ################################################################################################### @@ -559,7 +559,7 @@ ################################################################################################### # Check results and visualize the extracted model -fm.print_results() +fm.print() fm.plot() ################################################################################################### diff --git a/examples/customize/plot_custom_algorithms.py b/examples/customize/plot_custom_algorithms.py index 2276d96f..2df1d943 100644 --- a/examples/customize/plot_custom_algorithms.py +++ b/examples/customize/plot_custom_algorithms.py @@ -99,7 +99,7 @@ class DummyAlgorithm(Algorithm): """Dummy object to mimic a fit algorithm.""" - def __init__(self, modes=None, data=None, results=None, debug=False): + def __init__(self, modes=None, data=None, results=None, model=None, debug=False): """Initialize DummyAlgorithm instance.""" # Initialize base algorithm object with algorithm metadata @@ -107,7 +107,7 @@ def __init__(self, modes=None, data=None, results=None, debug=False): name='dummy_fit_algo', description='Dummy fit algorithm.', public_settings=DUMMY_ALGO_SETTINGS, - modes=modes, data=data, results=results, debug=debug) + modes=modes, data=data, results=results, model=None, debug=debug) def _fit(self): """Define the full fitting algorithm.""" @@ -133,7 +133,7 @@ def _fit(self): # components (`model.results.model._ap_fit` & `model.results.model._peak_fit`) # # If the above you do the above, the model object can be used as normal, and you can do -# (fit / print_results / plot / report / as well as save and load results). +# (fit / print / plot / report / as well as save and load results). # # There are also some additional procedures / outputs that a custom fit process may do: # @@ -206,7 +206,7 @@ def _fit(self): class CustomAlgorithm(Algorithm): """Custom fitting algorithm.""" - def __init__(self, guess_cf, modes=None, data=None, results=None, debug=False): + def __init__(self, guess_cf, modes=None, data=None, results=None, model=None, debug=False): """Initialize DummyAlgorithm instance.""" # Initialize base algorithm object with algorithm metadata @@ -214,7 +214,7 @@ def __init__(self, guess_cf, modes=None, data=None, results=None, debug=False): name='custom_fit_algo', description='Example custom algorithm.', public_settings=CUSTOM_ALGO_SETTINGS, - modes=modes, data=data, results=results, debug=debug) + modes=modes, data=data, results=results, model=None, debug=debug) ## Public settings self.settings.guess_cf = guess_cf diff --git a/examples/customize/plot_custom_param_conversions.py b/examples/customize/plot_custom_param_conversions.py index cb78f783..b3cbd9ad 100644 --- a/examples/customize/plot_custom_param_conversions.py +++ b/examples/customize/plot_custom_param_conversions.py @@ -7,7 +7,8 @@ from specparam import SpectralModel -from specparam.utils.download import load_example_data +# Import utility to load example data +from specparam.demo import load_example_data # Import the default set of parameter conversions from specparam.convert.definitions import check_converters, DEFAULT_CONVERTERS diff --git a/examples/manage/plot_fit_models_3d.py b/examples/manage/plot_fit_models_3d.py index 8786fd25..92d47546 100644 --- a/examples/manage/plot_fit_models_3d.py +++ b/examples/manage/plot_fit_models_3d.py @@ -246,5 +246,5 @@ all_fg = combine_model_objs(fgs) # Explore the results from across all model fits -all_fg.print_results() +all_fg.print() all_fg.plot() diff --git a/examples/models/plot_data_components.py b/examples/models/plot_data_components.py index aa41f554..a4bd7ea8 100644 --- a/examples/models/plot_data_components.py +++ b/examples/models/plot_data_components.py @@ -69,7 +69,7 @@ # # To access these components, we can use the following `getter` methods: # -# - :meth:`~specparam.SpectralModel.get_data`: allows for accessing data components +# - :meth:`~specparam.SpectralModel.data.get_data`: allows for accessing data components # - :meth:`~specparam.SpectralModel.results.model.get_component`: allows for accessing model components # @@ -86,12 +86,12 @@ ################################################################################################### # Plot the peak removed spectrum data component -plot_spectra(fm.data.freqs, fm.get_data('aperiodic'), color='black') +plot_spectra(fm.data.freqs, fm.data.get_data('aperiodic'), color='black') ################################################################################################### # Plot the peak removed spectrum, with the model aperiodic fit -plot_spectra(fm.data.freqs, [fm.get_data('aperiodic'), fm.results.model.get_component('aperiodic')], +plot_spectra(fm.data.freqs, [fm.data.get_data('aperiodic'), fm.results.model.get_component('aperiodic')], colors=['black', 'blue'], linestyle=['-', '--']) ################################################################################################### @@ -108,12 +108,12 @@ ################################################################################################### # Plot the flattened spectrum data component -plot_spectra(fm.data.freqs, fm.get_data('peak'), color='black') +plot_spectra(fm.data.freqs, fm.data.get_data('peak'), color='black') ################################################################################################### # Plot the flattened spectrum data with the model peak fit -plot_spectra(fm.data.freqs, [fm.get_data('peak'), fm.results.model.get_component('peak')], +plot_spectra(fm.data.freqs, [fm.data.get_data('peak'), fm.results.model.get_component('peak')], colors=['black', 'green'], linestyle=['-', '--']) ################################################################################################### @@ -156,7 +156,7 @@ ################################################################################################### # Plot the peak removed spectrum, with the model aperiodic fit -plot_spectra(fm.data.freqs, [fm.get_data('aperiodic', 'linear'), +plot_spectra(fm.data.freqs, [fm.data.get_data('aperiodic', 'linear'), fm.results.model.get_component('aperiodic', 'linear')], colors=['black', 'blue'], linestyle=['-', '--']) @@ -171,7 +171,7 @@ # Plot the flattened spectrum data with the model peak fit plot_spectra(fm.data.freqs, - [fm.get_data('peak', 'linear'), fm.results.model.get_component('peak', 'linear')], + [fm.data.get_data('peak', 'linear'), fm.results.model.get_component('peak', 'linear')], colors=['black', 'green'], linestyle=['-', '--']) ################################################################################################### @@ -191,8 +191,8 @@ # Plot the linear data, showing the combination of peak + aperiodic matches the full data plot_spectra(fm.data.freqs, - [fm.get_data('full', 'linear'), - fm.get_data('aperiodic', 'linear') + fm.get_data('peak', 'linear')], + [fm.data.get_data('full', 'linear'), + fm.data.get_data('aperiodic', 'linear') + fm.data.get_data('peak', 'linear')], linestyle=['-', 'dashed'], colors=['black', 'red'], alpha=[0.3, 0.75]) ################################################################################################### diff --git a/examples/models/plot_model_component_relationships.py b/examples/models/plot_model_component_relationships.py index a67cb381..ef1ec7fb 100644 --- a/examples/models/plot_model_component_relationships.py +++ b/examples/models/plot_model_component_relationships.py @@ -16,7 +16,9 @@ from specparam.utils.array import unlog from specparam.utils.select import nearest_ind -from specparam.utils.download import load_example_data + +# Import utility to load example data +from specparam.demo import load_example_data # Import function to directly compute peak heights from specparam.convert.params import compute_peak_height diff --git a/motivations/measurements/plot_BandByBand.py b/motivations/measurements/plot_BandByBand.py index 2c7b4235..52fa6ff9 100644 --- a/motivations/measurements/plot_BandByBand.py +++ b/motivations/measurements/plot_BandByBand.py @@ -203,7 +203,7 @@ def compare_band_pw(fm1, fm2, band_def): # Plot the power spectra differences plot_spectra_shading(freqs, - [fm_bands_g1.get_data('peak'), fm_bands_g2.get_data('peak')], + [fm_bands_g1.data.get_data('peak'), fm_bands_g2.data.get_data('peak')], log_powers=False, linewidth=3, shades=bands.definitions, shade_colors=shade_cols, labels=labels) @@ -294,7 +294,7 @@ def compare_band_pw(fm1, fm2, band_def): # Plot the power spectra differences plot_spectra_shading(freqs, - [fm_pa_g1.get_data('peak'), fm_pa_g2.get_data('peak')], + [fm_pa_g1.data.get_data('peak'), fm_pa_g2.data.get_data('peak')], log_powers=False, linewidth=3, shades=bands.definitions, shade_colors=shade_cols, labels=labels) diff --git a/tutorials/plot_02-PSDModel.py b/tutorials/plot_02-PSDModel.py index 5d3056ce..12831418 100644 --- a/tutorials/plot_02-PSDModel.py +++ b/tutorials/plot_02-PSDModel.py @@ -11,7 +11,7 @@ from specparam import SpectralModel # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### @@ -78,7 +78,7 @@ # The above method 'report', is a convenience method that calls a series of methods: # # - :meth:`~specparam.SpectralModel.fit`: fits the power spectrum model -# - :meth:`~specparam.SpectralModel.print_results`: prints out the results +# - :meth:`~specparam.SpectralModel.print`: prints out the results # - :meth:`~specparam.SpectralModel.plot`: plots the data and model fit # # Each of these methods can also be called individually. @@ -90,7 +90,7 @@ fm.fit(freqs, spectrum, freq_range) # After fitting, plotting and parameter fitting can be called independently: -# fm.print_results() +# fm.print() # fm.plot() ################################################################################################### diff --git a/tutorials/plot_03-Algorithm.py b/tutorials/plot_03-Algorithm.py index 81c1b664..102300ab 100644 --- a/tutorials/plot_03-Algorithm.py +++ b/tutorials/plot_03-Algorithm.py @@ -45,7 +45,7 @@ from specparam.plts.annotate import plot_annotated_peak_search # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### @@ -194,7 +194,7 @@ ################################################################################################### # Plot the peak removed power spectrum, created by removing peak fit from original spectrum -plot_spectra(fm.data.freqs, fm.get_data('aperiodic'), plt_log, +plot_spectra(fm.data.freqs, fm.data.get_data('aperiodic'), plt_log, label='Peak Removed Spectrum', color='black') ################################################################################################### @@ -212,7 +212,7 @@ # Plot the final aperiodic fit, calculated on the peak removed power spectrum _, ax = plt.subplots(figsize=(12, 10)) -plot_spectra(fm.data.freqs, fm.get_data('aperiodic'), plt_log, +plot_spectra(fm.data.freqs, fm.data.get_data('aperiodic'), plt_log, label='Peak Removed Spectrum', color='black', ax=ax) plot_spectra(fm.data.freqs, fm.results.model.get_component('aperiodic'), plt_log, label='Final Aperiodic Fit', color='blue', alpha=0.5, linestyle='dashed', ax=ax) @@ -248,7 +248,7 @@ ################################################################################################### # Print out the model results -fm.print_results() +fm.print() ################################################################################################### # @@ -288,12 +288,12 @@ # # Stored data attributes: # -# - Flattened Spectrum: (``SpectralModel.get_data('peak')``) +# - Flattened Spectrum: (``SpectralModel.data.get_data('peak')``) # # - The original data, with the aperiodic component removed # - This is computed as the power_spectrum minus the model aperiodic fit # -# - Peak Removed Spectrum: (``SpectralModel.get_data('aperiodic')``) +# - Peak Removed Spectrum: (``SpectralModel.data.get_data('aperiodic')``) # # - The original data, with the periodic component (peaks) removed # - This is computed as the power_spectrum minus the model peak fit diff --git a/tutorials/plot_04-PeriodicFitting.py b/tutorials/plot_04-PeriodicFitting.py index b55c5dcd..014a4e54 100644 --- a/tutorials/plot_04-PeriodicFitting.py +++ b/tutorials/plot_04-PeriodicFitting.py @@ -11,10 +11,10 @@ from specparam import SpectralModel # Import function to check available list of modes -from specparam.modes.definitions import check_modes +from specparam.modes import check_modes # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### # Component Fit Modes @@ -42,7 +42,7 @@ # choosing the periodic mode. # # To see the available periodic fit modes, we can use the -# :func:`~specparam.modes.definitions.check_modes` function. +# :func:`~specparam.modes.check_modes` function. # ################################################################################################### diff --git a/tutorials/plot_05-AperiodicFitting.py b/tutorials/plot_05-AperiodicFitting.py index fb11e52a..dfe9455c 100644 --- a/tutorials/plot_05-AperiodicFitting.py +++ b/tutorials/plot_05-AperiodicFitting.py @@ -11,10 +11,10 @@ from specparam import SpectralModel # Import function to check available list of modes -from specparam.modes.definitions import check_modes +from specparam.modes import check_modes # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### # Component Fit Modes diff --git a/tutorials/plot_06-Metrics.py b/tutorials/plot_06-Metrics.py index 7d317389..720503ce 100644 --- a/tutorials/plot_06-Metrics.py +++ b/tutorials/plot_06-Metrics.py @@ -11,10 +11,10 @@ from specparam import SpectralModel # Import function to check available list of metrics -from specparam.metrics.definitions import check_metrics +from specparam.metrics import check_metrics # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### # Model Metrics @@ -29,7 +29,7 @@ # and thus to assess the quality of the model fits. # # The module comes with various available metrics. To see the list of available metrics, -# we can use the :func:`~specparam.metrics.definitions.check_metrics` function. +# we can use the :func:`~specparam.metrics.check_metrics` function. # ################################################################################################### diff --git a/tutorials/plot_07-ModelObject.py b/tutorials/plot_07-ModelObject.py index 002a7598..53b37879 100644 --- a/tutorials/plot_07-ModelObject.py +++ b/tutorials/plot_07-ModelObject.py @@ -11,7 +11,7 @@ from specparam import SpectralModel # Import utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### @@ -112,9 +112,8 @@ ################################################################################################### -# You can check all the user defined settings with check_settings -# The description parameter here is set to print out quick descriptions of the settings -fm.print_settings(description=True) +# You can check all the user defined settings by printing from the model object +fm.print('settings') ################################################################################################### # Changing Settings @@ -296,9 +295,9 @@ # There is also functionality to save out a 'report' of a particular model fit. # # This generates and saves a PDF which contains the same output as -# :meth:`~specparam.SpectralModel.print_results`, -# :meth:`~specparam.SpectralModel.plot`, and -# :meth:`~specparam.SpectralModel.print_settings`. +# :meth:`~specparam.SpectralModel.print('results')`, +# :meth:`~specparam.SpectralModel.plot()`, and +# :meth:`~specparam.SpectralModel.print('settings')`. # ################################################################################################### diff --git a/tutorials/plot_08-GroupFits.py b/tutorials/plot_08-GroupFits.py index 16354bf4..4f7e68fc 100644 --- a/tutorials/plot_08-GroupFits.py +++ b/tutorials/plot_08-GroupFits.py @@ -11,7 +11,7 @@ from specparam import SpectralGroupModel # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### # Fitting Multiple Spectra @@ -87,7 +87,7 @@ ################################################################################################### # Print out results -fg.print_results() +fg.print() ################################################################################################### @@ -220,7 +220,7 @@ ################################################################################################### # Print results to check that the loaded group -nfg.print_results() +nfg.print() ################################################################################################### # Parallel Support @@ -288,7 +288,7 @@ ################################################################################################### # Print results and plot extracted model fit -fm.print_results() +fm.print() fm.plot() ################################################################################################### diff --git a/tutorials/plot_10-TroubleShooting.py b/tutorials/plot_10-TroubleShooting.py index c3f04d33..0b315079 100644 --- a/tutorials/plot_10-TroubleShooting.py +++ b/tutorials/plot_10-TroubleShooting.py @@ -286,7 +286,7 @@ ################################################################################################### # Check results and visualize the extracted model -fm.print_results() +fm.print() fm.plot() ################################################################################################### @@ -350,13 +350,11 @@ ################################################################################################### # Print out instructions to report bad fits -SpectralModel.print_report_issue() +fm.print('issue') ################################################################################################### # -# Note that you can also call this method from SpectralGroupModel -# (ex: `SpectralGroupModel.print_report_issue()`) as well as from instances of these objects -# (ex: `fm.print_report_issue()`, `fg.print_report_issue()`) +# Note that you can also call this method from SpectralGroupModel (ex: `fg.print('issue')`) # ################################################################################################### diff --git a/tutorials/plot_11-FurtherAnalysis.py b/tutorials/plot_11-FurtherAnalysis.py index febf5c6b..8764a40e 100644 --- a/tutorials/plot_11-FurtherAnalysis.py +++ b/tutorials/plot_11-FurtherAnalysis.py @@ -44,7 +44,7 @@ from specparam.data.periodic import get_band_peak, get_band_peak_group # Import a utility to download and load example data -from specparam.utils.download import load_example_data +from specparam.demo import load_example_data ################################################################################################### # Load and Fit Example Data diff --git a/tutorials/plot_12-Reporting.py b/tutorials/plot_12-Reporting.py index 19871925..fd31c320 100644 --- a/tutorials/plot_12-Reporting.py +++ b/tutorials/plot_12-Reporting.py @@ -82,7 +82,7 @@ # some of which might look familiar. # # The settings information, for example, is the same as printed using the -# # - :meth:`~specparam.SpectralModel.print_settings` method. +# # - :meth:`~specparam.SpectralModel.print('settings')` method. # # Next, let's check out the text version of the methods report. #