diff --git a/paper/.gitignore b/paper/.gitignore new file mode 100644 index 00000000..668b1fbe --- /dev/null +++ b/paper/.gitignore @@ -0,0 +1,3 @@ +jats +*.ora +*.pdf diff --git a/paper/front_example.png b/paper/front_example.png new file mode 100644 index 00000000..ba521754 Binary files /dev/null and b/paper/front_example.png differ diff --git a/paper/paper.bib b/paper/paper.bib new file mode 100644 index 00000000..43dc361e --- /dev/null +++ b/paper/paper.bib @@ -0,0 +1,92 @@ +@book{matlab, + author = {Higham, Desmond J. and Higham, Nicholas J.}, + title = {{MATLAB} {Guide}}, + edition = {3rd}, + publisher = {SIAM}, + address = {Philadelphia, PA}, + year = {2016}, + doi = {10.1137/1.9781611974678} +} + +@book{octave, + author = {Eaton, John W. and Bateman, David and Hauberg, S{\o}ren and Wehbring, Rik}, + title = {{GNU Octave} version 8.1.0: A {High-Level} Interactive Language for Numerical Computations}, + publisher = {Free Software Foundation}, + year = {2023}, + url = {https://docs.octave.org/v8.1.0/}, + note = {GNU Octave manual} +} + +@book{plotly, + author = {Sievert, C}, + title = {Interactive {Web-Based} Data Visualization with {R}, {Plotly}, and {Shiny}}, + publisher = {Chapman & Hall/CRC}, + year = {2020}, + doi = {10.1201/9780429447273}, +} + +@misc{rust, + title = {{Plotly.rs}: Plotly for {Rust}}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/plotly/plotly.rs} +} + +@misc{r, + title = {{Plotly.R}: An interactive graphing library for {R}}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/plotly/plotly.R} +} + +@misc{python, + title = {{Plotly.py}: The interactive graphing library for {Python}}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/plotly/plotly.py} +} + +@misc{dotnet, + title = {{Plotly.NET}: Interactive graphing library for .NET programming languages}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/plotly/Plotly.NET} +} + +@misc{export_fig, + author = {Altman, Yair}, + title = {{export_fig}: A MATLAB function for exporting figures in publication quality}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/altmany/export_fig} +} + +@misc{matlab2tikz, + title = {{matlab2tikz}: Convert MATLAB/{Octave} figures to TikZ/{Pgfplots}}, + publisher = {GitHub}, + journal = {GitHub repository}, + url = {https://github.com/matlab2tikz/matlab2tikz} +} + +@article{gramm, + author = {Morel, Pierre}, + title = {Gramm: Grammar of graphics plotting in {MATLAB}}, + journal = {Journal of Open Source Software}, + volume = {3}, + number = {23}, + pages = {568}, + year = {2018}, + doi = {10.21105/joss.00568} +} + +@article{MATTER2024111351, + title = {MRI characterization of pelvic floor ligaments in nulliparous women: Technique development and morphometry within the 3D pelvic inclination correction system (3D-PICS)}, + journal = {European Journal of Radiology}, + volume = {173}, + pages = {111351}, + year = {2024}, + issn = {0720-048X}, + doi = {10.1016/j.ejrad.2024.111351}, + url = {https://www.sciencedirect.com/science/article/pii/S0720048X24000676}, + author = {Lea Matter and Monika Hebeisen and Stephan Beintner-Skawran and Cäcilia S. Reiner and Cornelia Betschart}, +} \ No newline at end of file diff --git a/paper/paper.md b/paper/paper.md new file mode 100644 index 00000000..4d809dbc --- /dev/null +++ b/paper/paper.md @@ -0,0 +1,129 @@ +--- +title: 'plotly_matlab: interactive web-based graphing for GNU Octave and MATLAB' +tags: + - Plotly + - Octave + - MATLAB + - data visualization + - graphing +authors: + - name: Roberto Moura + orcid: 0009-0004-5413-3375 + affiliation: 1 + - name: Gilberto Galvis + orcid: 0000-0002-2574-4917 + affiliation: 2 + - name: Christopher Parmer + affiliation: 3 +affiliations: + - name: Independent Researcher, United Kingdom + index: 1 + - name: Independent Researcher, Slovenia + index: 2 + - name: Plotly Technologies, Canada + index: 3 +date: 1 September 2026 +bibliography: paper.bib +--- + +# Summary + +`plotly_matlab` is the official Plotly graphing library for MATLAB and GNU Octave. +It converts native figures, created with either engine, into interactive, +web-based charts that can be explored, exported, and embedded in web pages +with a single line of code. + +![Example plots generated by this library in Octave (top-left: quiver; top-right: ezsurf; bottom-left: surfc; bottom-right: scatter).](front_example.png) + +Interactive web-based plots play a central role in scientific research. Because +the charts are interactive, viewers can zoom and pan to inspect fine detail, and +rotate three-dimensional charts to change perspective. Hovering over data points +displays tooltips with numerical values. Because the charts are web-based, they +are easy to share between researchers on different operating systems, unlike +language-specific figure objects. + +First released in 2013, this library brings interactive web-based plots to Octave and MATLAB. + +# Statement of need + +Plotly [@plotly] is widely used by the scientific community to generate interactive web +plots (its canonical scholarly citation has been cited more than 1,000 times on OpenAlex[^1]). +While other languages were supported by Plotly, the Octave [@octave] and MATLAB [@matlab] +ecosystems, which are widely used in scientific research, both lacked a plotting library +that is interactive and web-based. This library bridges this gap by providing an easy +way to generate Plotly figures from a broad range of native plots supported by Octave and MATLAB. + +[^1]: Cited 1,061 times as of Aug 2026 (https://openalex.org/works/W2991157178) + +# State of the field + +Wrappers for Plotly also exist in R [@r], Python [@python], Rust [@rust], and .NET programming +languages [@dotnet]. For MATLAB and Octave, the existing alternatives cover +only part of the workflow: `export_fig` [@export_fig] is a widely used tool for +high-quality static export of figures but produces no interactive charts; +`matlab2tikz` [@matlab2tikz] targets LaTeX documents with generated TikZ code; +and the `gramm` package [@gramm] provides a grammar-of-graphics interface for +statistical visualization in MATLAB but renders to native figures rather than +web charts. Rather than extending an existing binding, this library implements +figure conversion directly from each engine's native graphics object model, +providing Octave and MATLAB users with a dedicated workflow for interactive +web-based graphing. + +# Software design + +The core of the library is the `plotlyfig` class, which walks the graphics +object tree of a figure (figure, axes, and children) and builds a Plotly +figure description (data and layout) through per-class dispatch: a central +`updateData` function routes each graphics object to a dedicated `updateX` +function (one per supported plot type), with shared geometry and color helpers +used across plot types. hggroup-based plot types are resolved through engine-aware +group classification: both engines wrap plot types in hggroups (groups of primitive +graphics objects such as lines, patches, and text), but the group structures differ, +so the wrapper identifies the plot type behind each group before dispatch. +Three-dimensional scenes are handled explicitly, including camera geometry and +axis aspect-ratio computation derived from each engine's native camera model. + +A central design commitment is cross-engine parity. MATLAB and GNU Octave +differ in their graphics object trees (e.g., Octave wraps plot types in +hggroups that MATLAB exposes differently) and property semantics (character +arrays versus string types, annotation properties absent in Octave). The library maintains +a single codebase that provides consistent behavior across both engines, with behavior +verified by a regression suite that runs on each. + +Testing is an essential part of the project. A test runner +(`runplotlytests`) executes structural regression tests of converted figure +descriptions in both engines, and a gallery of 81 plot types +(`makegallery`) generates native and converted outputs that can be compared by +rendering with Plotly.js in a browser. Continuous integration runs the Octave +test suite on every push (GitHub Actions). + +# Research impact statement + +`plotly_matlab` is used in published scientific research. For example, it was +used to produce visualizations in a biomechanical imaging study of pelvic +floor ligaments [@MATTER2024111351]. The library is distributed through the +official Plotly MATLAB page ([plotly.com/matlab](https://plotly.com/matlab)) and the MathWorks File +Exchange. The library is currently maintained and supported through the Plotly +community forum. Its public GitHub history documents tagged releases and +extensive issue triage. + +# AI usage disclosure + +Gemini 3.1 Pro was used exclusively as assistance in the writing of this +manuscript for structure and clarity. All AI suggestions were reviewed and +validated by the authors. The authors made all decisions and verified technical accuracy. + +# Acknowledgements + +The library was originally created by Chuck Bronson and has benefited from +contributions by many other contributors. R. Moura currently maintains the +library in his personal time and receives no funding for this work. +C. Parmer is a co-founder and the chief product officer (CPO) of Plotly +Technologies Inc.; the library's early +development was carried out by Plotly employees, and G. Galvis's 2021 +contributions were made under contract for Plotly. G. Galvis has no current +financial or contractual relationship with the company. The authors thank +Plotly Technologies Inc. for supporting the open-source development of the +Plotly ecosystem. + +# References