We've updated our privacy policy.

Download EDFs programmatically

Downloading EDFs programmatically

In this tutorial, you will learn how to:

  1. Launch a Ruby script that downloads files from the NSRR.
  2. Open the downloaded EDFs and print their filenames.

The Requirements for running this tutorial are described after the discussion of the tutorial script.

Important! This tutorial demonstrates downloading files using a Ruby script from the NSRR programmatically. If you simply want to download files on the NSRR via command line, you can view the NSRR demo.

The script

require 'rubygems'
require 'colorize'
require 'edfize'
require 'nsrr'
require 'nsrr/commands/download'

Nsrr::Commands::Download.run(%w(download learn/polysomnography/edfs/learn-nsrr01.edf --token=public))
Nsrr::Commands::Download.run(%w(download learn/polysomnography/edfs/learn-nsrr02.edf --token=public))
Nsrr::Commands::Download.run(%w(download learn/polysomnography/edfs/learn-nsrr03.edf --token=public))

puts "EDFs Downloaded: #{Edfize.edf_paths.count}"
Edfize.edfs.each do |edf|
  puts "  #{edf.filename}"

puts 'GOOD'.colorize(:green) + " Ruby #{RUBY_VERSION}"
puts 'GOOD'.colorize(:green) + " Edfize #{Edfize::VERSION::STRING}"
puts 'GOOD'.colorize(:green) + " NSRR Gem #{Nsrr::VERSION::STRING}"

if Edfize.edf_paths.count.zero?
  puts "EDFs weren't downloaded.".colorize(:red).on_white
  puts "Congrats! You have completed your first tutorial!".colorize(:green).on_white

download script

Breaking down the script

This script leverages the nsrr and the edfize gems to download and open EDFs respectively.

Downloading a file


This command passes an array of strings to the NSRR gem and requests a specific file to be downloaded. The command parameters mimic those passed to the NSRR gem when downloading files via command line. The %w() portion of the command takes its input and creates an array of strings splitting the strings on white space.

For example:

%w(Hello world!) is identical to ["Hello", "world!"]

While this script calls the command once for each EDF, it is also possible to download all files in a folder by specifying the containing folder.

Nsrr::Commands::Download.run(%w(download learn/polysomnography/edfs --token=public))

Doing so will download all files in the specified folder, as well as any file in a subfolder. You could pass the --shallow flag to the command if you wanted to ignore files in subfolders.

Nsrr::Commands::Download.run(%w(download learn/polysomnography/edfs --shallow --token=public))

Iterating through and loading EDFs

Edfize.edfs.each do |edf|
  puts "  #{edf.filename}"

edfize has two methods to help iterate through EDFs. The first Edfize.edfs, creates a Ruby enumerator that loads each EDF into memory, providing methods to read and write the EDF header, signal header, and signals. These methods are covered in the following tutorials.

edfize also provides a list of the filenames directly using Edfize.edf_paths. Calling edf_paths will generate an enumerator of strings representing the EDF file locations, without loading the EDFs into memory. In this script, edf_paths is used to get a quick count of EDFs.

Finishing the script

The script finishes by displaying the currently installed versions of Ruby, and the edfize and nsrr gems. colorize is used to color the command line output, however it is not necessary. For example, the lines could be rewritten as:

puts "GOOD Ruby #{RUBY_VERSION}"
puts "GOOD Edfize #{Edfize::VERSION::STRING}"

The script finished by printing a message to the screen based on if EDFs were successfully downloaded or not.

Try These

  1. Edfize provides a method called edf_size that returns the number of bytes in the EDF. Modify the script to display the EDF filename, followed by EDF size in megabytes.
  2. Simplify the script using the --shallow flag to download all the EDFs in the polysomnography/edfs folder without listing each one explicitly.

If you completed this tutorial, please leave a review and check out the next tutorial in the series:

Tutorial 02 - Read EDF Header and Signal Header


This tutorial requires that you have Ruby 2.2 or above installed, preferably Ruby 2.3 or higher.


Extract the script to your desktop to a folder of the same name. Open your console (Command Prompt on Windows or Terminal on Mac/Linux) and navigate to your tutorial folder.


cd ~/Desktop/tutorial_01


cd %USERPROFILE%\Desktop\tutorial_01


  • cd stands for "Change Directory"
  • ~, and %USERPROFILE% represents your user home directory

Installing the required gems.

This script requires you to have the colorize, nsrr, and edfize gems installed. The colorize gem is used to color command line output. The nsrr gem is used to easily download sets of files from the National Sleep Research Resource (https://sleepdata.org). The edfize gem is used to read and write EDF files using Ruby.

In your console type:

gem install colorize edfize nsrr --no-document

This command will get you the latest stable release of the colorize, nsrr, and edfize gem from RubyGems.org. The --no-document flag specifies to skip the installation of the documentation for the gems.

Running the script.

In your console and from the tutorial_01 directory, type:

ruby tutorial_01.rb

If everything goes well, you should have three EDFs successfully downloaded from the NSRR in tutorial_01/learn/polysomnography/edfs/, and also a short message informing you of the versions of Ruby, nsrr, and edfize that were used.


Remember, if you have any questions on this script, please let us know on the NSRR forum here: https://sleepdata.org/forum, or email us at support@sleepdata.org.