<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Giuliano Maciocci on Medium]]></title>
        <description><![CDATA[Stories by Giuliano Maciocci on Medium]]></description>
        <link>https://medium.com/@gmaciocci?source=rss-2d1c22d26fc3------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ChCXjPnsfKIw9WrONgv3eQ.jpeg</url>
            <title>Stories by Giuliano Maciocci on Medium</title>
            <link>https://medium.com/@gmaciocci?source=rss-2d1c22d26fc3------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 11:40:42 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gmaciocci/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Meditation for Skeptics]]></title>
            <link>https://gmaciocci.medium.com/meditation-for-skeptics-6f83be7608cd?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/6f83be7608cd</guid>
            <category><![CDATA[wellness]]></category>
            <category><![CDATA[mindfulness]]></category>
            <category><![CDATA[self-improvement]]></category>
            <category><![CDATA[meditation]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Thu, 27 Feb 2025 18:21:28 GMT</pubDate>
            <atom:updated>2025-02-27T18:21:28.612Z</atom:updated>
            <content:encoded><![CDATA[<p>You don’t have to be a spiritual type to gain more control over your mind</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4zjt0it62KomhK2__QaLtw.png" /></figure><p>I don’t have a spiritual cell in my whole body. Never have. My whole adult life has been spent in the realm of science and technology, driven by a curious but deeply scientific outlook on Life, the Universe, and Everything.</p><p>I am not religious. I don’t believe in the supernatural. And I’ve always been borderline allergic to anything even remotely associated with New Age spirituality.</p><p>For the longest time, I’d associated the practice of meditation with the kind of spiritual practices I’d always been turned off by; something a bit “woo-woo,” which might work for other people who believe in it, but wouldn’t work for me.</p><p>Some of that was because of its marketing: Look up any meditation app, course, or retreat and you’ll see the same dominant branding everywhere: smiling people in white robes in peaceful surroundings, pictures of galaxies and colorful mandalas, lotus flowers.</p><p>It just wasn’t in tune with MY brand. It was off-putting.</p><p>It also didn’t help that I’d been lied to, having somehow absorbed, by some kind of media osmosis fed by movies and TV, that in order to be successful at meditating one needed to <strong><em>“clear one’s mind,” </em></strong>which anyone will tell you is borderline impossible.</p><p>The brain is a noisy place — especially these days. With the fast pace of modern lifestyles and the minefield of devices constantly screaming for our attention, just the concept of clearing one’s mind seems like an impossible barrier to entry. My few attempts at meditation, driven by sheer curiosity, immediately failed to achieve any kind of inner silence, thus giving me even more reason not to go any further. The barrier to entry was too high already. The door to meditation remained firmly shut.</p><p>But then, the key fell into my lap from an unexpected source. A song.</p><blockquote>“The easiest way to get into the meditative state is to begin by listening”.</blockquote><p>A good friend of mine, much more spiritual than myself, shared his Spotify playlist of favorite 2024 songs with our social group. Among his curated collection of tracks, one in particular stood out as very different from the others.</p><p>The track <a href="https://open.spotify.com/track/2DbzxHuEBPNNPNJ297kPj2?si=aefe9ec4d08a42be">Listen</a> by Boreta, featuring Alan Watts — a British and American writer, speaker, and self-styled philosophical entertainer — is something of a guided meditation set to music. Alan Watts himself has been heavily sampled in a number of EDM and Drum n Bass tracks, and I immediately recognized the track’s opening words from other tracks in my own music collection: <em>“The easiest way to get into the meditative state is to begin by listening”. </em>I’d heard that sample a hundred times, but never the full context.</p><p>In its full version, the track goes on to explain how to slip into meditation, acting as an effective primer on what to do, what to look for, and how to do it.</p><p>And it <strong><em>clicked</em></strong> for me. It suddenly made sense. And, most importantly, it <strong><em>worked</em></strong>.</p><p>I tried to follow its instructions, and before long I was doing ten minute sessions every day, sometimes multiple times a day. Those session soon became twenty, then thirty minutes, and I’m now regularly spending 30–60mins a day deep in the most relaxed state that I’ve ever been able to achieve. My mood is better, my emotional stability and resilience to stress greatly improved, and I am such a convert I’ve decided to write about something for the first time in years.</p><h3>A primer on meditation</h3><p>The key to meditation is to manage your attention. You’ll be using sound, touch, and breathing to give you things to focus on, with the goal of actively maintaining focus for as long as possible. Trust me, it’s a lot more fun than it sounds.</p><p>Get yourself into a quiet place, adopt a comfortable upright position (Cross-legged is definitely optional), and close your eyes.</p><p><strong>1. Listen without judgement</strong></p><p>Start by listening to the sounds around you, no matter what they are. Your house creaking, that motorcycle riding by, the distant chirping of a bird, or the hum of traffic on the nearby highway. <strong>There is no bad sound</strong>. There is no annoying sound. To you, all sounds are equal. Just listen with your full attention at the music of the world around you.</p><p><strong>2. Feel your body</strong></p><p>Once you’ve tuned into the sounds around you, Feel how the sounds hit your eardrums, and how it makes you feel. Shift your attention to your body. Got an itch? Don’t scratch it; <strong><em>observe</em></strong> it, really feel it. Got an ache? Maybe a little twinge from sitting up too long? Feel it to its fullest, almost like you’re trying to analyze it.</p><p><strong>3. Breathe</strong></p><p>Feel your breathing. Try and feel the air coming into your nostrils. I bet you’ve never really tried to feel how the air interacts with the edges of your nostrils as it goes in — if you concentrate, you might feel them getting ever so slightly cool as you breathe in. Feel your chest — or better yet, belly- expand with every breath.</p><p><strong>4. Don’t try to clear your thoughts; <em>Observe</em> them</strong></p><blockquote>When you’re actively trying to listen, to observe, to feel, it’s actually hard to think. That’s the key to that elusive “clearing of the mind.”</blockquote><p>As you shift your attention and focus between listening, feeling and breathing, you will get intrusive thoughts: that thing you need to buy, that conversation you had with your boss, the almost-instantaneous classification of that sound you just heard (<em>“it’s my neighbor’s bike, god, why does it have to be so noisy…”</em>). Don’t fight it: acknowledge the thought, and return your attention to listening, feeling, or breathing.</p><p>Sometimes those thoughts are persistent, usually meaning your brain has some unfinished business that doesn’t care about your meditation session. In those cases it can be helpful to <strong>label the thought</strong>: I imagine drawing a line around the thought, writing a label on it, and watching it float away. So if my brain is bugging me about that thing I need to buy, I label it “<em>shopping</em>” and imagine it floating away. Labelled thoughts, in my experience, seldom returns. And if they do just repeat the process.</p><p>When you’re actively trying to listen, to observe, to feel, it’s actually hard to think. That’s the key to that elusive “clearing of the mind.” You’re not fruitlessly trying not to think — you’re giving your mind something else to do.</p><p><strong>5. Start small</strong></p><p>Start with short sessions, 10mins or so. Set a timer, and go. As you practice, you’ll find the time you spend actively in focus — listening, feeling, or concentrating on your breathing — gets longer, and the time spent packaging your intrusive thoughts into little labelled bubbles will lessen.</p><p>Before you know it, you’ll be spending most of your sessions in deep focus, increasingly relaxed after every session, your thoughts slowed down and infrequent, leading to a deep relaxation that will make you want to stay in your sessions longer and longer. You’ll be ignoring that timer at the end of the session to bask in that feeling for just a little longer.</p><h3>It’s not woo-woo, it’s science</h3><p>There is a <a href="https://pubmed.ncbi.nlm.nih.gov/?term=meditation">wealth of peer-reviewed research</a> connecting meditation to mental health benefits. Yet, while the mindfulness industry has had some success in de-coupling meditative practices from their aura (pun intended) of spirituality, meditation’s brand still struggles to make inroads with people like myself, die-hard rationalists with an atavistic aversion to most things ethereal.</p><p>Which is a real shame.</p><p>So I hope this serves as an introduction for some, helping to overcome a misplaced prejudice to try out a practice that, with just a few minutes a day, has the very real potential to improve your life.</p><p>Like it did for me.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6f83be7608cd" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How a note taking app changed my productivity game]]></title>
            <link>https://gmaciocci.medium.com/how-a-note-taking-app-changed-my-productivity-game-d1168c10a2aa?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/d1168c10a2aa</guid>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[obsidian]]></category>
            <category><![CDATA[notes]]></category>
            <category><![CDATA[notetaking]]></category>
            <category><![CDATA[workflow]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Mon, 24 Jan 2022 18:25:34 GMT</pubDate>
            <atom:updated>2022-02-17T11:24:41.810Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8DjRoS33DLXIeEK_RzcJjQ.png" /></figure><p>A few months ago, I was scrolling through my recommended feed on YouTube when I came across <a href="https://www.youtube.com/watch?v=TDhTpPIjsDg">this video</a> talking about <a href="https://obsidian.md/">Obsidian</a>, a free note taking app that advertises itself as “A second brain, for you, forever.”</p><p>Intrigued, I started down a deep, deep rabbit hole of community plugins, content-linking methodologies and philosophies, note taking tips, and mental model systems.</p><p>Before I knew it, I was a convert. Now, I am practically an evangelist, the guy who can’t shut up about this cool tool that he has somehow managed to inject into almost every aspect of his life and work.</p><p>Over a remarkably short time, Obsidian went from a good way to liberate my personal notes from the proprietary Apple prison in which they had been accumulating for years, to a tool which now encompasses my entire professional workflow.</p><p>Lots of meetings? Record every salient point in Obsidian. Need a tasks list that updates itself? Obsidian has you covered. Reminders? Researching a new topic? Yup, Obsidian. Project planning? Obsidian. Drafting a strategy document? Obsidian. Drink a new beer you want to remember? You get the idea.</p><p>So how can a note taking app supposedly take over almost every major recurring task and workflow in life and work? Well for starters because calling Obsidian a note taking app is like calling Elon Musk “That guy with the flame thrower.” Obsidian is, thanks to its ability to effortlessly cross-link notes and retrieve information in seconds, more of a knowledge mapping tool than a notepad — Hence the “brain” reference in its marketing. It even has a literal knowledge graph built in, where you can see how your notes cluster around topics and relate to each other.</p><p>Obsidian’s way of linking and mapping disparate notes to each other, coupled with the flexibility of its powerful tagging system, means it’s easy to develop interesting ways of organising one’s information, and in my case it meant that, during the first week at a new job, I could record any bit from any conversation I thought I might want to recall later without stressing about a neat folder system, or other organisational principle: I could focus one hundred percent of my attention on the note taking, and know complete confidence that I’d be able to retrieve and recall any bits of knowledge across any note later no matter where or how I had noted them down.</p><p>Aside from its core premise as a versatile note taking and knowledge mapping system, and its Markdown-based storage format which ensure your notes will likely outlive the application itself, what makes Obsidian insanely useful is the sheer magnitude of its community, and the plugins they produce and maintain to address anything from simple checklists to Kanban boards, and everything in between.</p><p>So while I’m not going to go into detail on how to use Obsidian — many have done a <a href="https://www.youtube.com/watch?v=7GqQKCT0PZ4">better job than I ever could</a>, and <a href="https://www.youtube.com/watch?v=QgbLb6QCK88">tutorials </a>on the subject can be found with a simple search — I wanted to highlight some of the more useful and interesting plugins I use, and how I use them, to perhaps get you started down the path to Obsidian-ising all the things. All of the plugins I mention here are available by simply tapping the “Browse” button under the Community Plugins entry in the application’s Settings screen.</p><p>So without further ado:</p><h3>Check lists</h3><p>Imagine you’re taking notes during an important meeting and have to note down an action you don’t want to forget. Normally you would have to switch to your preferred ToDo app, whereas in Obsidian, with the essential Checklist community plugin installed, you can just jot down a checklist item right in the note you are in, tag it with a hashtag you have set up, and know that that task will be automatically picked up and placed in a single neat, dynamically updated list in the right hand pane of the application.</p><p>I have set up checklist hash tags for #todo, #asap, #read, #watch, and even #improve to help me remember everything from a simple follow-up to an important functional improvement I need to think about for an upcoming product release. The fact that these check list items are in-line to whatever note you’re editing at any time, but also available in a central list that is always up to date, means I never forget anything these days.</p><h3>Reminders</h3><p>Another excellent plugins, Reminder builds on the functionality of check lists and adds a snoozeable pop-up reminder that comes up for whatever time and date you have added to that checklist item simply by typing something like “ <em>(</em><a href="http://twitter.com/2022"><em>@2022</em></a><em>–01–25 16:00)”. </em>The list of reminders is also available as an optional pane in the Obsidian sidebar, complete with dates and times.</p><h3>Project management in Kanban</h3><p>If you work in Agile, or have ever used something like Trello, you’ll be familiar with the cards-in-columns task management style that is a Kanban board. The Kanban plugin does exactly that, it lets you create Kanban boards that link to individual notes, with optional due dates and full drag-and-drop support. Extremely useful for lightweight project tracking.</p><p>I have a personal Kanban note pinned to the top of my starred notes, which are permanently displayed in my left hand sidebar. The board acts as a personal ToDo list for longer term stuff I need to deal with, in addition to the dynamically updated Checklist (see above) of all my outstanding tasks. Between the two, I never miss a thing.</p><h3>Encryption</h3><p>As I mentioned, I store a lot of my personal and professional life in my Obsidian vault. That sometimes means sensitive stuff like backup codes, one-time keys, account details and much more. The Meld Encrypt plugin protects these notes with AES256 encryption, and because the passwords are not stored anywhere (unless you set a buffer time, and then it’s only locally and temporarily), you don’t have to worry about hacked accounts or whatever. And because the encrypted notes are stored in plaintext on your local storage, like everything else in Obsidian, you will be able to decrypt them with any tool that uses AES encryption even fifty years from now and if Obsidian ceases to exist. Secure and future proof (Unless quantum decryption becomes a thing, in which case we have bigger problems).</p><h3>Exporting documents</h3><p>The Pandoc plugin lets me export my notes in a multitude of formats, including the ubiquitous PDF and .DOCX. Meaning Obsidian is now the place where I draft most of my work product, as I can easily annotate all my research within Obsidian and leverage those notes in the document draft. I then zap the exported file into Google Drive, apply some basic formatting, and I’m ready to share my work.</p><h3>Drawing and sketching</h3><p>This is more of an honourable mention, as Excalidraw is a plugin I only occasionally use, but is essential when I do. Simply put, Excalidraw lets you draw and embed sketches, simple flowcharts and diagrams in your notes vault, for when you need to note down or communicate something visually. A nice little bit of functionality to round out Obsidian’s text-heavy core experience.</p><p>I hope this will inspire someone to take a peek into the world of Obsidian, and find as much use out of it as I have. And if you’re an Obsidian expert with some tips to share, please don’t hesitate to let me know!</p><p><strong>UPDATE:</strong> I neglected to mention the invaluable <a href="https://apps.apple.com/de/app/exporter/id1099120373">Exporter </a>app, which lets people who have all their notes stuck in the Apple iCloud ecosystem export all their notes as individual Markdown files, which can then simply be plopped into a folder in your Obsidian vault.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d1168c10a2aa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Welcome to a new ERA of reproducible publishing]]></title>
            <link>https://gmaciocci.medium.com/welcome-to-a-new-era-of-reproducible-publishing-17325658c6e?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/17325658c6e</guid>
            <category><![CDATA[rstudio]]></category>
            <category><![CDATA[reproducibility]]></category>
            <category><![CDATA[publishing]]></category>
            <category><![CDATA[jupyter-notebook]]></category>
            <category><![CDATA[science]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Mon, 24 Aug 2020 00:00:00 GMT</pubDate>
            <atom:updated>2021-09-07T13:27:29.996Z</atom:updated>
            <content:encoded><![CDATA[<p><em>This article was originally published on eLife Labs on Aug 24, 2020, and is republished here for archival and preservation reasons.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1003/0*Znu-7w5Zq1jj0Ln2.jpg" /></figure><p>New open-source technology lets eLife authors publish Executable Research Articles that treat live code and data as first-class citizens.</p><p><strong>By Emmy Tsang and Giuliano Maciocci</strong></p><p>Since 2017, we have been working on the concept of computationally reproducible papers. The open-source suite of tools that started life as the <a href="https://elifesciences.org/labs/b521cf4d/reproducible-document-stack-towards-a-scalable-solution-for-reproducible-articles">Reproducible Document Stack</a> is now live on eLife as ERA, the <strong>Executable Research Article</strong>, delivering a truly web-native format for taking published research to a new level of transparency, reproducibility and interactivity.</p><p>From today, authors with a published eLife paper can register their interest to enrich their published work with the addition of live code blocks, programmatically-generated interactive figures, and dynamically generated in-line values, using familiar tools like R Markdown and Jupyter in combination with Stencila Hub’s intuitive asset management and format conversion interface. The resulting new ERA publication will be presented as a complement to the original published paper. Very soon, a Google Docs plugin will also be made available to let authors insert executable code and data blocks into their documents using the cloud service.</p><p>Readers of ERA publications will be able to inspect the code, modify it, and re-execute it directly in the browser, enabling them to better understand how a figure is generated. They will be able to change a plot from one format to another, alter the data range of a specific analysis, and much more. All changes are limited to an individual’s browsing session and do not affect the published article, so anyone can experiment safely. Readers can also download the ERA publication — with all embedded code and data preserved — and use it as a basis for further study or derivative works.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*DJ170HAMZNP-7aQN.jpg" /><figcaption><strong>Figures in ERAs can be accompanied by editable code blocks, where the code can be edited and re-executed to immediately see the effects of those edits.</strong></figcaption></figure><p>Started by eLife in partnership with <a href="https://substance.io/">Substance</a>, and later developed by <a href="https://stenci.la/">Stencila</a>, ERA takes many of the important lessons learned from pioneering technologies like Jupyter and R Markdown, and folds them into a new open-source research publication format that treats code and data as first-class citizens alongside the traditional text and figures. The ERA technology stack is also designed specifically towards preprint and journal publishing, with strong XML standards, native <a href="https://schema.org/">schema.org</a> compliance, and a versatile theming solution that makes it adaptable to the visual style of virtually any online publication.</p><h4><strong>Getting started with ERA</strong></h4><p>Explore some of the functionalities that ERA offers with two published examples:</p><ul><li><a href="https://elifesciences.org/articles/30274/executable">This ERA complement</a> of Lewis et al., 2018 (original article) showcases executable figures, tables and in-line numbers.</li><li><a href="https://elifesciences.org/articles/52258/executable">This ERA complement</a> of “Inter- and intra-animal variation in the integrative properties of stellate cells in the medial entorhinal cortex” by Pastoll et al. (original article) demonstrates a variety of executable plots.</li></ul><p>Start by clicking the Run Document button at the top of the article. This will start a compute session. Be patient, as it may take a moment. When you see the “ <em>Ready to run document</em> “ message, you’re good to go.</p><p>Then, look for the blue “eye” icons throughout the paper, which indicate code blocks. Clicking on those icons will reveal the underlying code, which can then be edited in place.</p><p>After making an edit, press the white “play” icon at the top of the code block to execute your new code and see its effects. Please note that it may take some time for the code to execute, depending on its complexity and on server load.</p><h4>Publish an ERA with eLife</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*7hFVENF_XKPHf4za.jpg" /><figcaption>Workflow for eLife authors to compose and publish an ERA complement.</figcaption></figure><p>eLife authors can register their interest to enrich their published works on eLife by using the button below. At this initial stage of release, our aim is to work closely with the first few chosen ERA authors to further test and improve the ERA tools and workflow- your input will be crucial to helping us create a more seamless experience for more authors in the future.</p><h4>Find out more about ERA</h4><ul><li>If you are an eLife author and are interested in publishing an ERA complement to your published article, please <a href="https://crm.elifesciences.org/crm/ERA-InterestForm">get in touch</a>.</li><li>We hosted a webinar and demo on September 8- please <a href="https://elifesciences.org/inside-elife/d417b916">view the recording.</a></li><li>Please <a href="https://crm.elifesciences.org/crm/RDS-updates">sign up</a> for our approximately bi-monthly ERA community update.</li></ul><p><strong>Questions?</strong> Please check the Frequently Asked Questions section below, or email us at innovation [at] elifesciences [dot] org.</p><h4>Frequently Asked Questions</h4><p><strong>Q: Can I share the changes I’ve made to the code?</strong></p><p>A: No — at the moment the changes are not saved and will disappear once you close/refresh your browser. You can however download the ERA (containing the Markdown/notebook file with the associated code and data files), edit the files locally and share the results.</p><p><strong>Q: I’d like to use the code that’s in this paper to analyse my own data — what’s the best way to do it?</strong></p><p>A: You can download the ERA (see above) and replace the data file with your own (although you may need to change some of the variables/parameters). Please remember to cite the original paper if you do publish those results!</p><p><strong>Q: Can I comment on the code?</strong></p><p>A: Not at the moment, unfortunately — Hypothesis is yet to be made available on ERA articles.</p><p><strong>Q: Can I download a particular code chunk/figure, or the underlying data file?</strong></p><p>A: At the moment, you cannot download a particular code chunk/executable figure. You can download the entire ERA (which contains the underlying code, CSV data and HTML).</p><p><strong>Q: What tools do I need to create an Executable Research Article?</strong></p><p>A: The <a href="https://hub.stenci.la/">Stencila Hub</a> interface allows for format conversion between various common tools such as RStudio, Jupyter, Google Docs, and even Word and PDF. Thanks to some embedding wizardry you can even convert to Word and PDF to share work with your colleagues for comment, and convert those back to R Markdown without losing any of your code and data!</p><p><strong>Q: What kind of programming languages can ERA handle?</strong></p><p>A: ERA can currently handle R Markdown and Python. Dependency compatibility for non-standard packages may vary, but if you’re experiencing issues or need new packages added for your article, you can <a href="https://stenci.la/">contact Stencila</a> to request this.</p><p><strong>Q: How do I compose an executable companion to my paper?</strong></p><p>A: Did you:</p><ol><li>publish with eLife,</li><li>have figures that are generated using R/Python in that paper,</li><li>have the raw data file for those figures?</li></ol><p>If yes for all three, please <a href="https://crm.elifesciences.org/crm/ERA-InterestForm">express your interest</a>.</p><p><strong>Q: My figures are generated using SPSS, MATLAB or programming languages other than Python or R, can I make my paper executable?</strong></p><p>A: Not at the moment — as we add compatibility for other languages, we will keep the community informed via our <a href="https://elifesci.org/ERAupdates">ERA community update</a>.</p><p><strong>Q: What if I’m already using Jupyter Notebook/R Markdown for data analysis/writing my articles?</strong></p><p>A: That will make composing your ERA a lot easier — Using Stencila Hub, you can take a copy of your paper published on the eLife website and convert it to a Jupyter Notebook/R Markdown file. You can then download it and add the appropriate code chunks. <a href="http://help.stenci.la/en/articles/4184684-enriching-an-elife-article">Please read the tutorial</a> for more information.</p><p><strong>Q: What size/type of data can I upload to Stencila?</strong></p><p>A: Theoretically there is no limit on size or type — but for this phase of development we ask you to please stick to tabular data (e.g. csv, tsv).</p><p><strong>Q: Can I cite the executable complement?</strong></p><p>A: You cannot at the moment — please cite the standard eLife article.</p><p><strong>Q: Is my code/data going to be reviewed?</strong></p><p>A: There will be some minimal checks to make sure that the code is not generating errors, but other than that, the code will be presented as-is. We are working with other code and data reviewing initiatives to improve this in the near future.</p><p><strong>Q: Will this increase the amount of time it takes for my paper to be reviewed?</strong></p><p>A: No, your paper would need to have been published already for you to be eligible for an ERA complement.</p><p><strong>Q: How long will it take for me to compose an ERA?</strong></p><p>A: It depends on the complexity of your code and paper — it could take anything between a few hours to 2–3 weeks.</p><p><strong>Q: Does that mean people can do whatever they want with my paper?</strong></p><p>A: Yes and no. Yes, because people can explore your data and change your code in their browsers; no, because none of these changes will be saved, nor will they affect anyone else’s views on your data and code.</p><p><strong>Q: What happens when a package that my analysis is dependent on is updated/not maintained and my code doesn’t work anymore?</strong></p><p>A: This should not affect the code that’s published, Stencila Hub will make sure that the correct (legacy) version of the package is installed when it is started.</p><p><strong>Q: Do I have to convert all of my figures into executable versions? What if some (parts) of my figures cannot be made executable, e.g. images/diagrams?</strong></p><p>A: You do not have to convert all of your figures into executable versions. When a single figure contains multiple panels/images, and some but not all of these could be made executable, it would be acceptable to re-capture these as separate Figures or figure supplements, as appropriate, so that those panels/images can be made executable.</p><p><strong>Q: Can I only enrich figures? What about inline numbers/tables?</strong></p><p>A: Inline numbers and tables can also be enriched with code.</p><p><strong>Q: Can I style the executable version of my figures differently from those already published?</strong></p><p>A: Please style your figures as closely as possible to the ones in your published eLife article — this will help speed up our quality control processes for the ERA. See above for figures which are only partially executable.</p><p><strong>Q: Can I enrich figure supplements?</strong></p><p>A: Yes</p><p><strong>Q: How can I attach data — can I link to data published on other repositories, e.g. Zenodo, Figshare, etc?</strong></p><p>A: Yes — you can upload tabular data and also add URLs of data sources to your Stencila Hub project.</p><p><strong>Q: Can I preview my ERA before it’s published?</strong></p><p>A: Yes, you can preview what your ERA will look like on Stencila Hub, before it is shared with the eLife Production Team.</p><h4>Developers and publishers</h4><p><strong>Q: Is this an eLife-exclusive feature?</strong></p><p>A: Quite the opposite. eLife and Stencila developed ERA as open-source software specifically to encourage other publishers to offer the format to their authors. Interested publishers should contact us at innovation [at] elifesciences [dot] org.</p><p><strong>Q: Why not just use Jupyter or a commercial solution?</strong></p><p>The ERA technology stack is designed specifically to be faster at loading, displaying and executing articles than Jupyter Notebooks, and to provide a reading experience that’s closer to that of a traditional online publication. ERA’s theming and format conversion capabilities also let publishers more easily integrate ERA content within their journal websites. Finally, unlike commercial solutions in this space, ERA’s open-source nature means there is no lock-in to a singler vendor — publishers can even run their own instance of the tool stack should they choose to, although they may want to choose an implementation hosted by Stencila as a more cost-effective option.</p><p><strong>Q: How do I contribute to the development of this project?</strong></p><p>A: You can <a href="https://crm.elifesciences.org/crm/tech-news?utm_source=Labs-ERAlaunch&amp;utm_medium=website&amp;utm_campaign=technews">sign up to our technology and innovation nesletter</a> to receive ERA community update for the latest news and opportunities to contribute, and/or <a href="https://github.com/stencila">explore Stencila’s repositories on GitHub</a>. If you see opportunities to collaborate, please don’t hesitate to email innovation [at] elifesciences [dot] org</p><p><strong>Q: Who is paying for the hosting/compute?</strong></p><p>A: eLife is paying at the moment — we hope to use this initial phase to assess the costs associated with these executable articles. Individual publishers wishing to adopt the technology will be able to negotiate their own hosted execution pricing directly with Stencila, or run their own instance of the technology stack on their own compute infrastructure.</p><p><em>Originally published at </em><a href="https://elifesciences.org/labs/dc5acbde/welcome-to-a-new-era-of-reproducible-publishing"><em>https://elifesciences.org</em></a><em> on August 24, 2020.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=17325658c6e" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Reproducible Document Stack: Towards a scalable solution for reproducible articles]]></title>
            <link>https://gmaciocci.medium.com/reproducible-document-stack-towards-a-scalable-solution-for-reproducible-articles-310c623d9a65?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/310c623d9a65</guid>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[science]]></category>
            <category><![CDATA[rstudio]]></category>
            <category><![CDATA[jupyter-notebook]]></category>
            <category><![CDATA[reproducibility]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Wed, 22 May 2019 00:00:00 GMT</pubDate>
            <atom:updated>2021-09-07T13:49:37.730Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Thisa article was originally published on eLife Labs on May 22, 2019, and is being reproduced here for archival and preservation purposes.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*av4rFLeyu--DJnB-.jpg" /></figure><p><strong>By Giuliano Maciocci, Emmy Tsang, Nokome Bentley and Michael Aufreiter</strong></p><p>In February, eLife introduced its <a href="https://elifesci.org/reproducible-example">first computationally reproducible document</a>, based on a research article originally published in the Reproducibility Project: Cancer Biology by Tim Errington, the Director of Research at the Center for Open Science. The interactive article is a demonstration of some of the capabilities of the initial prototype of the <a href="https://elifesciences.org/labs/7dbeb390/reproducible-document-stack-supporting-the-next-generation-research-article">Reproducible Document Stack (RDS)</a>, an open-source tool stack for authoring and publishing reproducible articles developed by <a href="http://substance.io/">Substance</a> and building on technology from <a href="http://stenci.la/">Stencila</a> and <a href="https://mybinder.org/">Binder</a>. The demo also showcased eLife’s vision for the future of research articles.</p><p>The research community’s response to the article was overwhelmingly encouraging: thousands of researchers explored the paper’s in-line code block re-execution abilities by manipulating its plots, and several authors approached us directly to ask how they might publish a reproducible version of their own manuscripts.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*-CnJtuBPEGc39EXK.jpg" /><figcaption>Changing the plot on the right from a bar plot to a dot plot by in-browser R-code re-execution.</figcaption></figure><p>Encouraged by the community interest and feedback, we have now started working on achieving a scalable implementation and service infrastructure to support the publication of reproducible articles. The goal of this next phase in the RDS project is to ship researcher-centred open-source solutions that will allow for the hosting and publication of reproducible documents, at scale, by anyone. This includes building conversion, rendering and authoring tools, and the backend infrastructure needed to execute reproducible articles in the browser.</p><p>Interoperability, modularity and openness are at the heart of the RDS’s design and development. We want authors, readers and publishers from different research communities to be able to use and interact with these tools seamlessly. RDS will continue to be developed open-source, and we strive to update and engage the community at all stages of development. Our first priority will be enabling interoperability with existing authoring tools for the Jupyter and R Markdown communities.</p><blockquote><em>Interoperability, modularity and openness are at the heart of the RDS’s design and development.</em></blockquote><p>As a first step, eLife aims to publish reproducible articles as companions of already accepted papers. We will endeavour to accept submissions of reproducible manuscripts in the form of <a href="https://github.com/substance/dar">DAR files</a> by the end of 2019.</p><p>We outline the key areas of innovation of this next phase of RDS development below.</p><h4>Format converters for reproducible documents</h4><p>Despite the fact that most research articles are still written in Word, an increasing number of scientists are moving to more reproducible formats such as Jupyter Notebooks and R Markdown. The new DAR format for reproducible documents finally offers a way to take this reproducibility through to publication; but without publisher support or any easy way to convert between formats, researchers fall back to converting their work to Word or PDFs before submitting to publishers, thereby losing reproducibility.</p><p>Interoperability is key when working with scientists across disciplines. We want it to be easy for a scientist to create a reproducible document from multiple starting points. Format converters will allow researchers using Jupyter Notebooks and R Markdown to submit reproducible articles to eLife and have them converted to the DAR format, without losing the reproducible elements.</p><blockquote><em>We want it to be easy for a scientist to create a reproducible document from multiple starting points.</em></blockquote><h4>Reproducible execution services and supporting tools development</h4><p>To publish reproducible documents, publishers and researchers need reliable and performant reproducible execution environments as the backend for running live-code elements. <a href="https://github.com/stencila/hub">Stencila Hub</a> is being built to provide such environments, and for the next phase of RDS development, additional functionality for the Hub will be specifically designed by Stencila for the publisher use case. The aim is to build a robust and scalable software and personnel infrastructure for the provision of execution services in support of the RDS, as well as to enhance the overall user experience. Stencila will provide the reproducible execution services to eLife, and subsequently to any publishers interested in making RDS publications available to their customers, through a Service Level Agreement.</p><p>We greatly value existing technology and the ongoing efforts of the open-source community, but at the same time, it is important that we encourage innovation and support the exploration of new approaches and solutions. We aim to maximise our reuse of existing open-source software, such as Jupyter kernels, Kubernetes, Jupyter Hub and Binder, to deliver execution services robustly and cost-effectively. Stencila’s short-term plan is to deploy its own BinderHub instance for the hosting of eLife’s reproducible articles; if alternative implementations are warranted, we will conduct thorough research and comparisons on user experience and performance, and deliver any alternative implementations as complements to existing technologies.</p><p>We also believe that there is still considerable room for innovation in the arena of efficient and scalable reproducible computation, and that a joint effort between the eLife and Stencila communities will facilitate the exploration of more robust publishing infrastructures. For example, Docker images, which are currently used to build reproducible research environments, can be very large. Stencila will therefore explore solutions to optimise the size of Docker images to the bare minimum required by a reproducible document, with the end goal of producing well-documented, tested and modular tools that will enable more reproducible and efficient execution environments. We hope to contribute these open tools and ideas towards other publishing and reproducibility pipelines beyond eLife and the RDS project.</p><h4>File format specification for portable reproducible documents</h4><p><a href="https://elifesciences.org/labs/8de87c33/texture-an-open-science-manuscript-editor">Texture</a> is an open-source editing software designed and developed by Substance specifically to edit and annotate scientific content. It uses the <a href="https://github.com/substance/dar">DAR</a> format, which is based on a stricter form of JATS-XML. To improve the portability of reproducible documents, Substance will extend the DAR file format specification to natively support R Markdown’s inline code cells, giving the DAR file format greater interoperability with mainstream tools for computational reproducibility.</p><h4>A Stencila plugin for Texture</h4><p>Substance will also work on improving the Texture authoring client by extending it with a new extension architecture that will allow plugins, such as one encompassing Stencila’s code-authoring functionality, to be added into the Texture client. This will ensure Texture can be maintained as primarily an XML editor, for use in the authoring and production of traditional manuscripts, but also extended as needed via separately maintained plugins to encompass new functionality such as Reproducible Document authoring and execution. A reference Stencila plugin will also be created as the first to use the new plugin architecture.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*8Rdm6toLaWVsaWQd.jpg" /><figcaption><strong>In 2017, </strong><a href="https://elifesciences.org/inside-elife/e832444e/innovation-understanding-the-demand-for-reproducible-research-articles"><strong>researchers familiar with reproducible document tools</strong></a><strong> told us they were interested in being able to share and read research articles with features that support better code and data sharing as well as greater interactivity and executability.</strong></figcaption></figure><h3>Authoring and publishing a reproducible article: the future workflow</h3><p>Once the technical work on the next phase of the RDS project is complete, we envision the following workflow for authoring and publishing reproducible articles:</p><ol><li><strong>Authoring. </strong>The author will follow provided guidelines for how to write reproducible articles as R Markdown, Jupyter Notebook or DAR documents. These guidelines will include how to add the necessary metadata to each of these formats.</li><li><strong>Uploading. </strong>The author uploads their article, and necessary data and code files, to a “project” on Stencila Hub. Eventually this step may be folded into a publisher’s submission workflow.</li><li><strong>Building.</strong> A compact and efficient reproducible execution environment is built for the article based on the software packages used in it. These tools also create a manifest of the software dependencies of the article, thereby providing data for software citations.</li><li><strong>Verification. </strong>The article is executed headlessly on the Stencila Hub within the reproducible execution environment to verify that it is indeed reproducible.</li><li><strong>Conversion. </strong>Once the article has been verified as being reproducible, the author presses a “Create DAR” button (when not already using the format) to export their article to DAR ready for eLife’s production team. Any issues with conversion would be reported to the user so that they could make corrections to their original document.</li><li><strong>Publication. </strong>A reproducible companion version of the article can be made available to readers via two mechanisms:</li><li>The article is converted to HTML and served from the Stencila Hub. It is progressively enhanced using Javascript to make the reproducible elements live by connecting to the execution environment built for the article (also hosted on the Hub).</li><li>The DAR is rendered by Javascript within the browser using a Texture Reader interface that is hosted by eLife and which connects to the execution environment built for the article and hosted on the Hub (this is the setup used in the demo).</li></ol><h3>Get involved</h3><p>Since the release of eLife’s first reproducible article, we have been actively collecting feedback from both the research and the open-source community, and this has been crucial to shaping the development of the RDS.</p><p>We strive to continue this for the next phase of the project, which is expected to last for about a year. We hope to post frequent updates on the milestones here on <a href="http://elifesciences.org/labs">eLife Labs</a>, and we welcome your input and feedback throughout, whether about the concept or specific technical elements. Please annotate publicly on this and future blog posts.</p><p>If you’d like to know more about the RDS project, or are a researcher or developer wishing to contribute to the project, here are some key resources to get you started:</p><ul><li>Stencila Desktop <a href="https://stenci.la/use/install.html">installation instructions</a> and <a href="https://github.com/stencila/desktop">code repository</a>.</li><li><a href="https://github.com/substance/texture">Texture repository</a>, the open-source manuscript editor that Stencila Desktop is based on.</li><li>See the <a href="https://stenci.la/learn/integrations/converters.html">guide on the Stencila Converters</a> and the <a href="https://github.com/stencila/convert">relevant repository</a>.</li><li>Join <a href="https://gitter.im/stencila/stencila">Stencila’s chat channel</a> and <a href="https://community.stenci.la/">Community Forum</a>.</li><li>Sign up for the <a href="https://crm.elifesciences.org/crm/RDS-updates">RDS community newsletter</a>.</li><li>Join <a href="https://zoom.us/webinar/register/WN_mnVgZtNEQXezMtDtSz6VaA">Stencila’s upcoming community call</a> on June 3 (1pm PST), and eLife’s open-source community call on June 24.</li></ul><p>We will discuss the RDS project and reproducibility in general at various conferences over the next two months:</p><ul><li><a href="https://cascadiarconf.com/">Cascadia R Conf</a> — June 8, Bellevue, US (Stencila).</li><li><a href="https://escience.washington.edu/events/writing-reproducible-executable-scientific-papers-with-r-python-a-hands-on-workshop/">Writing reproducible &amp; executable scientific papers with R &amp; Python: a hands-on workshop</a> — June 10–11, Seattle, US (Stencila).</li><li>“Hack and Yack” session at the British Library — June 17, London, UK (eLife).</li><li><a href="https://indico.cern.ch/event/786048/timetable/#20190619.detailed">OAI11 UNIGE-CERN Workshop on Innovations in Scholarly Communications</a> — June 19–21, Geneva, Switzerland (eLife).</li><li><a href="https://www.software.ac.uk/ccmcr19">CarpentryConnect 2019</a> — June 25–27, Manchester, UK (eLife).</li><li><a href="https://www.iscb.org/ismbeccb2019">ISCB/ECCB/BOSC 2019</a> — July 21–25, Basel, Switzerland (eLife).</li></ul><p>If you have specific questions or comments, you can also email us at innovation [at] elifesciences [dot] org, or interact with us on Twitter <a href="http://twitter.com/eLifeInnovation">@eLifeInnovation</a>.</p><p><em>Originally published at </em><a href="https://elifesciences.org/labs/b521cf4d/reproducible-document-stack-towards-a-scalable-solution-for-reproducible-articles"><em>https://elifesciences.org</em></a><em> on May 22, 2019.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=310c623d9a65" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Introducing eLife’s first computationally reproducible article]]></title>
            <link>https://gmaciocci.medium.com/introducing-elifes-first-computationally-reproducible-article-5e9040ef630c?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/5e9040ef630c</guid>
            <category><![CDATA[reproducibility]]></category>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[science]]></category>
            <category><![CDATA[jupyter-notebook]]></category>
            <category><![CDATA[rstudio]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Wed, 20 Feb 2019 00:00:00 GMT</pubDate>
            <atom:updated>2021-09-07T13:39:32.601Z</atom:updated>
            <content:encoded><![CDATA[<p>Blending the traditional manuscript with live code, data and interactive figures, we showcase a new way for researchers to tell their full story.</p><p><strong>By Giuliano Maciocci, Michael Aufreiter and Nokome Bentley</strong></p><p><em>(This article was originally published on eLife Labs on Feb 20, 2019, and reproduced here for archival and preservation purposes)</em></p><p>In September 2017 eLife announced the start of the Reproducible Document Stack (RDS) project, a collaboration between Substance, Stencila and eLife to support the development of an open-source technology stack aimed at enabling researchers to publish reproducible manuscripts through online journals. Reproducible manuscripts enrich the traditional narrative of a research article with code, data and interactive figures that can be executed in the browser, downloaded and explored, giving readers a direct insight into the methods, algorithms and key data behind the published research.</p><p>Today eLife, in collaboration with <a href="http://substance.io/">Substance</a>, <a href="https://stenci.la/">Stencila</a> and Tim Errington, Director of Research ar the Center for Open Science, US, published its <a href="https://elifesci.org/reproducible-example">first reproducible article</a>, based on one of Errington’s papers in the Reproducibility Project: Cancer Biology. This reproducible version of the article showcases some of what’s possible with the new RDS tools, and we invite researchers to explore the newly available opportunities to tell their story.</p><h3>Getting started with our reproducible article</h3><p><a href="https://elifesci.org/reproducible-example">Our reproducible article demo</a> showcases just some of the functionality that RDS tools will permit, and it’s intended as an easy starting point for exploring the technology. Here’s what you can do:</p><ul><li>Look out for the round blue ‘R script’-labelled buttons below Figure 1. Click it to reveal the code that generated that figure.</li><li>Edit that code, and press shift–enter to re-run it.</li><li>Observe the results in the figure in real time.</li></ul><p>Future iterations will enable fully downloadable datasets and table data, more interactive figure types, and the ability to download a pre-packaged DAR source file to make it much easier to fully replicate the whole reproducible manuscript in your local environment.</p><p>You can see more of the RDS’ potential in action by taking a look at this <a href="http://builds.stenci.la/stencila/update-the-introduction-rds-example-2018-11-16-db47651/example.html?archive=introduction">demo of Stencila</a>, one of the platforms behind the project.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*qviobVSa8YmHwXp1.jpg" /></figure><ol><li><a href="https://elifesci.org/reproducible-example">LAUNCH REPRODUCIBLE ARTICLE</a></li></ol><h3>How you can create a reproducible article</h3><p>The simplest way to author a reproducible article is with <a href="https://stenci.la/">Stencila Desktop</a>, a free, user-friendly manuscript editor. This combines the traditional authoring workflows of Word and Excel with the ability to embed R and Python code blocks that can analyse table data and generate live interactive plots using the powerful <a href="https://github.com/plotly/plotly.js">Plotly.js</a> library — features that will be very familiar to researchers who use Jupyter Notebooks. For non-coders, Stencila also provides a powerful formula language, Mini, that will be very familiar to those who prefer Excel for their data analysis.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/617/0*ZqEW5M4UrxFw8YC1.jpg" /></figure><p><a href="https://stenci.la/">DOWNLOAD STENCILA DESKTOP</a></p><p>Once an article is authored, Stencila Desktop saves it as a <a href="https://github.com/substance/dar">DAR</a> file (for Document ARchive), essentially a portable archive containing the article’s text, media, code and data. The DAR file also stores the article’s metadata (such as author details, affiliations and references) in a publisher-friendly format based on JATS XML. Sharing a DAR archive with a colleague, or making it available for download on a journal, GitHub repository or an author’s own website, lets scientists share their research in full like never before.</p><p>But what makes reproducible articles special is that they can be viewed, edited and executed from within a web browser. Should an author allow it, visitors to a reproducible article published online can, for example, see how a statistical analysis was performed to generate a figure, and actually alter the code generating that analysis and see the results change in real time. Should they wish to take that exploration further, readers can also download the original DAR file and have access to the exact same source code, formulae and datasets the original author embedded in their work.</p><h3>What about publishing?</h3><p>Our goal is to create a scalable publishing workflow for reproducible articles, and feedback from the community will help us build this functionality into our submission, review and production systems. For the time being, eLife will consider publication of reproducible articles as companions to any article, new or existing, that has been approved for publication.</p><p>If you’re a researcher with a published paper on eLife, or if your paper has just been approved for publication and you’re interested in giving others a deeper look into your work, please email us at innovation [at] elifesciences [dot] org and we will be happy to discuss.</p><p>If you’re a publisher interested in reproducible articles, please get in touch. All of the tools and technologies behind the RDS project are open, and we welcome the opportunity to help other publishers offer reproducible articles to their own authors and readers.</p><h3>This is only the beginning</h3><p>Reproducible articles are just starting out, and while they are a powerful evolution of the concept of a traditional research manuscript, they still have some limitations with regards to what they can do to make research truly reproducible. As we continue to work on the project, we will explore solutions to let authors reference very large external datasets in their code, cope better with long computation times, and expand built-in coverage for more popular R and Python modules. We’re also working on streamlining the author and reader user experience, adding support for supplementary and multi-panel figures and improved cross-compatibility with existing tools such as Jupyter and RMarkdown.</p><p>ADD A COMMENT <strong>1Open annotations. The current annotation count on this page is 1.</strong></p><p>Over the past few years Stencila has been researching, and experimenting on, alternative models and protocols for modular, composable, executable documents with an aim of creating more accessible interfaces for reproducible research. This has included developing ways to take the spreadsheet-like model of reactive, functional programming and apply it to articles containing open-source languages including R and Python. Stencila is now in the process of taking these prototypes and formalising them into a set of open schemas and specifications that others can develop against.</p><p>Along with finalising the DAR specification, Substance is working on generalising both code-editing and code-execution functions, in order to provide spreadsheet and word processor interfaces that can support formulae and source code in any language. While the code-editing interfaces are tied to Stencila runtime features, such as code analysis and remote execution, we want to draw a clear separation, defining an abstract interface for runtime environments. This will allow any DAR-compliant publication to be run on any suitable execution environment, ranging from a pure in-browser execution to container-backed runtimes to specialised environments which are tied to custom hardware. While we can’t serve every use case with one tool, we can maximise the technology’s value by opening up the interfaces. A next step will be the publication of a white paper document describing these new interfaces.</p><p>We will be sharing more about the project’s roadmap as our work continues.</p><h3>The technical magic behind the reproducible article</h3><p>The article that eLife published today builds on years of work by the community towards the long-standing vision of a fully reproducible, living research article. It represents a ‘bringing together’ of two of the primary frameworks currently used for reproducible research, RMarkdown and Jupyter. Under the hood it relies on many open-source applications and packages. It was made possible because the authors of the article went the extra mile in making their work reproducible, and registered their code and source data on the Open Science Framework (OSF).</p><p>We were able to download the author’s RMarkdown, R Scripts and data from the OSF. We used Stencila’s converter software to convert the article from the RMarkdown to JATS, the Journal Article Tag Suite — an XML format used by many publishers and upon which the DAR format is based. The converter uses Pandoc, a powerful and popular document conversion tool, and ensures that code cells in the RMarkdown are converted into the JATS extensions for reproducibility that DAR introduces. The result is an archivable article, in a format widely used by publishers, which also embeds the original source code. Stencila is continuing to work on improving its conversion software to ease the transition from existing formats to DAR.</p><p>Having source code embedded in the published article allows for transparency. But to achieve live execution from within the browser, we need a way to have R code executed remotely. To do this, Stencila’s interfaces connect to ‘execution contexts’ hosted within R or Python sessions. The execution contexts perform two steps. First, they analyse a chunk of code to determine the variables it depends upon, and any variable that is creates. This provides the automatic dependency analysis that enables Stencila’s reactive interfaces. Secondly, they actually ‘execute’ the chunk of code and return the result as data that can be rendered in document or re-used in another cell.</p><p>To reproduce this article, it is not only necessary to have the original source code embedded in the article; we also need to have an R session with the necessary R packages used by the code (e.g. ggplot2, cowplot) and the source data (CSV files which can be downloaded from OSF). Docker images provide a way of bundling source code, packages and data so that they can be re-executed. For this demo, rather than writing our own Docker images, we made use of the recently completed integration between Stencila and Binder — a project that was started by Daniel Nust and Min Ran-Kelley at the eLife Innovation Sprint in May 2018 (read more about this in <a href="https://elifesciences.org/labs/d42fe2b9/integrating-binder-and-stencila-the-building-blocks-to-increased-open-communication-and-transparency">Daniel’s blog post</a>).</p><p>We created a <a href="https://github.com/stencila/examples/tree/master/elife-30274">folder for the eLife article</a> in a GitHub repository which we could point Binder at. This folder contains two configuration files, runtime.txt and install.R, which tell Binder which version of R, and which R packages, to install into the Docker image. Thanks to Daniel and Min’s integration you can click on the “Launch Binder” button in the README of that folder to open an editable, interactive version of the article hosted by Binder.</p><p>To create a fully reproducible journal article, we wanted to go one step further and take a ‘<a href="https://elifesciences.org/labs/e5737fd5/designing-progressive-enhancement-into-the-academic-manuscript">progressive enhancement’ approach</a> in which the reader starts with a static document but can choose to ‘turn on’ the executable parts. In this approach, the content of the article, including the reproducible figures, are pre-rendered, hosted by the publisher, and can be delivered to the reader just like any web page. However, when the user chooses to edit any of the embedded code, the document is connected to a Docker container hosted by Binder. To do this, we created a tool called ‘<a href="https://github.com/stencila/bindilla">Bindilla</a>’ which acts as a bridge between the article in the browser and the container. Bindilla asks Binder to create a container for the image and then proxies requests for code execution to the execution contexts running in that container.</p><h3>Developer resources</h3><p>If you’d like to know more about the RDS project, or are a research or developer wishing to contribute to the project, here are some key resources to get you started:</p><ul><li>Stencila Desktop <a href="https://stenci.la/use/install.html">installation instructions</a> and <a href="https://github.com/stencila/desktop">code repository</a></li><li><a href="https://github.com/substance/texture">Texture repository</a>, the open-source manuscript editor that Stencila is based on</li><li>See the <a href="https://stenci.la/learn/integrations/converters.html">guide on the Stencila Converters</a> and the <a href="https://github.com/stencila/convert">relevant repository</a></li><li>And join <a href="https://gitter.im/stencila/stencila">Stencila’s chat channel</a> and <a href="https://community.stenci.la/">Community Forum</a>.</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=5e9040ef630c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Welcome to eLife 2.0]]></title>
            <link>https://gmaciocci.medium.com/welcome-to-elife-2-0-7d5f62b87a46?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/7d5f62b87a46</guid>
            <category><![CDATA[publishing]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[user-experience]]></category>
            <category><![CDATA[ux]]></category>
            <category><![CDATA[science-communication]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Thu, 01 Jun 2017 11:25:45 GMT</pubDate>
            <atom:updated>2017-06-15T14:15:22.692Z</atom:updated>
            <content:encoded><![CDATA[<p>We’re moving the online journal forward, and we hope you’ll join us on our journey.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/950/1*iabrr8IXafARoK8AR041ng.jpeg" /><figcaption>Illustration by Davide Bonazzi</figcaption></figure><h4>Why do we need an eLife 2.0?</h4><p>When I joined <a href="http://elifesciences.org/">eLife</a> just short of two years ago, I moved from a long stint in the corporate high-tech space into the scientific publishing realm, and got a serious taste of professional culture shock. Having spent much of my career as a user experience practitioner, I was taken aback at the state of online science journals when compared directly against the well-established standards of usability, accessibility and design that have become commonplace in the online services, retail, technology and social media spheres.</p><p>Responsive design, the ability for content to adjust its presentation seamlessly from one device to another, is still a rarity in the journal space. So are applied UX design principles, affordances for multiple reading and browsing behaviours, offline reading and performance optimisations, and a number of other practices most of the rest of the web takes for granted.</p><p>The eLife website did many of these things right, but it was still far from ideal. Born of a need to get up and running quickly in the fledgling days of the organisation, and tasked as an effective delivery vehicle for an innovative peer-review process, the site followed the standard online journal practice of displaying as much information about the article as possible, without a great level of care about whether, and how, this information should be prioritised.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Flz7lH8Qf5dMbXtZNxTwZg.png" /><figcaption>The new eLife homepage, left, next to the old</figcaption></figure><p>The result, again typical of many online science journals today, was a somewhat cluttered article view brimming with seldom used links and metadata, a sub-optimal <a href="https://webdesign.tutsplus.com/articles/understanding-visual-hierarchy-in-web-design--webdesign-84">visual hierarchy</a>, and an overall presentation that most users found less preferable than the stalwart format for research consumption, the venerable PDF.</p><p>The observation that the PDF, a proprietary legacy of the printed page era, still represents the dominant form through which the latest research is accessed, suggested that we as a journal had a real opportunity to look closely into what we could do to help our users transition towards more dynamic, rich, and interactive research artefacts that can more fully and faithfully convey the nuances of scientific discovery.</p><p>Thus began the effort that became eLife 2.0, a user-centred, bottom-up overhaul of our online journal aimed at delivering three key goals: deliver the best article reading experience, highlight content that enriches the research, and make it all easy to find. All while setting down a modern foundation for future innovation in the research publishing space.</p><h4>Goal 1: deliver the best article reading experience</h4><p>In an era of dynamic web content, open data, and increasingly powerful browsers, the PDF still rules supreme as the primary form through which new research is read. This is a shame, because it means fewer researchers are taking advantage of opportunities to more fully convey the full, reproducible narrative of their research through tools like interactive figures, executable code, and live data visualisations.</p><p>Our user research indicated a number of rather predictable reasons for PDF’s continued dominance as a research consumption format, including portability, offline reading use cases, and good old fashioned familiarity. But one of the most prevalent reasons given by our users for preferentially using PDF really surprised us: <em>“because it looks nicer”.</em></p><p>Aesthetics are easy to underestimate in the realm of reason and scientific rigour, but even the most analytical mind is still human after all and, whether consciously or not, appreciates reading experiences that minimise visual noise, reduce distractions, and therefore limit sources of cognitive load beyond what’s needed to interpret the content being read. In the case of research articles, “<em>looking nice</em>” is in fact a proxy for some important aspects key to an article’s readability:</p><ul><li>A clean layout, with a clear visual hierarchy</li><li>No intrusive sidebars, calls to action, thumbnails or adverts</li><li>A legible, high-contrast font</li><li>Good-sized figures that can be consumed alongside the article text</li></ul><p>These aspects formed the basis of eLife 2.0’s article page design, and went on to influence every major design decision throughout the rest of the site.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ib3hbo48LoJMGxEkMSb1EA.png" /><figcaption>The new Article page (left) drastically simplifies scanning for relevant information against the previous design</figcaption></figure><p>Inspired in part by research into reading behaviours, as well as reading-focused platforms from Medium to the Amazon Kindle, the new article page in eLife 2.0 provides a clean, distraction-free layout with a flexible navigation structure that supports how reading and skimming behaviours vary across desktop and mobile. In addition, eLife 2.0 article pages more seamlessly embed our signature Lens view (for simultaneous text and figure browsing), which is now accessible by selecting the <em>Side by Side</em> option alongside the traditional Article and Figures views.</p><p>The new article pages are also optimised for reading across a wide range of devices and screen sizes, and should load significantly faster than our previous site thanks to a streamlined page asset budget and our new <a href="http://iiif.io/">IIIF-enabled</a> figures. Standing for International Image Interoperability Framework, IIIF allows us to more efficiently serve the large images behind our figures by efficiently delivering only the bare minimum image data needed to render an image at any given screen size.</p><p>IIIF also forms the basis of further enhancements to the site. Shortly after launch, we will be deploying an enhanced asset viewer that will take full advantage of IIIF’s feature set. This new viewer, which we’ll also release as a standalone open source component, will allow figures viewed in full screen, and all their supplements, to be zoomed with very fine granularity thanks to <a href="https://openseadragon.github.io/">OpenSeaDragon</a>. This will let users interact with very large, highly detailed images with no performance penalty on almost any device. In the future, IIIF will also allow us to explore the ability to let users annotate our figures, as well as a number of other interesting use cases.</p><p>And what about offline reading? We’ve now laid the groundwork for the implementation of <a href="https://ponyfoo.com/articles/serviceworker-revolution">Serviceworker</a>, a technology that will soon let eLife 2.0 articles cache locally on your machine, so that once you’ve browsed to an article you can go offline, reload it from your browser history or a bookmark at a later date, and it will still be there waiting for you. Or, you could download the article into <a href="https://github.com/codeforscience/sciencefair">ScienceFair</a> and take advantage of its powerful manuscript management functions while enjoying your papers though our eLife Lens view.</p><h4>Goal 2: highlight content that enriches the research</h4><p>eLife’s in-house teams generate a large amount of content, such as Insights, Feature Articles and Editorials, that add both context and perspective to the science we publish. These articles also appeal to a broader, less specialised audience, and promote a shared understanding of scientific discoveries across disciplines.</p><p>In eLife’s previous iteration, this content could be quite difficult to find (Some users didn’t even know we had a regular podcast), so we wanted to make sure that all this content had a proper home, a portal where readers could more easily access this material.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3CpjtmqOZIbwdRTNyV9f3Q.png" /><figcaption>Our brand new Magazine section highlights the content that builds on the research.</figcaption></figure><p>The Magazine section of the site was created as just such a portal, showcasing everything from our latest Insights, Feature Articles and Editorials to subject-specific Collections, our Podcast and a range of content for and about early-career researchers.</p><p>It is our hope that the Magazine will establish itself as an alternative entry portal to eLife’s content that appeals both to specialists who are keen to read about developments in other fields, and to non-specialists looking for a perspective on the latest research across the life sciences.</p><h4>Goal 3: make it all easy to find</h4><p>Search was never a strong use case for the eLife website, given the majority of our visitors originate from search engines such as PubMed and Google Scholar, and enter our site directly at the individual article level.</p><p>But search is not the only way to find relevant content, which is why we have completely overhauled both the site’s navigation as well as its content recommendations infrastructure. What this means, is that specialists can jump directly into their subject of interest from the home page without having to so much as scroll, or get there directly from an article by clicking the appropriate tag.</p><p>In eLife 2.0, research categories are now treated like mini home pages in their own right, presenting relevant, up-to-date Research and Magazine content in a single organised view — allowing users so inclined to bookmark their research category of choice and streamline their browsing experience.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WCZWQ6Nx8Xf7upsVKRjx-w.png" /><figcaption>The new research category pages (left) provide custom landing pages for research specialists.</figcaption></figure><p>Finally, when you’re done reading an article in eLife 2.0 you will be discreetly introduced to a set of closely related articles, to help you discover more relevant science, or to more easily follow the full narrative of a discovery without leaving the article page.</p><p>And yes, we have also overhauled our global search capability to cover all content types across the site and provide more intuitive filtering, so you should always get the most relevant results whether you’re searching for an author name or a model organism (or anything in between).</p><h4>Performance, patterns, and giving it all away</h4><p>eLife 2.0 is the result of roughly eighteen months of user-centred design, development and testing, with many key site features having seen dozens of iterations as a result of direct user testing and performance optimisations. And while we’ve made every effort to ensure the site serves as a good example of UX and accessibility best practices, we know others can do even better.</p><p>To that end, we will soon be releasing all the UI patterns, style guides and key visual and code assets developed for eLife 2.0 under a CC-BY license as part of eLife’s <a href="https://elifesciences.org/elife-news/elife-introduces-continuum-new-open-source-tool-publishing">Continuum</a> publishing platform, in the hope that they will lower the barrier to entry for other publishers to use what we learned in the making of eLife 2.0 to improve their own user experience.</p><p>By using these assets, other publishers will also be able to take advantage of the substantial performance gains delivered by our minimalist design patterns, while making their own sites substantially more maintainable by adopting our novel approach to the use of <a href="http://patternlab.io/">PatternLab</a> for the modular implementation of the site’s front-end (a post on the subject will follow soon).</p><p>We have worked hard to make sure that eLife 2.0 brings across-the-board improvements to our users, and now that the site is out we have many new features in the pipeline, to be announced in the coming months. We will be measuring the success of the project not only by its impact on the usual visitor metrics, but also on whether and how the assets and resources we release to developers are used, and whether they are judged as helpful by the community.</p><p>If you have any feedback on <a href="http://elifesciences.org/">the new site</a>, we’d love to hear from you. If you like what we’ve done, please tell your friends and colleagues. If you don’t, please <a href="https://elifesciences.org/contact"><strong>tell us</strong></a><strong>!</strong></p><p>Thanks for joining us on the next phase of our journey.</p><p>UPDATE: If you’d like to know more about the process of designing and user testing eLife 2.0, read <a href="https://medium.com/@nick_duffield/redesigning-an-online-scientific-journal-from-the-article-up-1-early-designs-ee48d79fa02a">the first in a series of posts</a> on the subject by Nick Duffield, the project’s lead UX designer.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7d5f62b87a46" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Designing Progressive Enhancement Into The Academic Manuscript]]></title>
            <link>https://gmaciocci.medium.com/designing-progressive-enhancement-into-the-academic-manuscript-907298f827d1?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/907298f827d1</guid>
            <category><![CDATA[publishing]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[science]]></category>
            <category><![CDATA[digital-publishing]]></category>
            <category><![CDATA[user-experience]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Thu, 02 Feb 2017 09:59:30 GMT</pubDate>
            <atom:updated>2017-09-20T14:23:25.669Z</atom:updated>
            <content:encoded><![CDATA[<p>The academic manuscript is evolving into a complex, deeply interconnected digital artefact. We need to consider a design strategy to accommodate the transition.</p><blockquote><strong><em>Progressive enhancement</em></strong><em> is a strategy for web design that emphasises core webpage content first. This strategy then progressively adds more nuanced and technically rigorous layers of presentation and features on top of the content as the end-user’s browser/internet connection allow. — </em><a href="https://en.wikipedia.org/wiki/Progressive_enhancement">Wikipedia</a></blockquote><h3>State of play</h3><p>There has been, and there will continue to be, a lot of discussion within the academic publishing community as to how to divest from a longstanding print legacy and truly embrace new digital technologies for the dissemination of research output.</p><blockquote><strong><em>Update</em></strong><em>: Since this post was written, eLife and Substance have teamed up to apply its principles in practice. Find out more about it </em><a href="https://elifesciences.org/for-the-press/e6038800/elife-supports-development-of-open-technology-stack-for-publishing-reproducible-manuscripts-online"><em>here</em></a><em>.</em></blockquote><p>Yet the traditional manuscript format still rules supreme, considered by most the ultimate long-form narrative of a discovery. Composed mainly of text and static figures, the primary research artefact through which most researchers share new discoveries is still primarily consumed as a printable PDF: the digital equivalent of a printed page.</p><blockquote>complex datasets, and sometimes the code used to analyse them, are ultimately reduced to little more than PNG images.</blockquote><p>At the same time online HTML versions of the research manuscript are increasingly becoming <em>nexus artefacts</em>. No longer self-contained entities, today’s online manuscripts link out to a growing variety of data, stored across a growing number of both general purpose (<a href="http://datadryad.org/pages/repository">Dryad</a>, <a href="https://giving.web.cern.ch/civicrm/contribute/transact?reset=1&amp;id=20&amp;gclid=CJSvzb3F7tECFcsV0wod5hgHQQ">Zenodo</a>, <a href="https://figshare.com/">figshare</a>) and specialised (<a href="http://proteopedia.org/">Proteopedia</a>, <a href="https://www.ncbi.nlm.nih.gov/genbank/">Genbank</a>) repositories.</p><p>Much of this data is typically linked to the manuscript via a simple URI, or is at most visualised within the context of the manuscript itself through a static figure representing a snapshot of whatever state of the data, or its analysis, the manuscript’s author deemed most relevant to the manuscript’s narrative. And so complex datasets, and sometimes the code used to analyse them, are ultimately reduced to little more than PNG images.</p><h3>Moving forward</h3><p>Things are changing however. Researchers and publishers have an increasing number of options at their disposal to integrate new types of rich content directly into their online manuscripts. Interactive figures, for example, can provide authors with more tools to present their findings, and readers with richer ways to interact with them. Today’s combination of browser technology and increasingly powerful cloud computation allow for the direct, and increasingly powerful visualisations of a manuscript’s data within the context of the manuscript itself, from <a href="http://jmol.sourceforge.net/">3D molecular visualisations</a> to <a href="https://elifesciences.org/elife-news/toward-publishing-reproducible-computation-binder">executable code</a>.</p><blockquote>What used to be a the online equivalent of a printed page can now contain entire virtual machines</blockquote><p>Let’s take the latter example: until very recently, vetting or replicating a data analysis referred to in a research paper used to require finding the relevant GitHub repository for the algorithm, cloning it, replicating the author’s runtime environment and all its dependencies on a local machine, downloading the relevant data set, and running the code on top of it. Today, all of that can be embedded within the online version of the paper itself via services like <a href="http://mybinder.org/">Binder</a> or <a href="https://codeocean.com/">CodeOcean</a>, and executed with a single button press, enabling a whole new category of interactive figure.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YRz0b7MnbeTj8do2P0pPOA.png" /><figcaption>Example of an embedded Integrated Development Environment (source: <a href="http://codeocean.com/">codeocean.com</a>)</figcaption></figure><p>But while these tools offer new opportunities to enhance the discoverability of research output, their use within an online manuscript also brings considerable challenges. What used to be the online equivalent of a printed page can now contain entire virtual machines, requiring access to cloud computing resources and streaming massive datasets.</p><p>Such a manuscript is therefore no longer easily portable, is challenging to consume on anything but a desktop, and requires a live internet connection for some of its richer figures to display properly. The core content of the manuscript now also bears new dependencies to digital assets outside of the publisher’s purview.</p><p>Add to that the necessity of providing a (sadly still necessary) PDF copy to the paper without losing critical content, and you’re looking at something of production nightmare. By comparison, making the HTML version of a manuscript responsive so it can render on mobile devices (which incidentally many online publications are yet to do well) doesn’t seem like such a big deal.</p><h3>Progressive engagement</h3><p>We’ll take a brief look at how a progressive enhancement design philosophy can help overcome some of these challenges. But while we can apply progressive enhancement to account for device, dependency and connectivity issues with interactive figures, we should also consider how the same design philosophy addresses how users engage with research content online:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z3POR9apAMAl9hkQ-_jXYQ.png" /><figcaption>Progressive engagement with research artefacts</figcaption></figure><p>Let’s take the above user behaviour progression as a rough example. We can start to see how the way we present our manuscript and figures should afford different levels of interaction based not just on device and connectivity concerns, but on the user’s different stages of engagement with the content.</p><p>The ideal presentation of a research artefact should therefore coax the user into increasingly higher levels of engagement, with a particular focus on providing the user with the just right level of context to bridge the delicate transition from partial to full engagement.</p><p>Put simply, we don’t want to overwhelm the user with a rich interface presenting embedded code they must read and execute in order to see an output, when all they want is to know at an earlier level of engagement is whether that output is even relevant to them in the first place.</p><blockquote>a research artefact should therefore coax the user into increasingly higher levels of engagement</blockquote><p>We also don’t want to assume the above behaviour progression is always true: a user could for instance be looking for a specific example of a method, figure or result across multiple papers, and may not be interested in each manuscript’s narrative as a whole.</p><p>And finally we must account for the platform from which the user may be engaging: while more casual interactions may well be catered for by a mobile device, tasks indicative of deeper levels of engagement would realistically only be carried out on a more capable desktop platform and its associated input and display methods.</p><h3>Progressive enhancement</h3><p>So what we need here is a graduated approach to handling these increasingly rich data types, levels of user engagement, and consumption platforms without losing the core benefits of today’s manuscript formats: easy consumption and portability. We can therefore take the PDF as the worst-case, legacy form of the core manuscript content, and build up from there.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/833/1*yaZwU5xiUr5rQXdSDmWn3Q.png" /><figcaption>Progressive enhancement of a single figure: static, interactive, code, external resource.</figcaption></figure><p>So going back to our embedded analysis code example, we can start thinking about an implementation that roughy follows this outline:</p><ol><li>Start with embedding a lightweight static figure (a snapshot) of the key output of the code. This should represent whatever state the author deems fit to best convey the key finding/narrative contribution of the code in question. This will only serve as the minimum viable experience for skimming purposes (Casual engagement), but also as a safe baseline for when the content is being accessed through less capable devices, as a printable/PDF compatible output, and as a valid snapshot of what state the data was in when it was peer-reviewed (where applicable).</li><li>Allow the user to switch the static figure to an interactive output where supported, providing whatever level of UI is needed to appreciate the output in full.</li><li>Where appropriate, allow the user to dig behind the output of the interactive figure and directly look at the code behind it. You may at this stage allow minor edits to the algorithm and the ability to run it again in-situ to view the output.</li><li>If the user wants to engage further, for example intending to fork or modify the code, or do anything more complex, provide links to the most appropriate external resource where the user can benefit from a more appropriate environment or UI to do their work (e.g., the original GitHub and/or data repository, or an online IDE).</li></ol><p>In the relatively simpler case of a 3D visualisation, we can use just steps <strong>1.</strong> and <strong>2.</strong> to ensure a baseline level of compatibility for a figure even as we provide the ability to directly interact with the 3D content.</p><p>In summary, we have effectively recast the classic figure viewer as an <em>asset viewer</em>, and populated the element with increasingly rich versions of the same asset as the user continues to engage with it.</p><p><em>(Note: In cases </em><strong><em>2.</em></strong><em> and</em><strong><em> 3.</em></strong><em> we ideally want to embed a strictly versioned snapshot of the code locked at the stage of manuscript review, but that’s a discussion for a different day).</em></p><h3>Lightweight implementation example</h3><p>In order to fully leverage the advantages of progressive enhancement, it would also be helpful if all of a manuscript’s progressive levels of interaction were somehow encapsulated within a single canonical description of the manuscript and all of its core content.</p><p>For example, when dealing with figures a <a href="https://jats.nlm.nih.gov/">JATS</a> XML based authoring toolset like <a href="http://substance.io/texture/">Texture</a> could introduce a <em>source</em> attribute to keep track of alternative forms of the same figure and their dependencies, while allowing for the addition of third-party embeds for code, 3D and other data.</p><p>At its simplest, using the Texture framework to link a static figure as an alternative to the dynamic output of a spreadsheet cell would look something like this:</p><p><em>&lt;graphic texture:src=”Sheet1!C15&quot; xlink:href=”fig1.png”/&gt;</em></p><p>The regular <em>xlink:href</em> would ensure a valid static snapshot of the data in the figure is always available.</p><p>(Thanks to Michael Aufreiter at <a href="https://medium.com/u/4d45f4249313">Substance</a> for this example)</p><p>Compatible publishing platforms could then take that core JATS XML manuscript description and use it to render the right form in the right context: simple static figures when creating a PDF or rendering to mobile, or full embeds when delivering to a desktop browser.</p><h3><strong>Conclusion</strong></h3><p>In the context of research artefacts, the presentation of interactive figures in manuscripts is only one example of how a progressive enhancement design approach can be helpful in framing design and development decisions.</p><p>By taking into account varying levels of user engagement <em>as well as</em> various tiers of device capability, publishers and tool creators in the research space can ensure a smoother transition to new and richer ways of presenting research outputs.</p><p>It’s also important to note that progressive enhancement can and should also be applied to the manuscript as a whole. Increasing layers of semantic highlighting and its related interactions can for example be deployed incrementally as the user moves deeper down the text, so as not to overload the user experience at when that user’s level of engagement is still low.</p><p>Finally, the same principles are applicable to the presentation of smaller, discrete research objects beyond the manuscript format, where the opportunities for more novel interactions can also benefit from a more granular handling of both user behaviours and platform constraints.</p><p><em>(Thanks to </em><a href="https://chanzuckerberg.com/"><em>CZI</em></a><em>, </em><a href="http://substance.io/"><em>Substance </em></a><em>and </em><a href="http://elifesceiences.org/"><em>eLife Sciences</em></a><em> for inspiring this post. Stay tuned for an upcoming follow up by </em><a href="https://medium.com/u/4d45f4249313"><em>Substance</em></a><em> with more detail on implementation strategies, and make sure to check out their piece on </em><a href="https://medium.com/@_mql/reproducible-science-for-people-who-dont-code-5850abe806db#.29g9ss7q5"><em>Reproducible Science for People Who Don’t Code</em></a><em>)</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=907298f827d1" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[On VR, Exclusivity, and Misdirected Outrage]]></title>
            <link>https://gmaciocci.medium.com/on-vr-exclusivity-and-misdirected-outrage-c1868ad499fa?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/c1868ad499fa</guid>
            <category><![CDATA[oculus-rift]]></category>
            <category><![CDATA[gaming]]></category>
            <category><![CDATA[software]]></category>
            <category><![CDATA[virtual-reality]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Tue, 21 Jun 2016 15:12:23 GMT</pubDate>
            <atom:updated>2016-06-21T15:12:23.188Z</atom:updated>
            <content:encoded><![CDATA[<p>Why timed exclusives are (temporarily) good for VR.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/440/1*JDvC5f_smeID2b4k0lA32A.jpeg" /></figure><p>Originally published on <a href="http://twitter.com/augmentl">Augmentl</a>.io, June 21 2016</p><p>Over the past few weeks, the long running debate over software exclusivity in the VR space has reached unprecedented levels of intensity, hostility, and vitriol. Does Oculus’s approach of funding game development in return for timed exclusivity foster the development of VR content, or does its strategy threaten to splinter a market still in the process of finding its feet?</p><p>Like most internet dramas, the latest instalment in the exclusivity debate started with a throwaway comment on Reddit, where Mario Kotlar, a member of the Croteam team developing Serious Sam VR, implied that Croteam had turned down “<a href="https://www.reddit.com/r/Vive/comments/4nxpnq/fuck_facebook_and_fuck_oculus/d480x6v?context=3">a shitton of money</a>” from Oculus offered in exchange for the game’s exclusive release on the Oculus platform.</p><p>The issue was further incensed by a separate but related discussion surrounding the announcement that <a href="http://www.roadtovr.com/giant-cop-on-htc-vive-available-via-humble-bundle-until-18th-march/">Giant Cop</a>, a game previously announced for the HTC Vive, had now ditched Vive support in favour of an exclusive release on the Oculus platform. Oculus was once again accused of “buying out” a developer to gain an unfair advantage over the competition.</p><p>Things were not so clear cut, however. Upon requests for clarification, Croteam confirmed in a statement that Oculus offered the team a grant to to accelerate Serious Sam’s development in exchange for limited time exclusivity on the Oculus platform, with the understanding that the game would eventually come to all VR platforms. Similarly, Oculus’s grant to Other Ocean, Giant Cop’s developer, did not even ask for timed exclusivity at all: it was in fact Other Ocean <a href="https://uploadvr.com/giant-cop-speaks-oculus-exclusivity/">who first suggested</a> a limited time exclusivity so they could focus first on improving the game rather than investing time in multi-platform compatibility.</p><p>Neither of these clarifications however have done much to abate the fierce debate on exclusivity in VR titles, with many VR enthusiasts taking to the internet to advocate opposing positions. Some advocate that there is simply no excuse for hardware exclusives in the VR marketplace, praising Valve for its universal VR headset support in its SteamVR platform. Others see Oculus’s investment in the development of games as a crucial contribution to the creation of quality VR content, and question Valve’s lack of first-party commitment.</p><p>What is clear is that debating the question of exclusivity from an emotional, philosophical or idealistic standpoint fails to take into consideration the harsh realities of game development, and the uneven market positions of the two main contenders in the VR content space, Oculus and Valve.</p><p>First, game development is risky, expensive, and time consuming. While the availability of modern content creation tools like Unity and Unreal Engine, and their excellent support for VR, has given anyone with an idea the ability to release an interesting tech demo, turning that demo into a full game with any depth is a challenge orders of magnitude more complex.</p><p>Secondly, the audience for PC VR content is extremely limited at this early stage in the game, with the total number of VR devices in consumer hands being almost insignificant compared to the addressable PC market as a whole. Thus, while a AAA studio with a steady revenue stream can take the risk of investing in the creation of a new VR property, a smaller indie developer would incur a significant risk should their VR title not succeed. Small game studios have gone bust while undertaking less risky endeavours.</p><p>Finally, and perhaps most importantly, one needs to consider the relative positions of Valve and Oculus with regards to VR: for Oculus, VR is everything, and failure is not an option. Oculus needs to do everything it can to “prime the pump” of the VR content marketplace, stimulating the necessary virtuous cycle of interdependent software and hardware sales needed to create the critical mass of users that will ultimately reduce the risk of developing new VR content. More quality VR software leads to greater adoption of VR hardware, which leads to less risk for game developers.</p><p>For Valve, on the other hand, VR is a low-risk project with plenty of upside and negligible risk: should VR succeed, Valve would gain yet another channel in which to expand its quasi-monopoly on digital distribution. Should VR fail, however, the impact on Valve’s bottom line would be minimal, even with <a href="https://m.reddit.com/r/Vive/comments/4osav8/lighthouse_tracked_osvr/d4gdtr6">a third of the company</a> supposedly now dedicated to VR.</p><p>We can also look at the practical effects of the two main contenders’ relative policies on content. While the HTC Vive’s roster of mainly room-scale experiences is unarguably excellent, its overall content portfolio generally tends to be represented by shorter experiences, focused around novel but limited mechanics, such as Space Pirate Trainer, Job Simulator, Fantastic contraption, and Budget Cuts. Brilliant games with relatively modest budgets.</p><p>The Oculus content portfolio, by way of comparison, includes a greater number of high-budget, story-driven, multi-hour titles approaching traditional AAA production levels, notably Edge of Nowhere, Chronos, Lucky’s Tale, and Eve: Valkyrie — All of which are the direct result of partial or full funding of the games’ development by Oculus itself.</p><p>Neither the Vive’s nor the Oculus portfolio of games can objectively be called “better,” but the addition of Oculus’s high budget titles to the Vive’s excellent complement of indies undoubtedly adds a greater variety and richness to the overall VR content space, something which would have been more difficult to achieve without Oculus’s dedicated investments and the company’s <a href="http://superhotgame.com/2016/06/15/3-years-of-vr-history-year-2-will-surprise-you/">direct enagement with developers</a> trying to overcome the challenges of creating quality VR content.</p><p>It is also important to note that with the exception of titles fully commissioned, developed and/or funded by Oculus, there is no evidence to this day that Oculus has ever asked for more than a limited-time exclusivity in return for issuing a development grant. As a result, after a mere six months following their release on the Oculus store, the HTC Vive community will be enjoying a slew of Oculus-funded games that may never have existed at all, or may not have been as rich, had Oculus not actively invested in their developers. By contrast, while even HTC itself is actively engaging in the funding of VR game development, we are yet to see a quality, high-budget VR title funded (or indeed developed) by Valve.</p><p>That last aspect may however be about to change, with reports that Valve may finally be setting up a mechanism to help struggling indie developers take some of the risk away from developing VR content. According to Gabe Newell, Valve’s founder, his company will be offering what amounts to cash advances on Steam revenues to prospective VR developers, to be deducted from their game’s actual Steam sales once it’s released. While this will indeed allow developers to reduce their risk when developing their game, it is still money that will be repaid to Valve should a game be successful — in stark contrast to Oculus’s developer grants, which are repaid only with a limited time exclusive release on Home.</p><p>In the near future, the VR marketplace will become sufficiently mature to reduce the risk to developers of committing to the creation of quality VR content. When that happens, even the concept of timed exclusivity will become redundant. Until then, however, we should look at timed exclusivity as a benign, temporary inconvenience: if timed exclusivity deals ultimately succeed in convincing more developers to direct their talents towards VR, they may well be a price worth paying.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c1868ad499fa" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[On Oculus, Valve and Revisionist History]]></title>
            <link>https://medium.com/augmentl/on-oculus-valve-and-revisionist-history-8b0214fd1e17?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/8b0214fd1e17</guid>
            <category><![CDATA[oculus-rift]]></category>
            <category><![CDATA[valve]]></category>
            <category><![CDATA[virtual-reality]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Thu, 26 May 2016 10:04:14 GMT</pubDate>
            <atom:updated>2017-03-15T16:07:18.503Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QcMlllFpTPYeitNBDzZ6tA.jpeg" /></figure><p>Originally posted on <a href="http://augmentl.io/">Augmentl.io</a>, 26th May 2016.</p><p>There is a new a <a href="http://uploadvr.com/valve-shared-vr-oculus/">bedtime story</a> for the age of Virtual Reality. It goes a little something like this:</p><p><em>“Once upon a time, there was a young Magician, who wanted to build a pair of magic glasses.</em></p><p><em>But no matter how hard he tried, his magic glasses would make people feel bad.</em></p><p><em>So he turned to a wise old Wizard, and his team of busy elves, who shared with him the secret to building magic glasses that made people feel good.</em></p><p><em>But then the young magician was hired by the Evil King, and took Wizard’s secrets with him. He built the King the best magic glasses in the kingdom, without giving the Wizard or his elves anything in return.</em></p><p><em>This made the Wizard very angry, and so he sent one of his angriest elves to bad-mouth the Magician on Twitter at every opportunity.</em></p><p><em>The End “</em></p><p>I didn’t say it was a <em>good</em> bedtime story. But the newly popularised saga of how Oculus appropriated Valve’s VR technology during its early days and then proceeded to turn it against them following the Facebook acquisition, while a cute little tale, smacks of revisionist history. Valve’s Alan Yates and his anti-Oculus statements, rather than highlighting Oculus and Facebook’s implied duplicity, smack in fact of sour grapes and missed opportunities.</p><p>What history boils down to is this. When Palmer, Carmack and the scrappy little VR startup that would later be bought by Facebook for two billion dollars were struggling to solve the motion sickness issues plaguing their early VR prototypes, Valve stepped in and, in the spirit of collaboration, shared one of their own VR prototype, a dual-screen contraption that seemed to solve the problem.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p24YVhNhnz7fL8Uy5znieQ.png" /></figure><p>Oculus then ran with the concept, and used what it learned from it to accelerate its development of a polished consumer VR experience. When Facebook acquired Oculus a few months later, the major cash influx resulted in both an extension of the Rift’s scope (from an improved DK2 to what it is today) and Oculus’s overall ambitions — to be not only a provider of the best possible VR hardware for consumers, but to become the de-facto marketplace for the digital distribution of VR content.</p><p>That last part, which materialised in the form of the Oculus Home digital storefront catering to all of the Rift’s exclusive content, is the part Valve is taking issue with. It is clear that Valve’s original intentions in sharing their technology was to foster the development of a hardware ecosystem that would have created yet another avenue with which to expand their Steam digital distribution quasi-monopoly. What Valve did not expect was for Oculus to step on their storefront’s turf.</p><p>But this is where the the whole <em>Good vs. Evil</em> narrative falls flat. Back then, Valve also had no interest in getting their own hands dirty with actually making VR hardware. Manufacturing is hard, and in the Valve business model it is more profitable to just license the Steam platform (say, to the so-called and wildly unsuccessful Steam Machines) than it would be to manufacture actual hardware.</p><p>Were it not for Palmer’s scrappy team of dreamers, in fact, VR would in all likelihood still be some ridiculed concept on the trash heap of discarded technology ideas: a toxic technology no sane person would wrap their business model around. In Michael Abrash’s own words (Oculus’s chief scientist and one of three high profile Valve defectors to the company):</p><blockquote>“In the space of two years, a relative handful of people at two companies, none of them VR experts at the start, somehow managed to resurrect VR from the trash heap of technologies-that-never-were and make it the most exciting technology around. That wouldn’t have happened if Palmer hadn’t developed his prototype. If John hadn’t been investigating VR at the right time. If they hadn’t run into each other. If I hadn’t been looking for a new platform.”</blockquote><p>So while it is absolutely true that Valve’s early research was significant, some may even say critical, to the development of the Rift as it is today, it is also true that, had Valve not shared their work with Oculus, Valve’s early VR prototype would have remained just that. Valve <em>needed</em> Oculus’s momentum if they wanted to realise that early VR research into an actual market opportunity for their core business asset, the Steam digital store.</p><p>Left to their own devices, Valve would likely not have ben able (or willing) to take their VR prototype to the next level: not without Oculus’s fervent evangelism of VR, their unprecedented Kickstarter campaign, Facebook’s subsequent $2bn validation of a fledgling market previously seen as poison, and the ensuing gold rush that seeded the market with a veritable abundance of hardware manufacturers eager for a piece of the action — one of which was none other than HTC.</p><p>Why else would Michael Abrash, Atman Binstock and Aaron Nichols, Valve’s own VR dream team, have felt the need to defect to Oculus in order to realise their passion? Because they knew Valve’s own commitment to making VR happen would not match Oculus’s.</p><p>Alan Yates, the architect of Valve’s Lighthouse solution for the HTC Vive, has been <a href="https://www.reddit.com/r/Vive/comments/4klu94/oculus_becoming_bad_for_vr_industry/d3g6e6j?context=3">very outspoken</a> in trying to remind the world that Valve’s early research is responsible for much of the Rift’s core technology. But Yates also conveniently fails to acknowledge that research, no matter how critical, is only as good as its execution.</p><p>Without Oculus’s achievements in validating the whole VR market opportunity and defining the highest standards for the VR hardware and software experience, Valve would not have a found a partner in HTC. Neither would Valve have VR industry to help foster, or a VR consumer base to which to market its wares. Without Oculus, Valve’s early VR prototype would likely be collecting dust in a cabinet somewhere while the company mulled how to best expand into the mobile gaming market.</p><p>So yes, Valve handed Oculus some core technology two years ago. But Oculus handed Valve (and the whole industry) the most disruptive and significant market opportunity since the advent of the smartphone.</p><p>I’d say the debt is paid in full.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8b0214fd1e17" width="1" height="1" alt=""><hr><p><a href="https://medium.com/augmentl/on-oculus-valve-and-revisionist-history-8b0214fd1e17">On Oculus, Valve and Revisionist History</a> was originally published in <a href="https://medium.com/augmentl">Augmentl</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My Less Than Perfect Demo. Or, How I Came
To Love The HTC Vive.]]></title>
            <link>https://gmaciocci.medium.com/my-less-than-perfect-demo-or-how-i-came-to-love-the-htc-vive-80a0019b076f?source=rss-2d1c22d26fc3------2</link>
            <guid isPermaLink="false">https://medium.com/p/80a0019b076f</guid>
            <category><![CDATA[htc-vive]]></category>
            <category><![CDATA[virtual-reality]]></category>
            <category><![CDATA[oculus-rift]]></category>
            <dc:creator><![CDATA[Giuliano Maciocci]]></dc:creator>
            <pubDate>Thu, 17 Dec 2015 11:35:02 GMT</pubDate>
            <atom:updated>2015-12-17T11:35:32.167Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nEbuNTm-s3aSXK-jqkzbdA.jpeg" /></figure><p>I was given the opportunity to take their HTC Vive for a spin. I was not impressed. At first.</p><p>Originally published on <a href="http://augmentl.io/">Augmentl.io</a> (<a href="http://twitter.com/augmentl">@augmentl</a>) on November 21, 2015.</p><p>My chance to test the Vive came as part of the demo day organised by the excellent folks over at GameFace Labs, where I also had the opportunity to <a href="http://augmentl.io/hands-on-with-gameface-labs-latest-prototype/">play with their latest hardware</a>. The Vive was in some ways everything that it was supposed to be, but in other ways not what I was expecting.</p><p>The fault was not in the device itself, but rather in the insane amount of expectation and anticipation the generally glowing reviews of the hardware had instilled in me. I had all the device’s specs in my head, and was prepared to test each and every one of them in my limited 45 minute session.</p><p>So when I first got to strap on the Vive, and was put inside the Aperture Science demo, I instantly ran through a mental checklist of specifications:</p><p><em>“Screen door effect? I can see it. Damn it. Wait no, I’m really focusing on the screen. Relax. OK it’s gone. Theres a kind of a linen texture to the screen. Must be the diffuser. Not bad!”</em></p><p><em>“OK. Field of View? Subjectively wider than the DK2. Maybe not as tall. Not bad, I can live with this!”</em></p><p><em>“IPD? It’s off. I need to fiddle with it. OK I think I got it. No, wait… OK now I got it.”</em></p><p>And so on. I just could not relax into just experiencing the moment. All my anticipation, the preconceived expectations, and all the technical specs rattling in my head were actively conspiring from actually being in the moment and just experiencing the damn thing.</p><p>Initially, I time-shifted between “testing” the device and figuring out what the demo wanted me to do. I needed to open a drawer, but Chaperone was telling me I was about to reach a wall. That’s the Ed from GameFace, detecting my helpless floundering, helpfully tipped me off that I could “extend my reach” by pressing down on the controller’s touchpad. Aha! OK<br>now I could move on.</p><p>Then my left controller’s trigger started acting up. Was it acting up or was I screwing up? At this point, the elusive holy grail of VR, <em>Presence</em>, was nowhere to be seen. Both myself and those tiny technical glitches were getting in the way.</p><p>But somewhere along the way, it happened. At some point between me failing to fix a broken robot and the floor opening up below me, I was <em>there</em>. My stupid brain finally bought into the illusion and I was gobsmacked.</p><p>After Aperture Science I was put through TiltBrush (I wish I had talent), The Gallery (Wish I knew what I was doing), and Job Simulator (Wish I could have stayed there for a few hours). All of which I enjoyed immensely. Others have done a much better job reviewing these experiences than I could, so I’ll avoid doing that here.</p><p>As I reached the end of Job Simulator, I barely caught myself dropping the controllers onto a kitchen counter that was’t there. I don’t think me dropping the controllers on the floor would have endeared me to the GameFace team, but that almost-oops moment did confirm one thing for me: this thing is the real deal. And I want one. Now.</p><blockquote>It’s a lot easier to experience Presence when your brain has nothing else to deal with.</blockquote><p>Something else I learned in this experience is how difficult it is to engineer a set of demos targeted at immersion in VR. In this I believe the Oculus team may have had an advantage last year. When I got to they the Crescent Bay prototype at the first Oculus Connect, my sense of immersion was instant and total. But I believe that had as much to do with the experience<br>being completely passive (I just had to hand there), than about any inherent qualities of the hardware I was testing. It’s a lot easier to experience Presence when your brain has nothing else to deal with.</p><p>So to anyone getting the opportunity to demo new VR hardware, either at an event or at a lucky friend’s place, here is my advice: take a breath, look around, and relax. Let it come to you.</p><p>And as far as the Vive goes, well… Shut up and take my money.</p><p><a href="http://twitter.com/augmentl">@augmentl</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=80a0019b076f" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>