ENH: Switch to version 1.0 of config file format, fix #685 #345 #748

doc/get_started/autoannotate.md

@@ -20,10 +20,10 @@ Below is an example of some annotated Bengalese finch song, which is what we'll
 
 :::{hint}
 `vak` has built-in support for widely-used annotation formats.
-Even if your data is not annotated with one of these formats, 
-you can use `vak` by converting your annotations to a simple `.csv` format 
+Even if your data is not annotated with one of these formats,
+you can use `vak` by converting your annotations to a simple `.csv` format
 that is easy to create with Python libraries like `pandas`.
-For more information, please see:  
+For more information, please see:
 {ref}`howto-user-annot`
 :::
 
@@ -42,39 +42,39 @@ Before going through this tutorial, you'll need to:
    or [notepad++](https://notepad-plus-plus.org/)
 3. Download example data from this dataset: <https://figshare.com/articles/Bengalese_Finch_song_repository/4805749>
 
-   - one day of birdsong, for training data (click to download)  
+   - one day of birdsong, for training data (click to download)
      {download}`https://figshare.com/ndownloader/files/41668980`
    - another day, to use to predict annotations (click to download)
      {download}`https://figshare.com/ndownloader/files/41668983`
-   - Be sure to extract the files from these archives! 
-     Please use the program "tar" to extract the archives, 
+   - Be sure to extract the files from these archives!
+     Please use the program "tar" to extract the archives,
      on either macOS/Linux or Windows.
-     Using other programs like WinZIP on Windows 
+     Using other programs like WinZIP on Windows
      can corrupt the files when extracting them,
      causing confusing errors.
      Tar should be available on newer Windows systems
-     (as described 
+     (as described
      [here](https://learn.microsoft.com/en-us/virtualization/community/team-blog/2017/20171219-tar-and-curl-come-to-windows)).
-   - Alternatively you can copy the following command and then 
-     paste it into a terminal to run a Python script 
-     that will download and extract the files for you. 
+   - Alternatively you can copy the following command and then
+     paste it into a terminal to run a Python script
+     that will download and extract the files for you.
 
      :::{eval-rst}
-    
+
      .. tabs::
-    
+
         .. code-tab:: shell macOS / Linux
-    
+
            curl -sSL https://raw.githubusercontent.com/vocalpy/vak/main/src/scripts/download_autoannotate_data.py | python3 -
-     
+
         .. code-tab:: shell Windows
-    
+
            (Invoke-WebRequest -Uri https://raw.githubusercontent.com/vocalpy/vak/main/src/scripts/download_autoannotate_data.py -UseBasicParsing).Content | py -
      :::
 
 4. Download the corresponding configuration files (click to download):
    {download}`gy6or6_train.toml <../toml/gy6or6_train.toml>`,
-   {download}`gy6or6_eval.toml <../toml/gy6or6_eval.toml>`, 
+   {download}`gy6or6_eval.toml <../toml/gy6or6_eval.toml>`,
    and {download}`gy6or6_predict.toml <../toml/gy6or6_predict.toml>`
 
 ## Overview
@@ -181,7 +181,7 @@ Change the part of the path in capital letters to the actual location
 on your computer:
 
 ```toml
-[PREP]
+[vak.prep]
 dataset_type = "frame classification"
 input_type = "spect"
 # we change the next line
@@ -230,11 +230,11 @@ When you run `prep`, `vak` converts the data from `data_dir` into a special data
 automatically adds the path to that file to the `[TRAIN]` section of the `config.toml` file, as the option
 `csv_path`.
 
-You have now prepared a dataset for training a model!  
-You'll probably have more questions about 
-how to do this later, 
-when you start to work with your own data. 
-When that time comes, please see the how-to page: 
+You have now prepared a dataset for training a model!
+You'll probably have more questions about
+how to do this later,
+when you start to work with your own data.
+When that time comes, please see the how-to page:
 {ref}`howto-prep-annotate`.
 For now, let's move on to training a neural network with this dataset.
 
@@ -294,7 +294,7 @@ from that checkpoint later when we predict annotations for new data.
 
 (prepare-prediction-dataset)=
 
-An important step when using neural network models is to evaluate the model's performance 
+An important step when using neural network models is to evaluate the model's performance
 on a held-out dataset that has never been used during training, often called the "test" set.
 
 Here we show you how to evaluate the model we just trained.
@@ -356,33 +356,33 @@ This file will also be found in the root `results_{timestamp}` directory.
 spect_scaler = "/home/users/You/Data/vak_tutorial_data/vak_output/results_{timestamp}/SpectScaler"
 ```
 
-The last path you need is actually in the TOML file that we used 
+The last path you need is actually in the TOML file that we used
 to train the neural network: `dataset_path`.
-You should copy that `dataset_path` option exactly as it is 
-and then paste it at the bottom of the `[EVAL]` table 
+You should copy that `dataset_path` option exactly as it is
+and then paste it at the bottom of the `[EVAL]` table
 in the configuration file for evaluation.
-We do this instead of preparing another dataset, 
-because we already created a test split when we ran 
+We do this instead of preparing another dataset,
+because we already created a test split when we ran
 `vak prep` with the training configuration.
-This is a good practice, because it helps ensure 
+This is a good practice, because it helps ensure
 that we do not mix the training data with the test data;
-`vak` makes sure that the data from the `data_dir` option 
+`vak` makes sure that the data from the `data_dir` option
 is placed in two separate splits, the train and test splits.
 
-Once you have prepared the configuration file as described, 
+Once you have prepared the configuration file as described,
 you can run the following in the terminal:
 
 ```shell
 vak eval gy6o6_eval.toml
 ```
 
-You will see output to the console as the network is evaluated. 
-Notice that for this model we evaluate it *with* and *without* 
-post-processing transforms that clean up the predictions 
+You will see output to the console as the network is evaluated.
+Notice that for this model we evaluate it *with* and *without*
+post-processing transforms that clean up the predictions
 of the model.
-The parameters of the post-processing transform are specified 
+The parameters of the post-processing transform are specified
 with the `post_tfm_kwargs` option in the configuration file.
-You may find this helpful to understand factors affecting 
+You may find this helpful to understand factors affecting
 the performance of your own model.
 
 ## 4. Preparing a prediction dataset
@@ -400,7 +400,7 @@ Just like before, you're going to modify the `data_dir` option of the
 This time you'll change it to the path to the directory with the other day of data we downloaded.
 
 ```toml
-[PREP]
+[vak.prep]
 data_dir = "/home/users/You/Data/vak_tutorial_data/032312"
 ```
 
@@ -428,7 +428,7 @@ and then add the path to that file as the option `csv_path` in the `[PREDICT]` s
 Finally you will use the trained network to predict annotations.
 This is the part that requires you to find paths to files saved by `vak`.
 
-There's three you need. These are the exact same paths we used above 
+There's three you need. These are the exact same paths we used above
 in the configuration file for evaluation, so you can copy them from that file.
 We explain them again here for completeness.
 All three paths will be in the `results` directory

doc/reference/config.md

@@ -19,7 +19,7 @@ for each class.
 ## Valid section names
 
 Following is the set of valid section names:
-`{PREP, SPECT_PARAMS, DATALOADER, TRAIN, PREDICT, LEARNCURVE}`.
+`{eval, learncurve, predict, prep, train}`.
 In the code, these names correspond to attributes
 of the main `Config` class, as shown below.
 
@@ -43,50 +43,42 @@ that are considered valid.
 Valid options for each section are presented below.
 
 (ref-config-prep)=
-### `[PREP]` section
+### `[vak.prep]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.prep.PrepConfig
 ```
 
 (ref-config-spect-params)=
-### `[SPECT_PARAMS]` section
+### `[vak.prep.spect_params]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.spect_params.SpectParamsConfig
 ```
 
-(ref-config-dataloader)=
-### `[DATALOADER]` section
-
-```{eval-rst}
-.. autoclass:: vak.config.dataloader.DataLoaderConfig
-
-```
-
 (ref-config-train)=
-### `[TRAIN]` section
+### `[vak.train]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.train.TrainConfig
 ```
 
 (ref-config-eval)=
-### `[EVAL]` section
+### `[vak.eval]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.eval.EvalConfig
 ```
 
 (ref-config-predict)=
-### `[PREDICT]` section
+### `[vak.predict]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.predict.PredictConfig
 ```
 
 (ref-config-learncurve)=
-### `[LEARNCURVE]` section
+### `[vak.learncurve]` section
 
 ```{eval-rst}
 .. autoclass:: vak.config.learncurve.LearncurveConfig

doc/toml/gy6or6_eval.toml

@@ -1,4 +1,4 @@
-[PREP]
+[vak.prep]
 # dataset_type: corresponds to the model family such as "frame classification" or "parametric umap"
 dataset_type = "frame classification"
 # input_type: input to model, either audio ("audio") or spectrogram ("spect")
@@ -19,16 +19,15 @@ train_dur = 50
 val_dur = 15
 
 # SPECT_PARAMS: parameters for computing spectrograms
-[SPECT_PARAMS]
+[vak.prep.spect_params]
 # fft_size: size of window used for Fast Fourier Transform, in number of samples
 fft_size = 512
 # step_size: size of step to take when computing spectra with FFT for spectrogram
 # also known as hop size
 step_size = 64
 
 # EVAL: options for evaluating a trained model. This is done using the "test" split.
-[EVAL]
-model = "TweetyNet"
+[vak.eval]
 # checkpoint_path: path to saved model checkpoint
 checkpoint_path = "/PATH/TO/FOLDER/results/train/RESULTS_TIMESTAMP/TweetyNet/checkpoints/max-val-acc-checkpoint.pt"
 # labelmap_path: path to file that maps from outputs of model (integers) to text labels in annotations;
@@ -51,7 +50,7 @@ output_dir = "/PATH/TO/FOLDER/results/eval"
 # ADD THE dataset_path OPTION FROM THE TRAIN FILE HERE (we already created a test split when we ran `vak prep` with that config)
 
 # EVAL.post_tfm_kwargs: options for post-processing
-[EVAL.post_tfm_kwargs]
+[vak.eval.post_tfm_kwargs]
 # both these transforms require that there is an "unlabeled" label,
 # and they will only be applied to segments that are bordered on both sides
 # by the "unlabeled" label.
@@ -65,12 +64,11 @@ majority_vote = true
 # Only applied if this option is specified.
 min_segment_dur = 0.02
 
-# transform_params: parameters used when transforming data
-# for a frame classification model, we use FrameDataset with the eval_item_transform,
-# that reshapes batches into consecutive adjacent windows with a specific `window_size`
-[EVAL.transform_params]
+# dataset.params = parameters used for datasets
+# for a frame classification model, we use dataset classes with a specific `window_size`
+[vak.eval.dataset.params]
 window_size = 176
 
-# Note we do not specify any options for the network, and just use the defaults
-# We need to put this "dummy" table here though for the config to parse correctly
-[TweetyNet]
+# Note we do not specify any options for the model, and just use the defaults
+# We need to put this table here though so we know which model we are using
+[vak.eval.model.TweetyNet]

doc/toml/gy6or6_predict.toml

@@ -1,5 +1,5 @@
 # PREP: options for preparing dataset
-[PREP]
+[vak.prep]
 # dataset_type: corresponds to the model family such as "frame classification" or "parametric umap"
 dataset_type = "frame classification"
 # input_type: input to model, either audio ("audio") or spectrogram ("spect")
@@ -15,17 +15,15 @@ audio_format = "wav"
 # all data found in `data_dir` will be assigned to a "predict split" instead
 
 # SPECT_PARAMS: parameters for computing spectrograms
-[SPECT_PARAMS]
+[vak.prep.spect_params]
 # fft_size: size of window used for Fast Fourier Transform, in number of samples
 fft_size = 512
 # step_size: size of step to take when computing spectra with FFT for spectrogram
 # also known as hop size
 step_size = 64
 
 # PREDICT: options for generating predictions with a trained model
-[PREDICT]
-# model: the string name of the model. must be a name within `vak.models` or added e.g. with `vak.model.decorators.model`
-model = "TweetyNet"
+[vak.predict]
 # checkpoint_path: path to saved model checkpoint
 checkpoint_path = "/PATH/TO/FOLDER/results/train/RESULTS_TIMESTAMP/TweetyNet/checkpoints/max-val-acc-checkpoint.pt"
 # labelmap_path: path to file that maps from outputs of model (integers) to text labels in annotations;
@@ -61,12 +59,11 @@ majority_vote = true
 min_segment_dur = 0.01
 # dataset_path : path to dataset created by prep. This will be added when you run `vak prep`, you don't have to add it
 
-# transform_params: parameters used when transforming data
-# for a frame classification model, we use FrameDataset with the eval_item_transform,
-# that reshapes batches into consecutive adjacent windows with a specific `window_size`
-[PREDICT.transform_params]
+# dataset.params = parameters used for datasets
+# for a frame classification model, we use dataset classes with a specific `window_size`
+[vak.predict.dataset.params]
 window_size = 176
 
 # Note we do not specify any options for the network, and just use the defaults
-# We need to put this "dummy" table here though for the config to parse correctly
-[TweetyNet]
+# We need to put this table here though, to indicate which model we are using.
+[vak.predict.model.TweetyNet]

doc/toml/gy6or6_train.toml

@@ -1,5 +1,5 @@
 # PREP: options for preparing dataset
-[PREP]
+[vak.prep]
 # dataset_type: corresponds to the model family such as "frame classification" or "parametric umap"
 dataset_type = "frame classification"
 # input_type: input to model, either audio ("audio") or spectrogram ("spect")
@@ -22,17 +22,15 @@ val_dur = 15
 test_dur = 30
 
 # SPECT_PARAMS: parameters for computing spectrograms
-[SPECT_PARAMS]
+[vak.prep.spect_params]
 # fft_size: size of window used for Fast Fourier Transform, in number of samples
 fft_size = 512
 # step_size: size of step to take when computing spectra with FFT for spectrogram
 # also known as hop size
 step_size = 64
 
 # TRAIN: options for training model
-[TRAIN]
-# model: the string name of the model. must be a name within `vak.models` or added e.g. with `vak.model.decorators.model`
-model = "TweetyNet"
+[vak.train]
 # root_results_dir: directory where results should be saved, as a sub-directory within `root_results_dir`
 root_results_dir = "/PATH/TO/FOLDER/results/train"
 # batch_size: number of samples from dataset per batch fed into network
@@ -58,23 +56,20 @@ num_workers = 4
 device = "cuda"
 # dataset_path : path to dataset created by prep. This will be added when you run `vak prep`, you don't have to add it
 
-# train_dataset_params: parameters used when loading training dataset
-# for a frame classification model, we use a WindowDataset with a specific `window_size`
-[TRAIN.train_dataset_params]
+# dataset.params = parameters used for datasets
+# for a frame classification model, we use dataset classes with a specific `window_size`
+[vak.train.dataset.params]
 window_size = 176
 
-# val_transform_params: parameters used when transforming validation data
-# for a frame classification model, we use FrameDataset with the eval_item_transform,
-# that reshapes batches into consecutive adjacent windows with a specific `window_size`
-[TRAIN.val_transform_params]
-window_size = 176
-
-# TweetyNet.optimizer: we specify options for the model's optimizer in this table
-[TweetyNet.optimizer]
+# To indicate the model to train, we use a "dotted key" with `model` followed by the string name of the model.
+# This name must be a name within `vak.models` or added e.g. with `vak.model.decorators.model`
+# We use another dotted key to indicate options for configuring the model, e.g. `TweetyNet.optimizer`
+[vak.train.model.TweetyNet.optimizer]
+# vak.train.model.TweetyNet.optimizer: we specify options for the model's optimizer in this table
 # lr: the learning rate
 lr = 0.001
 
 # TweetyNet.network: we specify options for the model's network in this table
-[TweetyNet.network]
+[vak.train.model.TweetyNet.network]
 # hidden_size: the number of elements in the hidden state in the recurrent layer of the network
 hidden_size = 256