wonambi-python / wonambi

Package to analyze EEG, ECoG and other electrophysiology formats. It allows for visualization of the results and for a GUI that can be used to score sleep stages.

WONAMBI

Package for the analysis of EEG, ECoG and other electrophysiology modalities. Allows for visualization of the data and sleep stage scoring in a GUI. Provides automatic detectors for spindles and slow waves.

Features

• Can read files of format:
  • Axon (.abf, ABF2 only)
  • BCI2000 (.dat)
  • Blackrock (.nev, .ns2, .ns3, .ns5)
  • Brain Vision (.vhdr, .vmrk, .eeg / .dat)
  • EEGLAB (.set, .set / .fdt)
  • European Data Format (.edf)
  • EGI MFF (.mff)
  • Fieldtrip (.mat)
  • mne FIFF (.fiff)
  • SystemPlus Micromed (.trc)
  • Moberg ("EEG,Composite,SampleSeries,Composite,MRIAmp,data")
  • openephys (.continuous, .openephys)
  • BIDS-formatted data file
• Interface for Sleep Scoring
• Computes frequency analysis (spectrogram), time-frequency analysis (short-time spectrogram, Morlet wavelet)
• Detection of spindles and slow waves
• Pure Python

Installation

Install wonambi by running:

pip3 install wonambi

See Installation for details

If you want to scroll recordings and do some sleep scoring (requires PyQt5)

wonambi

Run it!

From the command line, simply type:

wonambi

To open a dataset directly, add the full path to the file you want to open:

wonambi /home/me/sleep_recordings.edf

Documentation

See Documentation

Change Log

See Change Log

Requirements

• Python 3.6 or later
• numpy
• scipy

Optional Requirements

• PyQt5 (optional for sleep scoring GUI)
• python-vlc (optional, to watch embedded movies)
• vispy (optional to plot 3D brain surfaces and electrodes)
• h5py (optional to read FieldTrip Matlab files)
• mne (optional, to export to mne FIFF files)
• nibabel (optional to read freesurfer)
• tensorpac (optional to run phase-amplitude analysis, tensorpac version should be 0.5.6)
• fooof 1.0 (optional to run parametrization of power spectra)

Status

License

The project is licensed under the 3-clause BSD license.

wonambi's Issues

Documentation on use with Python.

Hey there,

I'd like to use wonambi to load some lfp recordings for further processing in Python. Unfortunately, I wasn't able to find anything on using this package without the GUI in the docs. Could anyone give me a minimal example of how to read in a '.ns3' file?

If there is any documentation on this, then it should probably be a bit more prominent. If there isn't, then it should definitely be added to the docs.

Thanks in advance.

wonambi --bids does not read events

Wonambi - startup TypeError on Windows

Hi, thanks for the great piece of software. I've been using it for sleep scoring and spindle detection on MacOS, which has been working like a charm. Recently I had to move to Windows. Currently I'm using the following setup:

64-bit Windows 7
Anaconda 4.5.9.
Python 3.6.5

after setting up wonambi according to the installation guide I have tried to startup wonambi, which resulted in the following error:

c:\users\anaconda\anaconda3\lib\site-packages\h5py\__init__.py:36: FutureWarning: Conversion of the second argument of issubdtype from `float` to `np.floating` is deprecated. In future, it will be treated as `np.float64 == np.dtype(float).type`.
  from ._conv import register_converters as _register_converters
11:39:16  WONAMBI v5.32
qt.qpa.fonts: Unable to open default EUDC font: "C:\\windows\\FONTS\\EUDC.TTE"
Traceback (most recent call last):
  File "c:\users\anaconda\anaconda3\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\users\anaconda\anaconda3\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Users\anaconda\anaconda3\Scripts\wonambi.exe\__main__.py", line 9, in <module>
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\scroll_data.py", line 305, in main
    q = MainWindow()
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\scroll_data.py", line 67, in __init__
    self.create_widgets()
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\creation.py", line 49, in create_widgets
    MAIN.traces = Traces(MAIN)
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\traces.py", line 175, in __init__
    self.config = ConfigTraces(self.parent.overview.update_position)
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\traces.py", line 67, in __init__
    super().__init__('traces', update_widget)
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\settings.py", line 206, in __init__
    self.value = self.create_values(value_names)
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\settings.py", line 228, in create_values
    output[value_name] = read_settings(self.widget, value_name)
  File "c:\users\anaconda\anaconda3\lib\site-packages\wonambi\widgets\settings.py", line 337, in read_settings
    val = settings.value(setting_name, default_value, type=default_type)
TypeError: unable to convert a QVariant of type 10 to a QMetaType of type 2

So far I couldn't figure out how to resolve this error. Maybe this is a known issue on Windows?

ENH: notch filter in GUI

Bug: Read open bci2000 files

I found a bug in the source code for reading bci2000 files.
The value for the path is stored in self.filename but this is a string and cannot be opened with self.filename.open("rb") instead use open(self.filename,"rb").

I will submit a Pull Request to change this.

spindle detection example

Hi,

First of all I would like to thank you for providing such a library which was exactly what I was looking for !

I am a PhD student under A. Gramfort's supervision and I am currently working on spindle detection. I would like to use the methods you have implemented in my benchmark. Would you have a running example / notebook to illustrate how to perform spindle detection with wonambi from the edf extraction up to the detection ?

Furthermore, how should I cite this library ?

Thanks in advance,
Stanislas Chambon

Wamsley2012 peak_val_det is incorrect

Hi Wonambi Team,
Looks like there is a bug in the Wamsley2012 algo (and maybe others)
The spindle amplitudes in peak_val_det are off by a good factor of 1e7 (values around 500,000,000).
For example, running the Ferrarelli2007 algorithm on the same data gives values around 50uV

Is Moelle2011 the right citation?

Currently, the Moelle2011 spindle detection method is referenced with Moelle, M. et al. J. Neurosci. 22(24), 10941-7 (2002).. There is indeed a publication from Moelle et al. from 2011 available as well, however, it distinguishes between fast and slow spindles, whereas the algorithm implemented (as far as I can see it) does not implement this currently, but more closely resembles the original method of Moelle from 2002.

Would it be more appropriate to rename the method to "Moelle2002" instead? I'm not sure if I'm missing things, just want to make sure I'm referencing the right methods paper in our publication.

can't click slow wave button!

Why is the slow wave button gray and can't be clicked?

Can't read erd data

There is an error related to the conversion factor. Would you happen to know how to fix this?

Traceback (most recent call last):
  File "/home/repo/convert_debug.py", line 122, in <module>
    main()
  File "/home/repo/convert_debug.py", line 80, in main
    data = d.read_data(
  File "/home/repo/wonambi/wonambi/dataset.py", line 395, in read_data
    dat = dataset.return_dat(idx_chan, one_begsam, one_endsam)
  File "/home/repo/wonambi/wonambi/ioeeg/ktlx.py", line 950, in return_dat
    dat_rec = _read_erd(erd_file, begpos_rec, endpos_rec)
  File "/home/repo/wonambi/wonambi/ioeeg/ktlx.py", line 606, in _read_erd
    factor = _calculate_conversion(hdr)
  File "/home/repo/wonambi/wonambi/ioeeg/ktlx.py", line 234, in _calculate_conversion
    raise NotImplementedError('Implement conversion factor for headbox ' +
NotImplementedError: Implement conversion factor for headbox 20

Lacourse 2018 very slow

Hi Wonambi Team,
First, thank you for this amazing package!
I'm using it to apply the Lacourse 2018 detector. This detector is very slow. It's 'moving_power_ratio' that seems to be slow. I'm wondering if there are some code optimizations possible. For example, unless im mistaken, line 1347 and line 1353 do the same thing, twice:

sf, psd = periodogram(windat, s_freq, 'hann', nfft=nfft,
                                       detrend='constant')

That should give a factor of 2 speed up at least. There are also a lot of regular python functions which could be numpy functions to also speed things up (sum vs np.sum).
I don't know if you guys have time, but if so, it would help speed up the 2000 records id like to detect spindles for ;)

ENH: time point when you click on time window

Using Open Ephys .dat files

Hi,

I would like to use Wonambi for data that I will be acquiring with Open Ephys, but I can see that Open Ephys have changed their format from .continuous to .dat (https://open-ephys.github.io/gui-docs/User-Manual/Recording-data/Binary-format.html) which I can't open with Wonambi (it crashes). Is there a way around this or would it be possible to implement the new format?
Thanks in advance! :-)

Best,
Natalie

Check that the vmrk has correct datetime

FOOOF Version

Hey Wonambi devs - I just wanted to let you know what quite soon a major new release version of FOOOF (1.0) will go live. This version does include some API breaking changes for some names, as we've worked to bring the API closer to the naming scheme we want to us. The underlying algorithm is basically the same, though 1.0 does also have some extra utilities.

I wanted to let you know since as it is, I believe wonambi is set up to use FOOOF 0.3.X, and once the version updates on PYPI, this is likely to stop working. You can of course set a specific version number in the fooof requirement if you want new installs to keep working as normal. And/or the naming changes aren't too many, so you could update wonambi to use the new API (which should be set in and stable from now on), and then set the required version number as 1.0. Let me know if you want any help with updating, etc.

Unit Convertion

Hi Wonambi Team,
Does Wonambi convert units to something standard, or have functions for doing that? I didnt see any in the docs..
For example, i have files with mixed units (some in uV and some in mV) and im wondering if they get standardized automatically, or that's something I should do?
Also, are the detectors build to work on uV, mV or V?

Possibility to run analysis on several datasets in GUI?

I'm having a colleague with no coding experience that would like to run some spindle analysis. Wonambi seems perfect for this!

However, it seems like each participantt would need to be loaded&analysed individually, is that correct?

Issue appeared after upgrading from 3.6 to 5.18

I have this issue when I upgraded. I'm trying to read a BCI2000 file but the following error occurs:

File "C:/Users/PycharmProjects/my_file.py", line 9, in
bci_object = Dataset( bci_file_name)
File "c:\users\anaconda3\lib\site-packages\wonambi\dataset.py", line 192, in init
output = self.dataset.return_hdr()
File "c:\users\anaconda3\lib\site-packages\wonambi\ioeeg\bci2000.py", line 69, in return_hdr
s_freq = int(orig['Parameter']['SamplingRate'])
ValueError: invalid literal for int() with base 10: '2000Hz

Please note that this was working fine on the 3.6 version, but I faced an issue when reading the data. I thought upgrading would help, but now I got a more serious issue

BUG: return_videos does not take into account gap between videos

return_videos gives only the start time and end time of the first and last video, respectively. But it doesn't take into account if there is a gap between videos.

Spindle/SO detectors for non-artifacted

Hi Wonambi,
There are a few detectors that require artifact free NREM sleep. Does this mean the other methods should be able to work with NREM with artifacts?

Also, when they require NREM sleep, does this mean I should slice out the REM/Wake and concatenate NREM segments together? Or can I just ignore the spindles detected in REM/Wake segments after the fact?
I would say the former is safer, especially if a method is thresholding spindles based on some global property of the signal (e.g. X must be > 3*Std Dev of signal).

EDF New Channel - ValueError: could not broadcast input array from shape (400) into shape (500)

When loading an EDF sleep file, the dataset seems to load correctly. However, when I click Apply after creating a new Channel, I get the following error:

(base) C:\Users\Matthew\Documents\Sleep>wonambi
16:13:32 WONAMBI v5.62
16:13:41 Reading dataset: C:/Users/Matthew/Documents/Sleep/06000656-A5BS04864[EXPORT].edf
Traceback (most recent call last):
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\widgets\channels.py", line 434, in apply
self.parent.overview.update_position()
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\widgets\overview.py", line 239, in update_position
self.parent.traces.read_data()
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\widgets\traces.py", line 344, in read_data
endtime=window_end)
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\dataset.py", line 367, in read_data
dat = dataset.return_dat(idx_chan, one_begsam, one_endsam)
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\ioeeg\edf.py", line 201, in return_dat
dat_in_rec = self._read_record(f, blk, chan)
File "c:\users\matthew\anaconda3\lib\site-packages\wonambi\ioeeg\edf.py", line 237, in _read_record
dat_in_rec[i_ch_in_dat, :] = repeat(x, ratio)
ValueError: could not broadcast input array from shape (400) into shape (500)

Process finished with exit code -1073741819 (0xC0000005)

Hi Wonambi Team,
When running:

    d = Dataset('example1_sleep_rec.edf')
    data = d.read_data(chan=['C3-A2'])
    power = timefrequency(data, method='spectrogram')

I get:
Process finished with exit code -1073741819 (0xC0000005)

example1_sleep_rec.zip

ChanTimeFreq time axis

Hi Wonambi Team,
I'm using time-frequency to extract a spectrogram which i will use to calculate band power.
The ChanTimeFreq data returned from timefrequency has an axis attribute. I see that for frequency this is something like [0, 1, 2, ...] this makes me think these are the edges of the freq bins, and not the centers, is that right? So the first freq sample is 0-1Hz, the next 1-2Hz, etc. If so, then is the last value (say X) everything above that X, or X + freq_bin_size (1 Hz in this case).
Further, for time, the bins are like [4, 8, 12, 16, etc] which seem like edges (but the upper edge, not the lower edge as for freq). Does this mean the first time sample is from 0-4s, the next from 8-12s, or are these centers, where the first bin is 2-6s, then 6-10s, etc, and the first 2 seconds is lost (due to scipy's spectrogram function).
If you could clear up this ambiguity, that would be amazing :)

Citation for WONAMBI

I want to cite WONAMBI in our paper. What would be the appropriate citation, does a publication exist?

Accept StringIO for Annotation-Files

Heyho, I'm currently working my way through #26 to apply different spindle detection methods on our dataset. Our data is in EDF+ and simple csv files for sleep scoring.

I want to avoid having to create everything in XML files and was thinking about supplying files on-the-fly and passing them as StringIO/BytesIO or lists/np.arrays. Is there any possibly to supply the Annotations and all the other information as lists or StringIO?

When not using the GUI its a bit difficult to understand how to call the functions and what the functions expect. E.g. it took me some time to find out I can simply call the Detection class (i.e. that the class itself is a method and implements a __call__), and that there is no method defined that is called detection.run(data) .

I think this package is really awesome and has great potential, some more tutorials on non-GUI-use and it would be perfect!