Getting Started with Raven Expedition

Why use LTSAs?

A long-term spectral average is a good way to visually explore a collection of audio data for patterns. Read More about examples of why and how LTSAs are used here.

Create LTSA

There are several ways to do this:

A. New LTSA

1. File menu -> New LTSA
2. Select data source — In the file chooser, select the root folder for your data. All files from this root folder and all its subfolders will be used for the LTSA, though they must all have a matching sample rate and encoding
3. Configure signal — After the data folder is selected, Expedition reads all sound files in the selected root directory recursively, creates the signal source, and displays the signal source information in the Set up Signal and Configure LTSA Input Parameters dialog. You can choose to use the file timestamps for real time and labels by specifying the Timestamp Format.
4. Specify the time and frequency resolution (the time or frequency average) in the LTSA Input Parameters tab. Parameters can be saved as a preset for future reuse.
5. Specify frequency axis (Hybrid-millidecade or linear).
6. Specify auto save file name if you choose to auto save the resulting LTSA file after the calculation is finished.
7. After clicking OK on the Setup dialog, LTSA will be calculated and displayed.
   

B. New LTSA with Calendar

1. File menu -> New LTSA With Calendar
2. Select data source — in the file chooser, select the root folder for your data. You’ll be able to select which files you want included in the LTSA in the next step.
3. Once all sound files are read, they are entered in the Calendar View with each sound file as an event. In the calendar view, you can select a portion of data set to create LTSA.
4. Follow steps 3-7 from section A above.

C. New LTSA from Raven Signal

1. Raven Signal created from the two methods above, or from other Raven apps like Compass, can be saved as a *.ravenSignal file and reused later
   • A signal file is a list file with a lot of enhancements, and it makes it easy to open up all the same files again (e.g. you might want to create an LTSA with the same data but different parameters)
2. Select a saved *.ravenSignal file from the file chooser
3. Follow steps 3-7 from section A above.

You can also drag and drop entire folders or sound files, or Raven Signal files, to create LTSA.

Navigate and View LTSA

• There are zoom to selection, fit all, page forward/backward on the tool bar.
• Click on the event in the event table will pan to the event (same behavior as in Raven Pro)
• Jump to: allows you to select a date from the calendar to jump the LTSA view to that date
• Zoom in/out X and Y, fit X, fit Y buttons at the lower right corner
• If you used “Jump to” or the page forward/backward buttons, then scrolled or zoomed in your LTSA, you can click the “Apply” button again to return to the last place where you used the toolbar. Those numbers don’t change with zooming or scrolling.
• In the View menu, select “Time Coverage” to show how much coverage your data has in a calendar view. Bright green fill means a day has all or most of the data, lighter green means you have less than a full day of data, white boxes have no data.
  • If you don’t have much data in an average “day”, enable the Normalize option which takes the day with the most data and compares everything relevant to that.
  • You can turn on Use Histogram to switch from shades of green to a % filled related to the amount of data for that day

Shortcut keys/mouse/touchpad behaviors for navigation

These apply to both LTSA and wave/spectrogram views:

Keyboard

• CTRL/CMD + and – for zoom in/out horizontally. This works with Number pad and non-number pad.
• CTRL/CMD +ALT/option + and – for zoom in/out vertically.
• F1-F6 shortcuts same as in Raven Pro

Mouse

• CTRL/CMD + scroll wheel to zoom horizontally.
• CTRL/CMD + SHIFT + scroll wheel to zoom vertically
• Scroll wheel (no modifier) to pan horizontally
• SHIFT + scroll wheel to pan vertically
• Press middle mouse button and drag to pan both horizontally and vertically

Touchpad

• CTRL/CMD + two fingers left/right to zoom left/right horizontally
• Two fingers down/up to pan down/up vertically
• Two fingers left/right to pan left/right horizontally
• CTRL/CMD + two fingers down/up to zoom out/in vertically

Selections, annotations, and event table

Selections

• Similar to Raven Pro, to make a selection, draw a box (left mouse press and drag) on the LTSA chart to select an event, hit enter/return key to commit the selection.
• You can select the Auto Commit checkbox at the top of the Table window to commit after releasing the mouse button when drawing a selection box (rather than needing to hit Enter/Return)

Event table

• Event table can be saved (File menu -> Save event table), and reloaded (File menu -> Open event table)
• Backspace key to delete an event selection from the table
• Right click above an empty column on the table header to:
  1. add an annotation column. To edit the cell of annotation column on MAC, you have to hit enter or double-click to get into editing mode.
  2. Add additional available measurements
• Right click on the Time or Frequency columns to change their format
• Event table is saved in a json file *.raventable along with the signal source (can be viewed with text editor)

Annotation

Right click above an empty column on the event table header to add annotation columns. Options for annotating while making selections include:

1. Enabling “Use overlay for annotations” in Preferences -> General options. After you commit your selection, a popup text field allows you to add annotations to that selection, which appear in
2. Enabling Annotation Keymap (Command+T/Ctrl+T). This toggles the function of shortcut keys for annotating selections/events. You can set these shortcuts under Edit > Annotation Keymap.

Note that if you have both of these options enabled, Expedition will default to the active text field in the annotation overlay first. Only when clicking out of a selection then re-selecting it will keyboard shortcuts be re-enabled.

Wave and Spectrogram View

1. With an event selected on the LTSA chart or in the event table, you can click the “Wave and Spectrogram View” button on the upper left corner to review the wave and spectrogram associated with the sound signals within the event time box
2. Navigation in this view is similar to LTSA
3. Spectrogram parameters can be modified in the “Configure Spectrogram Parameters” dialog, accessed via the setting button (gear like button upper left side of the tool bar).
4. You can play the sound or selected event, change the play speed etc
5. Selection of events and event table work similar to that in LTSA view

Edit Display Options in Preferences

1. Edit menu -> Preferences
2. Change file boundaries color, max number
3. Use Duty Cycle Axis: in conjunction with Pad Gap unchecked (in Set up Raven Signal), this will plot all recording files together (without gap), and the time axis ticks will mark the true time at the beginning of each file (based on timestamp of the file) and actual time within each file. 
4. View -> Overlap: the page forward/backward overlap percentage

Save LTSA and Raven Signal

• Once LTSA is created, you can save it to a *.ravenltsa file and reopen it later.
• You can also save the Raven Signal (mostly the list of sound files) and reuse it later to create another LTSA or used it in other app (in the future).
• When saving a new LTSA with the “Pad Gaps” option enabled, saved power spectral density values in the padded gaps will be set to -∞.

Calibration

• Calibrate your data in the Edit menu -> Calibration. Additional offset applies across all frequency bins, and/or load a transfer function.
• A .ravencalibration file is saved in the same location as your LTSA. When you re-open the LTS file, the software looks for a calibration file in the same location with the same name. 
  • Note: If you send someone a Raven Expedition LTSA file, you’ll need to send this calibration file along as well (or share the calibration preset you saved).

Change Language

1. Edit menu, ->Language, select desired language, click “Apply”. Restart app for the change to take effect.
2. Some translated languages have not been proof read
3. We still have to figure out how to configure some system default dialogs or buttons (File chooser etc)’s language to match our language selection.  As such you will see a few OK, Cancel etc. buttons still in English.  They will be fixed before official release.

Toolbars

Jump to time

• Clicking on the small calendar icon brings up a calendar view, which shows which days have data (red blocks have no data). Clicking on a date adds that value to the field in YYYYMMDD format. Add hours and minutes to jump a specific time
• Change the duration shown in the field of view with values in the “visible duration” fields (e.g. 2 hours of data at a time).
  • Minutes max out at 59, Hours at 23, Days at 90 when typing them out
    • You can use a mouse scroll wheel to scroll past these limits – e.g. 25 hours will update to 1 day 1 hour when scrolling
• If you used “Jump to” or the page forward/backward buttons, then scrolled or zoomed in your LTSA, you can click the “Apply” button again to return to the last place where you used the toolbar. Those numbers don’t change with zooming or scrolling.

LTSA

• The Wave and Spectrogram View (Command+G/Ctrl+G) button shows a spectrogram view of the active selection.
• Enable/Disable Annotation Keymap (Command+T/Ctrl+T) toggles the function of shortcut keys for annotating selections/events. You can set these shortcuts under Edit > Annotation Keymap.
• Rolling Average button applies across the visible portion of the LTSA, removing much of the consistent background noise by subtracting a rolling average (only visually, not changing the underlying data or decibel values)
  • Because it’s a rolling average across the visible area, shifting your view could alter the average and the way these are displayed

Navigate

• Timezone shift dropdown
• Pan (Command/Ctrl + ,) toggles the ability to use the primary mouse button to pan around the view
• Fit all (Command/Ctrl + A) zooms out to show the entire signal into the window
• Zoom to Selection (Command/Ctrl + L) zooms the view to fit the current selection
• Page backward and forward (Command/Ctrl + ← or →) moves the view backward or forward a “page”. You can set the duration shown in the field of view in the Jump to time toolbar, and the amount of overlap for these pages in Edit > Preferences > Views.

Playback

• Play (Alt/Opt + P) – Plays the active selection or the entire opened set of sound files
• Stop (Alt/Opt + S) – Stops playback
• Rate – Change the speed of playback by entering a multiple of the normal speed (e.g. 2.00 is twice as fast)

Spectrogram

• Brightness and Contrast sliders change the respective values, altering the colormap
• Colormap dropdown has different color scheme display options
• Invert colormap (Command/Ctrl + I) flips the colormap vertically
  

Shortcut Keys Summary