RELEASE NOTES.TXT

This is BCILAB version 1.1-beta.
The latest versions of the toolbox can be found at github.com/sccn/BCILAB, and recent releases are also mirrored at ftp://sccn.ucsd.edu/pub/bcilab.

=== Getting Started ===

* Make sure that you have extracted this folder to a place that is not in your EEGLAB folder (an optimized edition of EEGLAB is bundled with the release).

* Start MATLAB, and if you have things in your path, reset you path to default settings by clicking File / Set Path / Default, and then Save. 
  If you have misc toolboxes in your path, you run the risk of creating unexpected errors (due to name conflicts), 
  but you can add your directories back later once you know what outputs to expect. If you intend to add BCILAB to the path, do *not* include sub-directories.

* Enter in MATLAB's command line: cd('your/path/to/bcilab'); bcilab; (if you path contains no spaces, you may also type: cd your/path/to/bcilab; bcilab)
  On some platforms (especially Linux), code for some advanced features will be compiled on the fly. 
  If you are using a compiler that is not recognized by MATLAB, you will get a few warnings here that you can ignore unless 
  you intend to use that particular device or component. 

* If you are a method developer, the best way to get into the toolbox is to start with the tutorial scripts in the userscripts folder
  (tutorial_erd1, tutorial_erd2, tutorial_erp1, tutorial_batch). They illustrate how to set up and run (currently over 40) different computational 
  approaches and exercise a large fraction of the available components. Then, the next step is to explore the GUI, which can help setting up approaches
  and analyses quickly. There is a GUI walkthrough video at: http://www.youtube.com/watch?v=Sup2SaJyFQE Then, explore the method directories code/filters, 
  code/machine_learning, and code/paradigms, and remaining folders in code; for further clarification the accompanying video http://www.youtube.com/watch?v=W3xIOopji28 
  explains the main concepts and data structures in the toolbox.

  If you are interested in experimental sciences or in data analysis and have prior experience with brain-computer interfacing, it is best to start 
  with the GUI walkthrough video at http://www.youtube.com/watch?v=Sup2SaJyFQE and then to run the tutorial scripts in the userscripts folder. 
  The lecture http://www.youtube.com/watch?v=W3xIOopji28 contains further details on toolbox concepts. If you want to get started with online analysis right away 
  and your hardware is not listed in the data acquisition menu of BCILAB, also watch the video on the lab streaming layer at: http://www.youtube.com/watch?v=Y1at7yrcFW0
  To get an overview of the contained methods, browse the Help menu or read the code documentation in code/filters, code/machine_learning, and code/paradigms.

  If you are just starting out with brain-computer interfacing, take a look at the video lecture series accompanying BCILAB, which is at
  http://sccn.ucsd.edu/wiki/Introduction_To_Modern_Brain-Computer_Interface_Design -- you will want to at least watch the video for Demo 2, and any other
  videos coming before that. If you find the material overwhelming, take your time to digest it step by step and closely study the paper references and 
  researcher web pages that are discussed in the last module (Further Reading). If you have an interest in general biosignal analysis (not just brain signals),
  don't miss the video on Demo 1.

=== Finding Documentation ===

* There is a video lecture series with toolbox demo videos (particularly Demo 2) and theory lectures covering several of the methods at: 
  http://sccn.ucsd.edu/wiki/Introduction_To_Modern_Brain-Computer_Interface_Design

* Each component and function of the toolbox is documented individually, including the internal functions. This help is accessible through the Help menu, 
  adding up to 100-200 pages of text. This covers nearly all of the functionality and inner workings of the toolbox in a "bottom-up" fashion. 
  The key functions and components of BCILAB also each have a list of short scripting examples that may provide additional in-depth help (together >200). 

* If all else fails, the code of each function is documented fairly extensively and to a high standard. 
  Thus, if you run into errors, the first place to look besides the error message is the documentation around the place where it happened and the 
  documentation of the responsible functions. To understand the inner workings of the toolbox one would probably need to read about 20% of the 
  function-level documentation (and to fully understand all aspects of BCILAB there is currently no better way than glancing over 
  some of the code-level documentation).

* If you implement your own plugins (e.g. filters, machine learning methods, BCI paradigms, device I/O), 
  you basically have to look at how the other components of the respective type are written and take a look at the documentation for 
  the toolbox features that they are using (e.g., the arg system or declare_properties). Most of them serve as working examples of how
  to build own components for the toolbox. 

* There is a relatively up-to-date wiki for BCILAB, which tries to give a conceptual top-down overview of how some 
  pieces of the toolbox work together and digs down into how to write certain types of plugins (sccn.ucsd.edu/wiki/BCILAB). 
  Although it is perhaps the most readable document, this wiki currently covers only ~20% of the toolbox functionality (not even talking about particular methods). 
  Turning this into a complete documentation is currently not within our reach in terms of manpower.
  
* There are slides of recent talks on the toolbox (some on on earlier versions) including some theory in ftp://sccn.ucsd.edu/pub/bcilab/presentations. 
  It is best to start with the most recent one as the slides have evolved somewhat over time. An early workshop talk on BCI is available on video at: 
  http://thesciencenetwork.org/programs/12th-eeglab-workshop/eeg-classification-and-cross-validation-using-the-bcilab-toolbox-overview

* We are currently writing a subsystems manual, which is ca. 20% complete. You find it at ftp://sccn.ucsd.edu/pub/bcilab/manuals.

=== Supported Platforms ===

* BCILAB should run on Windows/Linux/Mac, 32/64bit, MATLAB 2008a-2012a (and possibly newer)

* There are also compiled executables included for Win64 and Linux64 included, others forthcoming, (in the sub-directory build/distrib) which only require the 
  redistributable MATLAB Compiler Runtime (see http://www.mathworks.com/products/compiler/mcr/index.html or ftp://sccn.ucsd.edu/pub/MCR for download links). 
  These are fully featured, but cannot be further extended through custom plugins (to do this you need a MATLAB license).

* This release adds a new plugin for general-purpose data acquisition from a variety of EEG (and other) devices by allowing to stream data from and to the lab
  streaming layer (LSL). LSL is a new signal transport, synchronization and collection system that is maintained independently of BCILAB at
  code.google.com/p/labstreaminglayer. Besides this, the toolbox continues to natively support BioSemi and BrainProducts hardware, as well as a few common 
  protocols (TCP, OSC, etc.).


=== Known Issues in Beta Version ===
- utl_kernelize has a bug that renders it non-working (affects ml_trainsvm and ml_trainrvm)
- flt_standardize with the sphere setting turned on is not robust to signals that are (almost) rank-deficient
- flt_iir flips the signal sign under some settings (though consistently) and causes rather high CPU load during 
  online processing


=== Credits ===

If you are using the toolbox for a publication, please consider citing any of the following references:
[1] Kothe CK and Makeig S, "BCILAB: A Platform for Brain-Computer Interface Development", Journal of Neural Engineering, 2013 (in press).
[2] Delorme A, Mullen T, Kothe C, Acar ZA, Bigdely-Shamlo N, Vankov A, Makeig S "EEGLAB, SIFT, NFT, BCILAB, and ERICA: New tools for advanced EEG/MEG processing",
    Computational Intelligence, 2011.
[3] Delorme A, Kothe C, Vankov A, Bigdely-Shamlo N, Oostenveld R, Zander T, and Makeig S, "MATLAB-Based Tools for BCI Research"
    in (B+H)CI: The Human in Brain-Computer Interfaces and the Brain in Human-Computer Interaction. Desney S. Tan and Anton Nijholt (eds.), 2009.

If you are making extensive use of the underlying EEGLAB tools, please consider citing:
[3] Delorme A and Makeig S. "EEGLAB: an open source toolbox for analysis of single-trial EEG dynamics" J Neurosci Methods, 134:9-21, 2004.



=== Changes since 1.1-beta tag (Marker Streaming branch) ===

Major New Features
- set_joinepos: new function to join epoched signals across epochs (orders of magnitude faster than set_merge, and handles corner cases)
- set_makepos: can now extract epochs relative to markers online/incrementally (complete rewrite)
- onl_***: generally markers can now be streamed through the online system and are visible to filters and the feature extraction

Minor New Features
- combine_structs/flatten_structs: new functions to handle structs in name-value pair lists
- set_selinterval: now supports index ranges as an option, also 10x faster on some data
- sparse_binning,cummax,arraydeal,chopdeal: new utility functions for efficient struct array and particularly event struct handling
  (with optional mex versions available)
- onl_append: now supports submission of markers accompanying the chunk
- onl_filtered: can now emit multi-epoch signals online, also can now emit signals including markers
- onl_predict: can now emit multiple outputs per prediction; also got new option EmptyResultValue to control the format of empty results
- onl_newpredictor: new argument PredictAt: allows to define markers relative to which predictions should be generated 
  (and epochs should be extracted)
- onl_peek: now supports markers
- onl_read_background: now supports callback functions that also return markers, plus better error handling 
- onl_write_background: new options PredictAt, Verbose, and EmptyResultValue, also better error handling
- onl_simulate: aside from specifying the latency of onl_predict calls, now allows to use the pipeline with marker-locked prediction
  (via TargetMarkers argument which takes the same role as PredictAt in some other functions)
- run_readlsl: now supports reading synchronized markers from marker streams
- run_readdataset: now supports reading markers
- run_write***: added PredictAt and Verbose options
- utl_buffer: new utility function for buffering of subsequent signal structs
- utl_fileinfo: now supports empty file paths
- utl_find_filter: now supports returning the subscript path to the matching location in the data structure (for use with subsasgn)
- utl_loadmodel: new utility function for loading BCI models
- utl_picktimes: minor optimization
- play_eegset_lsl: new function to play back a dataset through LSL

Minor Changes
- arg_define: now a bit faster in direct mode, slight simplifications
- declare_properties: quite a bit faster
- set_chanid: a bit faster
- set_insert_markers: more efficient for very large insertions
- set_picktimes: minimal optimization
- set_targetmarkers: can now be used online (more efficient), merged the various EventTypes/EventMap formats into a single argument
- exp_beginfun: faster during online processing
- flt_spectrum: more efficient
- hlp_scope/hlp_resolve: faster
- onl_newpipeline, onl_filtered, onl_newpredictor: simplified quite a bit
- utl_add_online, utl_complete_model: removed some now-obsolete model properties (prediction_window and subrequests)

Minor Fixes
- flt_resample: now resamples marker latencies more correctly (was off by 1 before)
- onl_append: fixed handling of optional timestamps
- ParadigmRSSD: now works also with ICA types other than AMICA
- utl_resolve_streams: fixed rare crash bug when multiple candidate streams needed to be disambiguated based on supported channels and types
- vis_filtered: minor documentation fix


=== Changes since 1.1-beta ===

Major New Features

Minor New Features
- set_insert_markers: now supports negative upper bounds in the absoluterange segment specification
- window_func: now supports some more alternative names for window functions and one or another func
- hlp_diskcache: now has a tad less overhead
- ParadigmMTCSP: now supports LogTransform option, also a bit more efficient
- flt_ica: now allows to retain channel labels when TransformData is set

Major Changes

Minor Changes
- partitioning of continuous data during a parameter search will now cache the data set rather than
  reload it every time

Serious Fixes

Minor Fixes
- flt_ica, robust_sphere option: was calling an obsolete function

=== Changes since 1.01 ===

Major New Features
- ml_trainproximal: new general-purpose classifier (allows for free-form combinations of 
  regularization terms in a regression or classification setting)
- hlp_diskcache: new function to cache results on disk through a simple interface
- consensus_admm: new function to calculate Alternating Direction Method of Multipliers solution 
  (for n terms)
- flt_repair_bursts: new algorithm to remove bursty artifacts (ASR)
- flt_repair_channels: much-improved approach to repairing bad channels online

Minor New Features
- arg_define: added proper handling of cases where variables cannot be written into a function’s 
  workspace (e.g., for nested functions)
- arg_define: added a crucial warning for cases where arguments are passed in by name but 
  using one or more wrong parameter names
- arg_guidialog: now handles multi-select popup menus even when there’s only one option
- arg_guipanel: added the option to generate a new figure and return the entered input (similarly 
  to arg_guidialog)
- hlp_funcversion: new function that returns a version identifier string (or hash if none present) of 
  a given function
- arg_setdirect: new function to recursively override the ‘arg_direct’ flag in a data structure
- set_fit_dipoles: can now discard non-localizable components
- set_targetmakers: now allows to prune non-target markers from the set
- set_targetmarkers: now supports {‘actualvalues’} as value to EventMap, in which case the 
  marker strings are converted to numeric values implicitly
- set_targetmarkers: now supports wildcard expressions (with * or ?) in the marker types
- set_targetmarkers: now allows to get marker strings from a different field (than .type)
- exp_eval: now optionally more friendly to dbstop if error (if appropriate tracking field set)
- utl_funcversion: new function to get a version identifier of a function
- new argument specifier to mark an argument as deprecated (optional ‘deprecated’ flag, 
  arg_deprecated function, and support in declare_properties); these are never shown in the GUI
  and generate deprecation notes when used
- new argument specifier to mark an argument as experimental (optional ‘experimental’ flag, and 
  and support in declare_properties); these items are hidden in the GUI by default (can be 
  overridden at startup or in bcilab_config.m)
- new argument specifier to mark an argument as guru-level (optional ‘guru’ flag); these items 
  can be toggled in the GUI (default display setting available at startup or in bcilab_config.m)
- flt_clean_channels: now allows to protect channels from removal
- flt_clean_channels: added linenoise-aware processing
- design_fir: new function to design FIR filter using the frequency-sampling method (with cubic 
  interpolation)
- warn_once, disp_once: now return whether the message got displayed
- geometric_median: new function to calculate the Geometric Median
- fit_eeg_distribution: new function to robustly estimate EEG mean/std. deviation
- filter_fast: now does not require fftfilt() any more (included an octave piece)
- cov_shrink: now faster in the unweighted case
- cov_blockgeom: new function to calculate blockwise geometric-median covariance matrix
  (robust estimator)
- block_geometric_median: new function to calculate blockwise geometric median
- gui_applymodel: support for standardized mean-squared error (Dan Roberts)
- gui_batchanalysis: now also picks up correctly-formatted cell array approaches from the 
  workspace
- gui_calibratemodel: now allows to choose the event field to extract target markers from
- io_loadset: supports loading of sub-sampled data and automatic casting to double
- ml_calcloss: now supports standardized mean-squared error and sign error (Dan Roberts)
- ml_trainlogreg: now supports continuous target values (parameter ContinuousTargets’)
- ml_trainlogreg: supports custom loss measures for internal parameter search
- ml_train***: results can now be cached on disk for all (slow) classifiers (in hlp_diskcache  
  cache domain named ‘predictivemodels’)
- ml_train: now officially supports arbitrary tensor-shaped features (did so before, but 
  undocumented)
- vis_filtered: can now display non-standard data fields of the stream
- vis_csd: function to show online current source density (requires MoBIlab in path) (Tim Mullen)
- utl_memoize_commit: now makes smarter decisions about when to cache (accounts for the 
  expected time to read data from disk)
- utl_crossval: now returns average statistics across folds for all measures
- utl_nearest: new function (Dan Roberts)
- utl_crossval: now supports passing in the index sets to run over directly
- ml_calcloss: AUC loss does not require the statistics toolbox any more
- utl_calc_crossspec: new function to calculate cross-spectrum related tensors from a data 
  set
- par_worker: shows a tad more diagnostics
- par_getworkers_ssh: new parameter to customize the MATLAB binary location
- par_getworkers_ssh: new parameter to prefix the standard startup command by extra 
  commands
- par_getworkers_ssh: added some robustness to certain linux commands not being available
- run_readdataset: can now convert received data to double; also allows to override the buffer 
  size (for speed)
- bci_train/bci_predict: new parameter EventField (where to search for target markers) 
  (Dan Roberts)
- bci_train: new option to prune non-target markers (for speed)
- bic_batchtrain: slighty better diagnostics, and offers features for poor man’s parallel computing
  (using the new Ordering parameters)
- utl_timeseries_fields: new function to look up time-series fields from an EEGLAB data set 
  struct; several filters now filter by default all fields returned by this
- onl_filtered/onl_predict: can now buffer a variety of fields, not just .data
- flt_analytic_phasor: new function to calculate the instantaneous amplitude, phase and 
  frequency in a given frequency band
- window_func: new function to calculate most common window functions
- flt_window: now supports most windows without need for the signal processing toolbox
- flt_selchans: now supports data order preserving channel selection, and selective removal of 
  channels
- flt_rescale: new filter to rescale the data by a factor (Tim Mullen)
- flt_sigmoid: new filter to perform a sigmoidal transform of the data (Tim Mullen)
- flt_rectify: new filter to rectify the given data (Tim Mullen)
- bci_predict: better handling of missing target field in the data & errors from the loss measures
- flt_project: now supports more expressive/flexible syntax to refer to data set fields or 
   workspace variables
- flt_fir/flt_fir: can now process the data in chunks to save memory
- flt_fir: now also supports the window method and frequency sampling design rules; the latter 
  requires no sigproc toolbox
- flt_fir: renormalizing the amplitude is now optional
- flt_fir: minimum-phase filter design produces now less noisy filters than before
- flt_iir: now supports free-form designs via the Yule-Walker method
- flt_pipeline: now more tolerant when trying to load erroneous plugin functions
- flt_ica: now supports rica, sphering and robust sphering as methods
- plugins are now also searched in the respective sub-directory “in_developmentâ€?, and marked 
  experimental by default
- ParadigmFBCSP: now supports robust covariance estimation
- ParadigmDataflowSimplified: now supports a “feature conditioningâ€? stage between feature 
  extraction and machine learning
- ParadigmDALERP: now supports application to other data fields than .data, and allows for 
  optional shrinkage-based covariance estimation
- flt_clean_windows: now uses dramatically improved statistics with very high breakdown point    
  by default; also processes windows in finer overlap by default, allowing to capture more 
  short-time artifacts
- CrossSpecMatc (in chronux): added a very fast path
- pop_epoch, pop_select, eeg_eegrej (in EEGLAB): added support for srcpot field
- cvglmnetMulticlass.m (in glmnet): added support for caching and custom loss functions in 
  parameter search
- hkl_kfold.m (in HKL): added support for caching
- updated liblsl-Matlab: added support for transferring byte strings (int8 typed)
- topoplot_grid: added some more options
- added new method (rica.m) to dependencies
- flt_clean_settings: major overhaul (added new techniques and fixed some other ones)
  (but should maintain parameter backwards compatibility)
- arg_define: better error message when mixing up arguments
- hlp_tostring: now supports a cutoff on output length for elements
- flt_ica: added experimental new method Beamica
- utl_register_field: new function to register custom fields with data structures
- flt_standardize: can now also do multivariate sphering (whitening)
- tutorial_erp1.m: added a few new approaches to demo new features
- added UnLocBox toolbox to dependencies (primarily for some of its prox operators)
- added the ability to read private plugins from ~/.bcilab/code
- added robust re-referencing
- flt_standarize now uses regularization for sphering
- vis_artifacts: can now also display event markers
- eeg_checkset: optimized chanlocs processing 
- par_getworkers_ssh: added sanity checks, made shell command editable, added ability to auto-generate MATLAB command (default)
  and added ability to bring up its own GUI
- env_startup now creates a few more directories in ~/.bcilab (including code/scripts and logs/workers)
- env_acquire_cluster/env_release_cluster (and "Request Cluster Availability" button) now by default override BCILAB's
  current global setting of whether to run on the cluster and which worker pool to use, making routine cluster acquisition 
  with the click of a button more convenient (given that the cluster acquire options are set up correctly in the config file 
  or settings GUI)
- flt_selchans: can now select the closest channels to the selected ones, if the desired channels are not in the data set
- flt_iir: now does not need the Sigproc toolbox for online processing and runs with less overhead (removed dfilt dependency)
- bci_batchtrain: now returns error messages produced during a cluster run, and allows more flexible wildcard syntax when
  listing data sets to process (using rdir() rather than dir()), such as /data/mystudy/**/*.set
- hlp_serialize: now serializes gpuArray data (as double arrays)

Major Changes
- arg_tovals: now by default sets the arg_direct flag to false rather than true, meaning that some 
  existing functions taking outputs generated via arg_tovals will likely run the slow path unless the 
  flag is set to true explicitly (e.g., via arg_setdirect)
- set_chanid is now case insensitive at channel matching (note that this should only break
  processing of pathological data sets which have multiple channels with the same name but 
  different case, and otherwise improve things)
- some methods are now marked as “experimentalâ€? and not shown in the GUI by default (can be 
  toggled at startup or in the bcilab_config.m)

Minor Changes
- utl_fileinfo: now returns the version identifier string for the given file if one is present as the first 
  argument instead of the code hash (otherwise returns the hash as before); the 5th output 
  always contains the code hash
- set_fit_dipoles now stores dipole fits in a different format in the temp directory (now using 
  hlp_diskcache)
- channels with numerical labels are now assumed to be of type ‘EEG’ (instead of ‘unknown’)
- set_fit_dipoles: SCCN cap labeling schemes were updated to assume a priori that the most 
  recent (2012) cap scheme was used
- env_startup: default disk space to use for cache is now 80GB instead 10% of free space
- flt_clean_channels: minor changes to default settings
- flt_clean_flatlines: now uses a different criterion (based on duration of near-absolute flatlines);    
  the old functionality has been deprecated
- the helpers, misc, arg and parallel functions are now included under the BSD license
- io_loadset: the ‘nofixups’ parameter has been deprecated
- vis_hist: superseded by vis_artifacts
- ult_resolve_streams: matching of channel names and types is now case insensitive
- utl_add_online: some error messages are now lazy, so come up only when used erroneously 
  online
- flt_ica: normalizing the weights is now optional and disabled by default
- flt_fir: now uses the frequency sampling method by default
- set_makepos: improved how this function performs its online behavior (checks via onl_isonline)
- onl_predict: streamlined/simplified implementation; now calls onl_filtered to perform the signal 
  processing part
- onl_filtered: streamlined/simplified implementation; now calls onl_peek to read from raw 
  stream, also improved the documentation
- onl_peak: generalized a little bit (to support the needs of onl_filtered)
- io_loadset, set_new: now by default append a .tracking.timeseries field
- onl_newstream: reduced default online buffer length from 30 to 10 seconds, for faster processing
- some speedups in the online pipeline (simplified a few things)
- flt_ica: if TransformData is checked, by default the .icaweights field is cleared afterwards (can be disabled by 
  setting the ClearAfterTransform flag to false)
- ParadigmSpectralmeans: now uses a FIR filter by default instead of IIR
- arg_guidialog: now by default hides arguments marked "guru" (can be toggled with the ShowGuru option)
- flt_fir: normalize_response now off by default
- bci_batchtrain: was previously running locally by default; now the default matches the current global setting
- fit_eeg_distribution: now by default fits an ensemble of truncated distributions and returns a quantile thereof 
- flt_clean_windows: updated defaults in accordance with fit_eeg_distribution 
- ParadigmDALERP: now uses a FIR filter by default instead of IIR

Serious Fixes
- ml_calcloss: fixed calculation of FP and FN (Dan Roberts)
- utl_crossval: calculated mean AUC loss incorrectly, usually pessimistically
  (per-fold AUC’s were correct)

Minor Fixes
- arg_subswitch: fixed an error message
- arg_subtoggle: now properly supports ‘off’ / ‘on’ strings in the defaults
- env_showmenu: now highlights the menu when it’s already open
- env_beginfun: now uses a better way to measure the evaluation time of the function
- hlp_superimposedata: now supports all-empty inputs
- hlp_struct2varargin: now support empty inputs
- hlp_deserialize: fixed support for cell arrays of empty (0x0) struct arrays (crashed before)
- hlp_deserialize: now warns if a scoped/nested function could not be deserialized
- hlp_fingerprint: now respects the workspace of anonymous functions
- hlp_microcache: now warns if an improper lambda-equality value setting was passed in
- hlp_cryptohash: now does not overrun MATLAB’s Java heap when hashing large data 
- set_merge, set_combine and set_gettarget now accept empty inputs
- ml_calcloss: fixed typo in negative log-likelihood loss (crashed before)
- utl_resolve_streams: fixed a case where channel labels don’t match but the stream has the 
  right number of channels (didn’t work before)
- utl_memoize_commit: now gracefully handles the case where free drive space cannot be queried
- flt_resample: fixed Lanczos window (was off by one point)
- ParadigmSpectralmeans: fixed an off-by-one error in frequency indexing (Dan Roberts)
- flt_eog: fixed bug which disabled regression when removing EOG channels
- utl_check_dataset: fixed a warning message
- onl_append: changed the order of stream field updates to work with new MATLAB versions 
- flt_movavg: fixed buffering bug when data had 0 samples
- ParadigmFBCSP: used missing function when robust flag was set (cov_robust, now cov_blockgeom)
- ParadigmSIFT: feature extraction now works for online processing