(spect-file-format)=

# Spectrogram file format

## File type

`vak` uses pre-computed files containing spectrograms.

For these files, it accepts two types, either `.npz` or `.mat`.
`.npz` is a `numpy` library format,
for a file that can contain multiple arrays.
`.mat` is the Matlab data file format---many labs
have existing codebases that generate spectrograms using Matlab.
To work with one of these formats,
you will specify either `npz` or `vak` in the `[PREP]` section
of your `.toml` configuration file.

:::{note}
`vak` loads `.mat` files with the function `scipy.io.loadmat`. 
That function can only load 
v4 (Level 1.0), v6 and v7 to 7.2 matfiles as stated here: 
<https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.loadmat.html>
Version 7.3 of the matfile format uses an HDF5-based format, 
which is not supported by `scipy` or `vak`.
(For more details see 
[this page in the Matlab documentation](https://www.mathworks.com/help/matlab/import_export/mat-file-versions.html)
)
If you have are working with Matlab, 
please either save your `.mat` files 
in a format that can be ready by `scipy.io.loadmat`,
or convert your data to `.npz` files 
as described in {ref}`howto-user-spect`.
:::

## Conventions

Regardless of whether they are `.npz` files or `.mat` files,
`vak` expects any spectrogram files to obey the following conventions.

### Content

A spectrogram array files should contain (at least) four items.
Other arrays can be in the file, but they will be ignored.

1. The spectrogram, an *m x n* matrix
2. A vector of *m* frequency bins,
   where the value of each element is the frequency at the center of the bin
3. A vector of *n* time bins,
   where the value each element is the time at the center of the bin
4. A string path to the audio file from which the spectrogram was generated.

### Array naming

By convention each should be associated with a string key: 's', 'f', 't', and 'audio_path'.
If you are using Matlab then you will need to save your workspace variables with these names.

### Spectrogram file naming

The *name* of each spectrogram file *must* be the **same**
as the name of the audio file it was created from, with the spectrogram file format added.
E.g., if your audio file is `bird1.wav`, then the spectrogram file should be `bird1.wav.npz`.

(example-spect-file-format)=
### Example array files that meet this spectrogram file format specification
Please click on this link to download a .tar.gz archive containing 
spectrogram files generated by a run of `vak prep` on audio data:
<https://osf.io/9cedz/download>

You can inspect the contents `.npz` array files by loading them with `numpy.load`

These files are provided to demonstrate the specification described here. 
You may find them helpful as examples 
if you prefer to generate your own spectrograms, 
and you need to write a script to create array files 
containing your spectrograms so `vak` can work with them, 
as described in {ref}`howto-user-spect`.
