diff --git a/@gramm/stat_summary.m b/@gramm/stat_summary.m index 2880f75..5b1a7e0 100644 --- a/@gramm/stat_summary.m +++ b/@gramm/stat_summary.m @@ -21,6 +21,7 @@ % percentiles % - 'fitnormalci' % - 'fitpoissonci' +% - 'fitbinomialci' % - 'fit95percentile' % - @function : provide a the handle to a custom function that takes % y values (as an n_repetitions x n_data_points matrix) and returns diff --git a/examples.m b/examples.m index b9c916d..176b45b 100644 --- a/examples.m +++ b/examples.m @@ -1382,5 +1382,50 @@ g17.draw(); +%% Raw matlab code equivalent to the first figure (in paper.md) + +figure('Position',[100 100 800 400],'Color',[1 1 1]); + +% Define groups +cyl = [4 6 8]; % Manually +orig = unique(cars.Origin_Region); % Based on data + +% Loop over groups +for oi = 1:length(orig) % External loop on the axes + + % Axes creation + ax = subplot(1,length(orig),oi); + hold on + + for ci = 1:length(cyl) %Internal loop on the colors + + % Data selection + sel = strcmp(cars.Origin_Region,orig{oi}) & ... + cars.Cylinders==cyl(ci) & ... + ~isnan(cars.Model_Year) & ~isnan(cars.MPG); + + % Plotting of raw data + plot(cars.Model_Year(sel),cars.MPG(sel),'.', ... + 'MarkerSize',15); + + % Keep the same color for the statistics + ax.ColorOrderIndex = ax.ColorOrderIndex - 1; + + % Statistics (linear fit and plotting) + b = [ones(sum(sel),1) cars.Model_Year(sel)] \ ... + cars.MPG(sel); + x_fit = [min(cars.Model_Year(sel)) ... + max(cars.Model_Year(sel))]; + plot(x_fit, x_fit * b(2) + b(1),'LineWidth',1.5); + end + + % Axes legends + title(['Origin: ' orig{oi}]); + xlabel('Year'); + ylabel('Fuel Economy (MPG)'); +end +% Ugly color legend +l = legend('4','','6','','8','','Location','southeast'); +title(l,'#Cyl'); diff --git a/gramm cheat sheet.pdf b/gramm cheat sheet.pdf index b1708b1..2377691 100644 Binary files a/gramm cheat sheet.pdf and b/gramm cheat sheet.pdf differ diff --git a/paper/codemeta.json b/paper/codemeta.json new file mode 100644 index 0000000..2491f92 --- /dev/null +++ b/paper/codemeta.json @@ -0,0 +1,23 @@ +{ + "@context": "https://raw.githubusercontent.com/codemeta/codemeta/master/codemeta.jsonld", + "@type": "Code", + "author": [ + { + "@id": "https://orcid.org/0000-0003-0984-7016", + "@type": "Person", + "email": "pier.morel@gmail.com", + "name": "Pierre Morel", + "affiliation": "German Primate Center" + } + ], + "identifier": "https://doi.org/10.5281/zenodo.594625", + "codeRepository": "https://github.com/piermorel/gramm", + "datePublished": "2018-01-31", + "dateModified": "2018-01-31", + "dateCreated": "2018-01-31", + "description": "Gramm is a complete data visualization toolbox for Matlab. It provides an easy to use and high-level interface to produce publication-quality plots of complex data with varied statistical visualizations. Gramm is inspired by R's ggplot2 library.", + "keywords": "data visualization, grouped data, visual analytics, plotting, matlab, statistical graphics", + "license": "MIT", + "title": "gramm", + "version": "v2.23" +} \ No newline at end of file diff --git a/paper/figure.png b/paper/figure.png new file mode 100644 index 0000000..38fdebf Binary files /dev/null and b/paper/figure.png differ diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 0000000..88a9366 --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,149 @@ + @Book{Wickham:2009, + author = {Hadley Wickham}, + title = {ggplot2: Elegant Graphics for Data Analysis}, + publisher = {Springer-Verlag New York}, + year = {2009}, + isbn = {978-0-387-98140-6}, + url = {http://ggplot2.org}, + } + @book{Wilkinson:1999, + author = {Leland Wilkinson}, + title = {The Grammar of Graphics}, + year = {1999}, + isbn = {0-387-98774-6}, + publisher = {Springer-Verlag New York, Inc.}, + address = {New York, NY, USA}, + } + @misc{michael_waskom_2017_883859, + author = {Michael Waskom and + Olga Botvinnik and + Drew O'Kane and + Paul Hobson and + Saulius Lukauskas and + David C Gemperline and + Tom Augspurger and + Yaroslav Halchenko and + John B. Cole and + Jordi Warmenhoven and + Julian de Ruiter and + Cameron Pye and + Stephan Hoyer and + Jake Vanderplas and + Santi Villalba and + Gero Kunter and + Eric Quintero and + Pete Bachant and + Marcel Martin and + Kyle Meyer and + Alistair Miles and + Yoav Ram and + Tal Yarkoni and + Mike Lee Williams and + Constantine Evans and + Clark Fitzgerald and + Brian and + Chris Fonnesbeck and + Antony Lee and + Adel Qalieh}, + title = {mwaskom/seaborn: v0.8.1 (September 2017)}, + month = sep, + year = 2017, + doi = {10.5281/zenodo.883859}, + url = {https://doi.org/10.5281/zenodo.883859} + } + @article{JSSv040i01, + author = {Hadley Wickham}, + title = {The Split-Apply-Combine Strategy for Data Analysis}, + journal = {Journal of Statistical Software, Articles}, + volume = {40}, + number = {1}, + year = {2011}, + keywords = {}, + abstract = {Many data analysis problems involve the application of a split-apply-combine strategy, where you break up a big problem into manageable pieces, operate on each piece independently and then put all the pieces back together. This insight gives rise to a new R package that allows you to smoothly apply this strategy, without having to worry about the type of structure in which your data is stored. + + The paper includes two case studies showing how these insights make it easier to work with batting records for veteran baseball players and a large 3d array of spatio-temporal ozone measurements.}, + issn = {1548-7660}, + pages = {1--29}, + doi = {10.18637/jss.v040.i01}, + url = {https://www.jstatsoft.org/v040/i01} + } + @article{doi:10.1152/jn.00504.2017, + author = {Enrico Ferrea and Lalitta Suriya-Arunroj and Dirk Hoehl and Uwe Thomas and Alexander Gail}, + title = {Implantable computer-controlled adaptive multi-electrode positioning system (AMEP)}, + journal = {Journal of Neurophysiology}, + volume = {Advance online publication}, + year = {2017}, + doi = {10.1152/jn.00504.2017}, + note ={PMID: 29187552}, + + URL = { + https://doi.org/10.1152/jn.00504.2017 + + }, + eprint = { + https://doi.org/10.1152/jn.00504.2017 + + } + , + abstract = { Acute neuronal recordings performed with metal microelectrodes in non-human primates allow investigating the neural substrate of complex cognitive behaviors. Yet, the daily re-insertion and positioning of the electrodes prevents recording from many neurons simultaneously, limiting the suitability of these types of recordings for brain-computer-interface applications or for large-scale population statistical methods on a trial-by-trial basis. In contrast, chronically implanted multi-electrode arrays offer the opportunity to record from many neurons simultaneously, but immovable electrodes prevent optimization of the signal during and after implantation and cause the tissue response to progressively impair the transduced signal quality, thereby limiting the number of different neurons that can be recorded over the lifetime of the implant. Semi-chronically implanted matrices of electrodes, instead, allow individually movable electrodes in depth and achieve higher channel count compared to acute methods, hence partially overcome these limitations. Existing semi-chronic systems with higher channel count lack computerized control of electrode movements, leading to limited user-friendliness and uncertainty in depth-positioning. Here we demonstrate a chronically-implantable Adaptive Multi-Electrode Positioning (AMEP) system with detachable drive for computerized depth-adjustment of individual electrodes over several millimeters. This semi-chronic 16-channel system is designed to optimize the simultaneous yield of units in an extended period following implantation since the electrodes can be independently depth-adjusted with minimal effort and their signal quality continuously assessed. Importantly, the electrode array is designed to remain within a chronic recording chamber for a prolonged time, or can be used for acute recordings with high signal-to-noise ratio in the cerebral cortex of non-human primates. } + } + @article{doi:10.1152/jn.00614.2017, + author = {Michael Berger and Antonino Calapai and Valeska Stephan and Michael Niessing and Leonore Burchardt and Alexander Gail and Stefan Treue}, + title = {Standardized automated training of rhesus monkeys for neuroscience research in their housing environment}, + journal = {Journal of Neurophysiology}, + volume = {Advance online publication}, + year = {2017}, + doi = {10.1152/jn.00614.2017}, + note ={PMID: 29142094}, + + URL = { + https://doi.org/10.1152/jn.00614.2017 + + }, + eprint = { + https://doi.org/10.1152/jn.00614.2017 + + } + , + abstract = { Teaching non-human primates the complex cognitive behavioral tasks that are central to cognitive neuroscience research is an essential and challenging endeavor. It is crucial for the scientific success that the animals learn to interpret the often complex task rules, and reliably and enduringly act accordingly. To achieve consistent behavior and comparable learning histories across animals, it is desirable to standardize training protocols. Automatizing the training can significantly reduce the time invested by the person training the animal. And self-paced training schedules with individualized learning speeds based on automatic updating of task conditions could enhance the animals' motivation and welfare. We developed a training paradigm for across-task unsupervised training (AUT) of successively more complex cognitive tasks to be administered through a stand-alone housing-based system optimized for rhesus monkeys in neuroscience research settings (Calapai et al. 2016). The AUT revealed inter-individual differences in long-term learning progress between animals, helping to characterize learning personalities, and commonalities, helping to identify easier and more difficult learning steps in the training protocol. Our results demonstrate that (1) rhesus monkeys stay engaged with the AUT over months despite access to water and food outside the experimental sessions, but with lower numbers of interaction compared to conventional fluid-controlled training; (2) with unsupervised training across sessions and task levels, rhesus monkeys can learn tasks of sufficient complexity for state-of-the art cognitive neuroscience in their housing environment; (3) AUT learning progress is primarily determined by the number of interactions with the system rather than the mere exposure time. } + } + +@article{1741-2552-13-1-016002, + author={Pierre Morel and Enrico Ferrea and Bahareh Taghizadeh-Sarshouri and Josep Marcel Cardona Audí and Roman +Ruff and Klaus-Peter Hoffmann and Sören Lewis and Michael Russold and Hans Dietl and Lait Abu-Saleh and Dietmar +Schroeder and Wolfgang Krautschneider and Thomas Meiners and Alexander Gail}, + title={Long-term decoding of movement force and direction with a wireless myoelectric implant}, + journal={Journal of Neural Engineering}, + volume={13}, + number={1}, + pages={016002}, + url={http://stacks.iop.org/1741-2552/13/i=1/a=016002}, + doi = {10.1088/1741-2560/13/1/016002}, + year={2016}, + abstract={Objective. The ease of use and number of degrees of freedom of current myoelectric hand prostheses is limited by the information content and reliability of the surface electromyography (sEMG) signals used to control them. For example, cross-talk limits the capacity to pick up signals from small or deep muscles, such as the forearm muscles for distal arm amputations, or sites of targeted muscle reinnervation (TMR) for proximal amputations. Here we test if signals recorded from the fully implanted, induction-powered wireless Myoplant system allow long-term decoding of continuous as well as discrete movement parameters with better reliability than equivalent sEMG recordings. The Myoplant system uses a centralized implant to transmit broadband EMG activity from four distributed bipolar epimysial electrodes. Approach. Two Rhesus macaques received implants in their backs, while electrodes were placed in their upper arm. One of the monkeys was trained to do a cursor task via a haptic robot, allowing us to control the forces exerted by the animal during arm movements. The second animal was trained to perform a center-out reaching task on a touchscreen. We compared the implanted system with concurrent sEMG recordings by evaluating our ability to decode time-varying force in one animal and discrete reach directions in the other from multiple features extracted from the raw EMG signals. Main results. In both cases, data from the implant allowed a decoder trained with data from a single day to maintain an accurate decoding performance during the following months, which was not the case for concurrent surface EMG recordings conducted simultaneously over the same muscles. Significance. These results show that a fully implantable, centralized wireless EMG system is particularly suited for long-term stable decoding of dynamic movements in demanding applications such as advanced forelimb prosthetics in a wide range of configurations (distal amputations, TMR).} +} +@article{10.1371/journal.pbio.2001323, + author = {Pierre Morel and Philipp Ulbrich and Alexander Gail}, + journal = {PLOS Biology}, + publisher = {Public Library of Science}, + title = {What makes a reach movement effortful? Physical effort discounting supports common minimization principles in decision making and motor control}, + year = {2017}, + month = {06}, + volume = {15}, + url = {https://doi.org/10.1371/journal.pbio.2001323}, + pages = {1-23}, + abstract = {Author summary Economic choice in humans and animals can be understood as a weighing of benefits (e.g., reward) against costs (e.g., effort, delay, risk), leading to a preference for the behavioral option with highest expected utility. The costs of the action associated with a choice can thereby affect its utility: for equivalent benefits, an action that requires less physical effort will be preferred to a more effortful one. Here, we characterized how human subjects assess physical effort when choosing between arm movements. We show that the effort cost of a movement increases with its duration and with the square of the force it is performed against but not with the distance covered. Therefore, the subjective cost that determines decisions does not reflect the objective energetic cost of the actions—i.e., the corresponding metabolic expenditure. Instead, the subjective cost has commonalities with the cost that our central nervous system is believed to minimize for controlling the motor execution of actions. Our findings thus argue in favor of action selection and action control sharing common underlying optimization principles.}, + number = {6}, + doi = {10.1371/journal.pbio.2001323} +} +@article {HBM:HBM23932, +author = {Wan, Nick and Hancock, Allison S. and Moon, Todd K. and Gillam, Ronald B.}, +title = {A functional near-infrared spectroscopic investigation of speech production during reading}, +journal = {Human Brain Mapping}, +year = {2017}, +issn = {1097-0193}, +url = {http://dx.doi.org/10.1002/hbm.23932}, +doi = {10.1002/hbm.23932}, +volume = {Advance online publication}, +keywords = {fNIRS, functional connectivity, Granger causality, oral reading, silent reading}, +} \ No newline at end of file diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 0000000..aad3aba --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,53 @@ +--- +title: 'Gramm: grammar of graphics plotting in Matlab' +authors: +- affiliation: 1 + name: Pierre Morel + orcid: 0000-0003-0984-7016 +date: "31 January 2018" +bibliography: paper.bib +tags: +- data visualization +- grouped data +- visual analytics +- plotting +- matlab +- statistical graphics +affiliations: +- index: 1 + name: German Primate Center, Göttingen, Germany +--- + +# Summary + +Gramm is a data visualization toolbox for Matlab (The MathWorks Inc., Natick, USA) that allows to produce publication-quality plots from grouped data easily and flexibly. Matlab can be used for complex data analysis using a high-level interface: it supports mixed-type tabular data via tables, provides statistical functions that accept these tables as arguments, and allows users to adopt a split-apply-combine approach [@JSSv040i01] with ```rowfun()```. However, the standard plotting functionality in Matlab is mostly low-level, allowing to create axes in figure windows and draw geometric primitives (lines, points, patches) or simple statistical visualizations (histograms, boxplots) from numerical array data. Producing complex plots from grouped data thus requires iterating over the various groups in order to make successive statistical computations and low-level draw calls, all the while handling axis and color generation in order to visually separate data by groups. The corresponding code is often long, not easily reusable, and makes exploring alternative plot designs tedious (Example code Fig. 1A). + +Inspired by ggplot2 [@Wickham:2009], the R implementation of "grammar of graphics" principles [@Wilkinson:1999], gramm improves Matlab's plotting functionality, allowing to generate complex figures using high-level object-oriented code (Example code Figure 1B). +Gramm has been used in several publications in the field of neuroscience, from human psychophysics [@10.1371/journal.pbio.2001323], to electrophysiology [@1741-2552-13-1-016002; @doi:10.1152/jn.00504.2017], human functional imaging [@HBM:HBM23932] and animal training [@doi:10.1152/jn.00614.2017]. + +# Gramm use and features + +The generation of a figure with gramm includes the following steps, which typically take few lines of code (Example gramm code Fig. 1B). In a first line, the user creates an instance of a gramm object by providing the constructor with the variables necessary for the plot: x and y values as well as grouping variables. Each grouping variable can simply be associated with a given plot feature using named arguments: color hue and lightness, sub-axis rows and columns, marker and line type and size. In the example Fig 1B, the two grouping variables are associated with sub-axis columns and color hues. After this initialization, the user can add graphical layers to the figure by making calls to corresponding methods of the newly created object. ```geom_``` methods are used to add individual layers that represent the x/y data directly, such as points, lines, bars, rasters, etc. ```stat_``` methods are used to add statistical visualization layers, some of which reflecting built-in Matlab statistics functions, others extending Matlab's capabilities: histograms, linear or non-linear fits, density estimates, statistical summaries, spline smoothing, violin plots, ellipse fits, etc. Most geom_ and stat_ methods can take optional arguments for customization of the layer. At this stage, the user can also call optional ```set_``` methods in order to fine tune the figure design (colormaps, legends, ordering, titles, etc.). The actual plotting is made when the user finally calls the ```draw()``` method. + +Once the ```draw()``` call is issued and the figure plotted, some interactions with the gramm object and plot are still possible. The user can retrieve the results of the statistical computations from the gramm object as well as the handles of the graphic primitives making up the plot, which allows further customization of individual plot elements. Plots with different data or different groups can also be superimposed on the existing plot using the ```update()``` method. Coding in this case works the same as if a new gramm object was created. + +Multiple gramm plots can be combined in the same figure window simply by creating a 2D array of gramm objects and calling the ```draw``` method on the whole array. The plots are then placed in the figure window according to their indices in the array. + +![Comparison of default Matlab plotting and gramm plotting with corresponding code. A. Grouped data Matlab plot generated using minimal code. Note the absence of confidence interval representations, the placement and aspect of the color legend, the non-matching axes limits, as well as the improper fit of content to the figure window width (the black outline represents the figure window edges). B. Gramm plot and corresponding code. C. Gramm plot with alternative design resulting from swapping the arguments highlighted with red and blue boxes in panel B](figure.png) + +Detailed documentation on the use of gramm is available through the built-in Matlab help navigator with ```doc gramm```, but a quick overview of all methods and their arguments can be found in the "gramm cheat sheet.pdf" file. Typical examples that demonstrate the various ways of using gramm as well as some use tips can be found in "examples.m", the output of which is published as an html page in "html/examples.html". + +# Comparison with standard Matlab code + +The code necessary to generate the example plot of Fig. 1B with gramm is more than three times shorter than the minimal standard Matlab code that would generate a conceptually similar plot (Fig. 1A). Moreover, the standard Matlab plot is missing several features that are built in gramm and would require adding more complex code, such as proper common color legends, matching scales across axes, shaded areas for confidence bounds or advanced dynamic content fitting to figure window size. Last, this simple example makes apparent the flexibility of gramm: exchanging which group is represented by sub-plots and which group by colors in order to produce the plot in Fig. 1C only requires argument name changes (red and blue boxes Fig. 1B), while standard Matlab code requires for-loops to be swapped, axis creation code to be modified, and the legend code to be completely reworked (Fig. 1A lines 3, 4, 6, 14, 15, 16, 18 and 19). + +# Comparison with other packages + +To my knowledge, gramm is the only implementation of this kind and breadth for Matlab, but two implementations of grammar of graphics' principles are available for other popular scientific languages: ggplot2 [@Wickham:2009] for R, and Seaborn [@michael_waskom_2017_883859] for python. Beyond obvious interface differences due to the different languages, a few specificities are noteworthy. + +As a main conceptual difference between gramm and the two aforementioned implementations, gramm does not acccept data input within the layer creation methods. Thus, gramm provides a more rigid framework with the constructor and the ```update()``` method, as presented above. +Compared to ggplot2, gramm can better handle repeated time series. These are very common in scientific fields where Matlab is widely used, such as neuroscience. With repeated time series, R/ggplot2 requires a memory-expensive "long" table (```n_repetitions * n_samples``` rows) that contains not only x/y data but also the groups. On the other hand, gramm can handle 2D arrays or ragged-array (cell) input for the x/y data (```n_repetitions``` rows; ```n_samples``` columns), and use less memory demanding arrays with ```n_repetitions``` rows for the groups. When the data is provided in this optimized way to gramm, some ```geom_``` and ```stat_``` functions adjust their behavior in order to account for the data struture. Seaborn has a basic support for repeated trajectory-like data, with the function ```tsplot()```. + +In terms of layer and data type support, gramm does not support geographical map representations (ggplot2), surface representations (ggplot2, seaborn), or clustermap data (seaborn). However, gramm supports 3D plots with line and point layers, can produce dedicated plots for repeated stochastic event time series (like spike raster plots that are frequently used in neuroscience), and is able to fit and represent confidence ellipses/ellipsoids for 2D and 3D point cloud data. + +# References \ No newline at end of file