Example Usage

The following examples show basic usage of the arfx tool for moving data in and out of ARF files.

Adding data to ARF files

Create a new ARF file and add a number of WAV files to it. I specify my name, the ID of the animal, the experimental protocol, the data type, and the amplifier type to be stored as metadata with the entries.

$ arfx -cvf newfile.arf -a st489 -e dmeliza -p soundbox -T ACOUSTIC -k amp=DMP5 mywave1.wav mywave2.wav mywave3.wav
mywave1.wav/0 -> /mywave1/pcm
mywave2.wav/0 -> /mywave2/pcm
mywave3.wav/0 -> /mywave3/pcm

Create a new ARF file and add all the entries in a pcm_seq2 file to it

$ arfx -cvf newfile.arf data.pcm_seq2
data.pcm_seq2/1 -> /data_0001/pcm
data.pcm_seq2/2 -> /data_0002/pcm
data.pcm_seq2/3 -> /data_0003/pcm
data.pcm_seq2/4 -> /data_0004/pcm
...

Add entries from a pcm_seq2 to an existing file and name them sequentially

$ arfx -rvf oldfile.arf -n awesomedata data2.pcm_seq2
data2.pcm_seq2/1 -> /awesomedata_0004/pcm
data2.pcm_seq2/2 -> /awesomedata_0005/pcm
data2.pcm_seq2/3 -> /awesomedata_0006/pcm
data2.pcm_seq2/4 -> /awesomedata_0007/pcm
...

Copy several entries from one arf file to another, renaming the entries

$ arfx -Avf newfile.arf -n newname oldfile.arf/data_0001 oldfile.arf/data_0002 oldfile.arf/data_0003
oldfile.arf/data_0001 -> /newname_0000
oldfile.arf/data_0002 -> /newname_0001
oldfile.arf/data_0003 -> /newname_0002

Inspect ARF file

List contents of file

$ arfx -tf st489_20090714.arf
/st489_1_20090714a_0001/pcm_000
/st489_1_20090714a_0001/pcm_001
/st489_1_20090714a_0002/pcm_000
/st489_1_20090714a_0002/pcm_001
...

Inspect specific entries

$ arfx -tf newfile.arf mywave1
/mywave1
  timestamp : Thu Jun 10 18:01:19 2010
  animal : st489
  experimenter : dmeliza
  protocol : soundbox
  amp : DMP5
  /pcm : 558374 samples @ 48000/s, type ACOUSTIC (node pcm/0)

Edit ARF metadata

Change the protocol to 'soundroom', clear the amp key, and and add a new key, testosterone=yes

$ arfx -Uvf newfile.arf -p soundroom -k testosterone=yes -k amp='' mywave1
vvvvvvvvvv
/mywave1
  timestamp : Thu Jun 10 18:01:19 2010
  animal : st489
  experimenter : dmeliza
  protocol : soundbox
  amp : DMP5
  /pcm : 558374 samples @ 48000/s, type ACOUSTIC (node pcm/0)
**********
/mywave1
  timestamp : Thu Jun 10 18:01:19 2010
  animal : st489
  experimenter : dmeliza
  protocol : soundroom
  testosterone : yes
  /pcm : 558374 samples @ 48000/s, type ACOUSTIC (node pcm/0)
^^^^^^^^^^

Store text files in top-level attributes

This function is useful for importing log and settings files into the ARF container.

$ arfx --write-attr -f newfile.arf experiment_notes.txt
experiment_notes.txt -> newfile.arf/user_experiment_notes.txt

To read out the contents of the attribute

$ arfx --read-attr -f newfile.arf experiment_notes.txt

Note that the attribute is given the prefix user_ to help avoid collisions.

Extract entries from ARF file

All entries from a file

$ arfx -xvf newfile.arf
/mywave1/pcm -> mywave1.wav
/mywave2/pcm -> mywave2.wav
/mywave3/pcm -> mywave3.wav

Specific entries from a file

$ arfx -xvf newfile.arf data_0001 data_0002
/data_0001/pcm -> data_0001.wav
/data_0002/pcm -> data_0002.wav

Data from multi-channel entries

$ arfx -xvf st489_20090714.arf st489_1_20090714a_0001
/st489_1_20090714a_0001/pcm_000 -> st489_1_20090714a_0001_pcm_000.wav
/st489_1_20090714a_0001/pcm_001 -> st489_1_20090714a_0001_pcm_001.wav

Deleting entries from files

Use with care!

$ arfx -dvf st489_20090714.arf st489_1_20090714a_0001
/st489_1_20090714a_0001
Repacking st489_20090714.arf...done

In order to free up space, arfx has to repack the ARF file. Use the -P option to turn off this behavior, which can be time-consuming for large files.