From 159d17d7e8736e24f76c75434d39a634866a72ff Mon Sep 17 00:00:00 2001 From: JoFrhwld Date: Thu, 14 Mar 2024 14:42:28 -0400 Subject: [PATCH] docs update --- docs/_quarto.yml | 5 ++ docs/objects.json | 2 +- docs/reference/CandidateTracks.qmd | 77 ++++++++++--------- docs/reference/OneTrack.qmd | 56 +++++++------- docs/reference/_sidebar.yml | 4 + docs/reference/index.qmd | 9 +++ .../processors.outputs.pickle_candidates.qmd | 15 ++++ ...processors.outputs.unpickle_candidates.qmd | 18 +++++ 8 files changed, 122 insertions(+), 64 deletions(-) create mode 100644 docs/reference/processors.outputs.pickle_candidates.qmd create mode 100644 docs/reference/processors.outputs.unpickle_candidates.qmd diff --git a/docs/_quarto.yml b/docs/_quarto.yml index 5fbb230..f096c3a 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -68,6 +68,11 @@ quartodoc: children: embedded - name: CandidateTracks children: embedded + - title: Outputs + desc: Data outputs + contents: + - processors.outputs.pickle_candidates + - processors.outputs.unpickle_candidates - title: Smoothers desc: Smoother diff --git a/docs/objects.json b/docs/objects.json index a012120..ffe7000 100644 --- a/docs/objects.json +++ b/docs/objects.json @@ -1 +1 @@ -{"project": "fasttrackpy", "version": "0.0.9999", "count": 34, "items": [{"name": "fasttrackpy.process_audio_file", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_file.html#fasttrackpy.process_audio_file", "dispname": "-"}, {"name": "fasttrackpy.patterns.just_audio.process_audio_file", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_file.html#fasttrackpy.process_audio_file", "dispname": "fasttrackpy.process_audio_file"}, {"name": "fasttrackpy.process_directory", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_directory.html#fasttrackpy.process_directory", "dispname": "-"}, {"name": "fasttrackpy.patterns.just_audio.process_directory", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_directory.html#fasttrackpy.process_directory", "dispname": "fasttrackpy.process_directory"}, {"name": "fasttrackpy.process_audio_textgrid", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_textgrid.html#fasttrackpy.process_audio_textgrid", "dispname": "-"}, {"name": "fasttrackpy.patterns.audio_textgrid.process_audio_textgrid", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_textgrid.html#fasttrackpy.process_audio_textgrid", "dispname": "fasttrackpy.process_audio_textgrid"}, {"name": "fasttrackpy.process_corpus", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_corpus.html#fasttrackpy.process_corpus", "dispname": "-"}, {"name": "fasttrackpy.patterns.corpus.process_corpus", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_corpus.html#fasttrackpy.process_corpus", "dispname": "fasttrackpy.process_corpus"}, {"name": "fasttrackpy.OneTrack.spectrogram", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.spectrogram", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack.spectrogram", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.spectrogram", "dispname": "fasttrackpy.OneTrack.spectrogram"}, {"name": "fasttrackpy.OneTrack.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.to_df", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.to_df", "dispname": "fasttrackpy.OneTrack.to_df"}, {"name": "fasttrackpy.OneTrack", "domain": "py", "role": "class", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack", "domain": "py", "role": "class", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack", "dispname": "fasttrackpy.OneTrack"}, {"name": "fasttrackpy.CandidateTracks.spectrograms", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.spectrograms", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks.spectrograms", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.spectrograms", "dispname": "fasttrackpy.CandidateTracks.spectrograms"}, {"name": "fasttrackpy.CandidateTracks.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.to_df", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.to_df", "dispname": "fasttrackpy.CandidateTracks.to_df"}, {"name": "fasttrackpy.CandidateTracks", "domain": "py", "role": "class", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks", "domain": "py", "role": "class", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks", "dispname": "fasttrackpy.CandidateTracks"}, {"name": "fasttrackpy.Smoother.smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother.smooth", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.Smoother.smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother.smooth", "dispname": "fasttrackpy.Smoother.smooth"}, {"name": "fasttrackpy.Smoother", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.Smoother", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother", "dispname": "fasttrackpy.Smoother"}, {"name": "fasttrackpy.processors.smoothers.Smoothed", "domain": "py", "role": "class", "priority": "1", "uri": "reference/processors.smoothers.Smoothed.html#fasttrackpy.processors.smoothers.Smoothed", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.dct_smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.smoothers.dct_smooth.html#fasttrackpy.processors.smoothers.dct_smooth", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.dct_smooth_regression", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.smoothers.dct_smooth_regression.html#fasttrackpy.processors.smoothers.dct_smooth_regression", "dispname": "-"}, {"name": "fasttrackpy.Loss", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Loss.html#fasttrackpy.Loss", "dispname": "-"}, {"name": "fasttrackpy.processors.losses.Loss", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Loss.html#fasttrackpy.Loss", "dispname": "fasttrackpy.Loss"}, {"name": "fasttrackpy.processors.losses.lmse", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.losses.lmse.html#fasttrackpy.processors.losses.lmse", "dispname": "-"}, {"name": "fasttrackpy.processors.losses.mse", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.losses.mse.html#fasttrackpy.processors.losses.mse", "dispname": "-"}, {"name": "fasttrackpy.Agg", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Agg.html#fasttrackpy.Agg", "dispname": "-"}, {"name": "fasttrackpy.processors.aggs.Agg", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Agg.html#fasttrackpy.Agg", "dispname": "fasttrackpy.Agg"}, {"name": "fasttrackpy.processors.aggs.agg_sum", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.aggs.agg_sum.html#fasttrackpy.processors.aggs.agg_sum", "dispname": "-"}]} \ No newline at end of file +{"project": "fasttrackpy", "version": "0.0.9999", "count": 36, "items": [{"name": "fasttrackpy.process_audio_file", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_file.html#fasttrackpy.process_audio_file", "dispname": "-"}, {"name": "fasttrackpy.patterns.just_audio.process_audio_file", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_file.html#fasttrackpy.process_audio_file", "dispname": "fasttrackpy.process_audio_file"}, {"name": "fasttrackpy.process_directory", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_directory.html#fasttrackpy.process_directory", "dispname": "-"}, {"name": "fasttrackpy.patterns.just_audio.process_directory", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_directory.html#fasttrackpy.process_directory", "dispname": "fasttrackpy.process_directory"}, {"name": "fasttrackpy.process_audio_textgrid", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_textgrid.html#fasttrackpy.process_audio_textgrid", "dispname": "-"}, {"name": "fasttrackpy.patterns.audio_textgrid.process_audio_textgrid", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_audio_textgrid.html#fasttrackpy.process_audio_textgrid", "dispname": "fasttrackpy.process_audio_textgrid"}, {"name": "fasttrackpy.process_corpus", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_corpus.html#fasttrackpy.process_corpus", "dispname": "-"}, {"name": "fasttrackpy.patterns.corpus.process_corpus", "domain": "py", "role": "function", "priority": "1", "uri": "reference/process_corpus.html#fasttrackpy.process_corpus", "dispname": "fasttrackpy.process_corpus"}, {"name": "fasttrackpy.OneTrack.spectrogram", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.spectrogram", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack.spectrogram", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.spectrogram", "dispname": "fasttrackpy.OneTrack.spectrogram"}, {"name": "fasttrackpy.OneTrack.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.to_df", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack.to_df", "dispname": "fasttrackpy.OneTrack.to_df"}, {"name": "fasttrackpy.OneTrack", "domain": "py", "role": "class", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack", "dispname": "-"}, {"name": "fasttrackpy.tracks.OneTrack", "domain": "py", "role": "class", "priority": "1", "uri": "reference/OneTrack.html#fasttrackpy.OneTrack", "dispname": "fasttrackpy.OneTrack"}, {"name": "fasttrackpy.CandidateTracks.spectrograms", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.spectrograms", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks.spectrograms", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.spectrograms", "dispname": "fasttrackpy.CandidateTracks.spectrograms"}, {"name": "fasttrackpy.CandidateTracks.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.to_df", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks.to_df", "domain": "py", "role": "function", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks.to_df", "dispname": "fasttrackpy.CandidateTracks.to_df"}, {"name": "fasttrackpy.CandidateTracks", "domain": "py", "role": "class", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks", "dispname": "-"}, {"name": "fasttrackpy.tracks.CandidateTracks", "domain": "py", "role": "class", "priority": "1", "uri": "reference/CandidateTracks.html#fasttrackpy.CandidateTracks", "dispname": "fasttrackpy.CandidateTracks"}, {"name": "fasttrackpy.processors.outputs.pickle_candidates", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.outputs.pickle_candidates.html#fasttrackpy.processors.outputs.pickle_candidates", "dispname": "-"}, {"name": "fasttrackpy.processors.outputs.unpickle_candidates", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.outputs.unpickle_candidates.html#fasttrackpy.processors.outputs.unpickle_candidates", "dispname": "-"}, {"name": "fasttrackpy.Smoother.smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother.smooth", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.Smoother.smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother.smooth", "dispname": "fasttrackpy.Smoother.smooth"}, {"name": "fasttrackpy.Smoother", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.Smoother", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Smoother.html#fasttrackpy.Smoother", "dispname": "fasttrackpy.Smoother"}, {"name": "fasttrackpy.processors.smoothers.Smoothed", "domain": "py", "role": "class", "priority": "1", "uri": "reference/processors.smoothers.Smoothed.html#fasttrackpy.processors.smoothers.Smoothed", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.dct_smooth", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.smoothers.dct_smooth.html#fasttrackpy.processors.smoothers.dct_smooth", "dispname": "-"}, {"name": "fasttrackpy.processors.smoothers.dct_smooth_regression", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.smoothers.dct_smooth_regression.html#fasttrackpy.processors.smoothers.dct_smooth_regression", "dispname": "-"}, {"name": "fasttrackpy.Loss", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Loss.html#fasttrackpy.Loss", "dispname": "-"}, {"name": "fasttrackpy.processors.losses.Loss", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Loss.html#fasttrackpy.Loss", "dispname": "fasttrackpy.Loss"}, {"name": "fasttrackpy.processors.losses.lmse", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.losses.lmse.html#fasttrackpy.processors.losses.lmse", "dispname": "-"}, {"name": "fasttrackpy.processors.losses.mse", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.losses.mse.html#fasttrackpy.processors.losses.mse", "dispname": "-"}, {"name": "fasttrackpy.Agg", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Agg.html#fasttrackpy.Agg", "dispname": "-"}, {"name": "fasttrackpy.processors.aggs.Agg", "domain": "py", "role": "class", "priority": "1", "uri": "reference/Agg.html#fasttrackpy.Agg", "dispname": "fasttrackpy.Agg"}, {"name": "fasttrackpy.processors.aggs.agg_sum", "domain": "py", "role": "function", "priority": "1", "uri": "reference/processors.aggs.agg_sum.html#fasttrackpy.processors.aggs.agg_sum", "dispname": "-"}]} \ No newline at end of file diff --git a/docs/reference/CandidateTracks.qmd b/docs/reference/CandidateTracks.qmd index 84145cc..b753e29 100644 --- a/docs/reference/CandidateTracks.qmd +++ b/docs/reference/CandidateTracks.qmd @@ -6,56 +6,59 @@ A class for candidate tracks for a single formant ## Parameters -| Name | Type | Description | Default | -|---------------------|----------|---------------------------------------------------------------------------|--------------| -| `sound` | pm.Sound | A `parselmouth.Sound` object. | _required_ | -| `min_max_formant` | float | The lowest max-formant value to try. Defaults to 4000. | `4000` | -| `max_max_formant` | float | The highest max formant to try. Defaults to 7000. | `7000` | -| `nstep` | int | The number of steps from the min to the max max formant. Defaults to 20. | `20` | -| `n_formants` | int | The number of formants to track. Defaults to 4. | `4` | -| `window_length` | float | Window length of the formant analysis. Defaults to 0.025. | `0.025` | -| `time_step` | float | Time step of the formant analyusis window. Defaults to 0.002. | `0.002` | -| `pre_emphasis_from` | float | Pre-emphasis threshold. Defaults to 50. | `50` | -| `smoother` | Smoother | The smoother method to use. Defaults to `Smoother()`. | `Smoother()` | -| `loss_fun` | Loss | The loss function to use. Defaults to Loss(). | `Loss()` | -| `agg_fun` | Agg | The loss aggregation function to use. Defaults to Agg(). | `Agg()` | +| Name | Type | Description | Default | +|---------------------|----------|--------------------------------------------------------------------------|--------------| +| `sound` | pm.Sound | A `parselmouth.Sound` object. | _required_ | +| `min_max_formant` | float | The lowest max-formant value to try. Defaults to 4000. | `4000` | +| `max_max_formant` | float | The highest max formant to try. Defaults to 7000. | `7000` | +| `nstep` | int | The number of steps from the min to the max max formant. Defaults to 20. | `20` | +| `n_formants` | int | The number of formants to track. Defaults to 4. | `4` | +| `window_length` | float | Window length of the formant analysis. Defaults to 0.025. | `0.025` | +| `time_step` | float | Time step of the formant analyusis window. Defaults to 0.002. | `0.002` | +| `pre_emphasis_from` | float | Pre-emphasis threshold. Defaults to 50. | `50` | +| `smoother` | Smoother | The smoother method to use. Defaults to `Smoother()`. | `Smoother()` | +| `loss_fun` | Loss | The loss function to use. Defaults to Loss(). | `Loss()` | +| `agg_fun` | Agg | The loss aggregation function to use. Defaults to Agg(). | `Agg()` | ## Attributes -| Name | Type | Description | -|----------------|-----------------------------------|--------------------------------------------------------------------------------| -| candidates | list\[OneTrack, ...\] | A list of `OneTrack` tracks. | -| min_n_measured | int | The smallest number of successfully measured formants across all `candidates` | -| smooth_errors | np.array | The error terms for each treack in `candidates` | -| winner_idx | int | The candidate track with the smallest error term | -| winner | OneTrack | The winning `OneTrack` track. | -| file_name | str | The filename of the audio file, if set. | -| interval | aligned_textgrid.SequenceInterval | The textgrid interval of the sound, if set. | -| id | str | The interval id of the sound, if set. | -| group | str | The tier group name of the sound, if set. | +| Name | Type | Description | +|----------------|-----------------------------------|-------------------------------------------------------------------------------| +| candidates | list\[OneTrack, ...\] | A list of `OneTrack` tracks. | +| min_n_measured | int | The smallest number of successfully measured formants across all `candidates` | +| smooth_errors | np.array | The error terms for each treack in `candidates` | +| winner_idx | int | The candidate track with the smallest error term | +| winner | OneTrack | The winning `OneTrack` track. | +| file_name | str | The filename of the audio file, if set. | +| interval | aligned_textgrid.SequenceInterval | The textgrid interval of the sound, if set. | +| id | str | The interval id of the sound, if set. | +| group | str | The tier group name of the sound, if set. | ## Methods | Name | Description | | --- | --- | -| [spectrograms](#fasttrackpy.CandidateTracks.spectrograms) | Generate a spectrogram with formant tracks for the candidate tracks | +| [spectrograms](#fasttrackpy.CandidateTracks.spectrograms) | This will plot a grid of the candidate formant | | [to_df](#fasttrackpy.CandidateTracks.to_df) | Return a polars dataframe of the candidate tracks | ### spectrograms { #fasttrackpy.CandidateTracks.spectrograms } `CandidateTracks.spectrograms(**kwargs)` -Generate a spectrogram with formant tracks for the candidate tracks +This will plot a grid of the candidate formant +tracks and their spectrograms. If a `file_name` +is provided, it will save the plot to disk. #### Parameters -| Name | Type | Description | Default | -|---------------------|--------|-----------------------------------------------------------|------------| -| `formants` | int | Number of formants to plot. Defaults to 3. | _required_ | -| `maximum_frequency` | int | Maximum frequency for the spectrogram. Defaults to 3500. | _required_ | -| `tracks` | bool | Whether or not to plot the tracks. Defaults to True. | _required_ | -| `dynamic_range` | int | Dynamic range of the spectrogram. Defaults to 60. | _required_ | -| `figsize` | tuple | Figure size. Defaults to (12,8). | _required_ | +| Name | Type | Description | Default | +|---------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------|------------| +| `formants` | int | The number of formants to plot. Defaults to 3. | _required_ | +| `maximum_frequency` | float | The frequency range the spectrogram and formants will be plotted up to. Defaults to 3500. | _required_ | +| `dynamic_range` | float | A all spectrogram values below the dynamic range. will be plotted as white. Defaults to 60. | _required_ | +| `figsize` | tuple\[float, float\] | Width and height of the figure in inches. Defaults to (8,5). | _required_ | +| `file_name` | Path \| None | If provided, how to save the spectrogram. If not provided (None) the plot will show interactively. Defaults to None. | _required_ | +| `dpi` | float | If the plot is being saved, its image resolution in dots per inch. Defaults to 75 | _required_ | ### to_df { #fasttrackpy.CandidateTracks.to_df } @@ -65,10 +68,10 @@ Return a polars dataframe of the candidate tracks #### Parameters -| Name | Type | Description | Default | -|----------|--------------------------------|--------------------------------------------------------------------------------------|--------------| -| `which` | Literal\['winner', 'all'\] | Return just the winner track data, or all candidates. Defaults to "winner". | `'winner'` | -| `output` | Literal\['formants', 'param'\] | Whether to output the formants or the smoothing parameters. Defaults to "formants". | `'formants'` | +| Name | Type | Description | Default | +|----------|--------------------------------|-------------------------------------------------------------------------------------|--------------| +| `which` | Literal\['winner', 'all'\] | Return just the winner track data, or all candidates. Defaults to "winner". | `'winner'` | +| `output` | Literal\['formants', 'param'\] | Whether to output the formants or the smoothing parameters. Defaults to "formants". | `'formants'` | #### Returns diff --git a/docs/reference/OneTrack.qmd b/docs/reference/OneTrack.qmd index 226cf17..15f5c4d 100644 --- a/docs/reference/OneTrack.qmd +++ b/docs/reference/OneTrack.qmd @@ -6,17 +6,17 @@ A single formant track. ## Parameters -| Name | Type | Description | Default | -|---------------------|----------|----------------------------------------------------------------|--------------| -| `sound` | pm.Sound | A `parselmouth.Sound` object. | _required_ | -| `maximum_formant` | float | max formant | _required_ | -| `n_formants` | int | The number of formants to track. Defaults to 4. | `4` | -| `window_length` | float | Window length of the formant analysis. Defaults to 0.025. | `0.025` | -| `time_step` | float | Time step of the formant analyusis window. Defaults to 0.002. | `0.002` | -| `pre_emphasis_from` | float | Pre-emphasis threshold. Defaults to 50. | `50` | -| `smoother` | Smoother | The smoother method to use. Defaults to `Smoother()`. | `Smoother()` | -| `loss_fun` | Loss | The loss function to use. Defaults to Loss(). | `Loss()` | -| `agg_fun` | Agg | The loss aggregation function to use. Defaults to Agg(). | `Agg()` | +| Name | Type | Description | Default | +|---------------------|----------|---------------------------------------------------------------|--------------| +| `sound` | pm.Sound | A `parselmouth.Sound` object. | _required_ | +| `maximum_formant` | float | max formant | _required_ | +| `n_formants` | int | The number of formants to track. Defaults to 4. | `4` | +| `window_length` | float | Window length of the formant analysis. Defaults to 0.025. | `0.025` | +| `time_step` | float | Time step of the formant analyusis window. Defaults to 0.002. | `0.002` | +| `pre_emphasis_from` | float | Pre-emphasis threshold. Defaults to 50. | `50` | +| `smoother` | Smoother | The smoother method to use. Defaults to `Smoother()`. | `Smoother()` | +| `loss_fun` | Loss | The loss function to use. Defaults to Loss(). | `Loss()` | +| `agg_fun` | Agg | The loss aggregation function to use. Defaults to Agg(). | `Agg()` | ## Attributes @@ -26,9 +26,9 @@ A single formant track. | time_domain | np.array | The time domain of the formant estimates | | formants | np.ndarray | A (formants, time) array of values. The formants as initially estimated by praat-parselmouth | | n_measured_formants | int | The total number of formants for which formant tracks were estimatable | -| smoothed_formants | np.ndarray | The smoothed formant values, using the method passed to `smoother`. | +| smoothed_formants | np.ndarray | The smoothed formant values, using the method passed to `smoother`. | | parameters | np.ndarray | The smoothing parameters. | -| smooth_error | float | The error term between formants and smoothed formants. | +| smooth_error | float | The error term between formants and smoothed formants. | | file_name | str | The filename of the audio file, if set. | | interval | aligned_textgrid.SequenceInterval | The textgrid interval of the sound, if set. | | id | str | The interval id of the sound, if set. | @@ -38,25 +38,29 @@ A single formant track. | Name | Description | | --- | --- | -| [spectrogram](#fasttrackpy.OneTrack.spectrogram) | Generate a spectrogram with tracked formants overlaid | +| [spectrogram](#fasttrackpy.OneTrack.spectrogram) | This will plot the spectrogram and formant tracks | | [to_df](#fasttrackpy.OneTrack.to_df) | Output either the formant values or the formant smoothing parameters as a polars dataframe | ### spectrogram { #fasttrackpy.OneTrack.spectrogram } `OneTrack.spectrogram(**kwargs)` -Generate a spectrogram with tracked formants overlaid +This will plot the spectrogram and formant tracks +of a single candidate track. If a `file_name` is +provided, it will save the plot to disk. #### Parameters -| Name | Type | Description | Default | -|---------------------|--------|-----------------------------------------------------------|------------| -| `formants` | int | Number of formants to plot. Defaults to 3. | _required_ | -| `maximum_frequency` | int | Maximum frequency for the spectrogram. Defaults to 3500. | _required_ | -| `tracks` | bool | Whether or not to plot the tracks. Defaults to True. | _required_ | -| `dynamic_range` | int | Dynamic range of the spectrogram. Defaults to 60. | _required_ | -| `figsize` | tuple | Figure size. Defaults to (8,5). | _required_ | -| `color_scale` | str | Color scale for the spectrogram. Defaults to "Greys". | _required_ | +| Name | Type | Description | Default | +|---------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------| +| `formants` | int | The number of formants to plot. Defaults to 3. | _required_ | +| `maximum_frequency` | float | The frequency range the spectrogram and formants will be plotted up to. Defaults to 3500. | _required_ | +| `tracks` | bool | Whether or not to plot the formant tracks. Defaults to True. If False, just the spectogram will be plotted. | _required_ | +| `dynamic_range` | float | A all spectrogram values below the dynamic range. will be plotted as white. Defaults to 60. | _required_ | +| `figsize` | tuple\[float, float\] | Width and height of the figure in inches. Defaults to (8,5). | _required_ | +| `color_scale` | str | A named matplotlib color scale for the spectrogram. Defaults to "Greys". See [here](https://matplotlib.org/stable/users/explain/colors/colormaps.html) for more options. | _required_ | +| `file_name` | Path \| None | If provided, how to save the spectrogram. If not provided (None) the plot will show interactively. Defaults to None. | _required_ | +| `dpi` | float | If the plot is being saved, its image resolution in dots per inch. Defaults to 100. | _required_ | ### to_df { #fasttrackpy.OneTrack.to_df } @@ -66,9 +70,9 @@ Output either the formant values or the formant smoothing parameters as #### Parameters -| Name | Type | Description | Default | -|----------|--------------------------------|--------------------------------------------------------------------------------------|--------------| -| `output` | Literal\['formants', 'param'\] | Whether to output the formants or the smoothing parameters. Defaults to "formants". | `'formants'` | +| Name | Type | Description | Default | +|----------|--------------------------------|-------------------------------------------------------------------------------------|--------------| +| `output` | Literal\['formants', 'param'\] | Whether to output the formants or the smoothing parameters. Defaults to "formants". | `'formants'` | #### Returns diff --git a/docs/reference/_sidebar.yml b/docs/reference/_sidebar.yml index bcb8514..09cb1af 100644 --- a/docs/reference/_sidebar.yml +++ b/docs/reference/_sidebar.yml @@ -12,6 +12,10 @@ website: - reference/OneTrack.qmd - reference/CandidateTracks.qmd section: Classes + - contents: + - reference/processors.outputs.pickle_candidates.qmd + - reference/processors.outputs.unpickle_candidates.qmd + section: Outputs - contents: - reference/Smoother.qmd - reference/processors.smoothers.Smoothed.qmd diff --git a/docs/reference/index.qmd b/docs/reference/index.qmd index c93b9c9..4792934 100644 --- a/docs/reference/index.qmd +++ b/docs/reference/index.qmd @@ -20,6 +20,15 @@ Classes | [OneTrack](OneTrack.qmd#fasttrackpy.OneTrack) | A single formant track. | | [CandidateTracks](CandidateTracks.qmd#fasttrackpy.CandidateTracks) | A class for candidate tracks for a single formant | +## Outputs + +Data outputs + +| | | +| --- | --- | +| [processors.outputs.pickle_candidates](processors.outputs.pickle_candidates.qmd#fasttrackpy.processors.outputs.pickle_candidates) | This will save a CandidateTracks object to | +| [processors.outputs.unpickle_candidates](processors.outputs.unpickle_candidates.qmd#fasttrackpy.processors.outputs.unpickle_candidates) | This will load a CandidateTracks object | + ## Smoothers Smoother diff --git a/docs/reference/processors.outputs.pickle_candidates.qmd b/docs/reference/processors.outputs.pickle_candidates.qmd new file mode 100644 index 0000000..109e542 --- /dev/null +++ b/docs/reference/processors.outputs.pickle_candidates.qmd @@ -0,0 +1,15 @@ +# processors.outputs.pickle_candidates { #fasttrackpy.processors.outputs.pickle_candidates } + +`processors.outputs.pickle_candidates(candidates, file)` + +This will save a CandidateTracks object to +disk as a "pickle" file. Due to the way sound +objects are handled, only use `unpickle_candidates()` +to re-load the pickle object. + +## Parameters + +| Name | Type | Description | Default | +|--------------|-----------------|-----------------------------------------------|------------| +| `candidates` | CandidateTracks | A CandidateTracks object to pickle. | _required_ | +| `file` | Path \| str | The file location to save the pickle file to. | _required_ | \ No newline at end of file diff --git a/docs/reference/processors.outputs.unpickle_candidates.qmd b/docs/reference/processors.outputs.unpickle_candidates.qmd new file mode 100644 index 0000000..c0531fa --- /dev/null +++ b/docs/reference/processors.outputs.unpickle_candidates.qmd @@ -0,0 +1,18 @@ +# processors.outputs.unpickle_candidates { #fasttrackpy.processors.outputs.unpickle_candidates } + +`processors.outputs.unpickle_candidates(file)` + +This will load a CandidateTracks object +that was pickled with `pickle_candidates()`. + +## Parameters + +| Name | Type | Description | Default | +|--------|-------------|-------------------------------------------------|------------| +| `file` | Path \| str | The pickled CandidateTracks object to unpickle. | _required_ | + +## Returns + +| Type | Description | +|-----------------|---------------------------| +| CandidateTracks | A CandidateTracks object. | \ No newline at end of file