<?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[Curvenote - Medium]]></title>
        <description><![CDATA[Curvenote is an interactive scientific writing platform that connects to Jupyter. - Medium]]></description>
        <link>https://medium.com/curvenote?source=rss----ca5f3d19387d---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Curvenote - Medium</title>
            <link>https://medium.com/curvenote?source=rss----ca5f3d19387d---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 19:09:11 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/curvenote" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Version Control for Scientists]]></title>
            <link>https://medium.com/curvenote/version-control-for-scientists-787ceeb0e7c9?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/787ceeb0e7c9</guid>
            <category><![CDATA[science]]></category>
            <category><![CDATA[version-control]]></category>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[collaboration]]></category>
            <category><![CDATA[research]]></category>
            <dc:creator><![CDATA[Steve Purves]]></dc:creator>
            <pubDate>Mon, 20 Dec 2021 19:46:50 GMT</pubDate>
            <atom:updated>2021-12-20T19:46:49.966Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PWm67MEXs8AUGLvMr_h31w.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/@ari_spada?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Ari Spada</a> on <a href="https://unsplash.com/s/photos/reflection?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Version control systems allow people to work iteratively on content, code, and materials with the confidence that their work won’t be lost and that earlier work can be easily revisited and reproduced. These systems also allow advanced collaboration: with distributed teams working on parts of larger systems at the same time and having the confidence that they can “merge” all the changes back together in the future.</p><p>The most advanced and flexible version control systems come from software engineering and decades of development there have resulted in mature, distributed version control systems. <a href="https://git-scm.com/">Git</a> being the most prevalent and <a href="https://github.com/">GitHub</a> being the best known and most widely used platform for hosting git repositories.</p><p>These version control systems were designed for software development workflows. Git was not designed for scientific workflows around exploration, experimentation, writing, teaching, data, attribution, <em>and </em>software<em>.</em></p><blockquote>Scientific exploration and experimentation is different from software development.<br>Writing is different than programming.</blockquote><p>At Curvenote we are exploring version control and collaboration workflows that are designed specifically for the research workflow. We are thinking about what a “unit of content” is for these workflows, how that content is updated, modified and reused in other documents and presentations.</p><h3>The push for git</h3><p>Git is powerful and excellent at supporting software development workflows. As data-based research and software becomes more prevalent across all scientific fields there is mounting pressure for scientists to adopt git as a version control solution in their work. There are many challenges that scientists face when working with git:</p><ul><li>Git is <em>complicated </em>with a steep learning curve: requiring a scientist to learn many abstract concepts often far from their primary field of work.</li><li>Git tracks and represents changes to text files on a line-by-line basis. This works well for code stored as text but doesn’t for many other types of data and content.</li><li>Git doesn’t easily support mixing binary data, structured objects, and content — meaning document structures like Jupyter notebooks or Word files are not well supported.</li><li>The unit of collaboration is the “repository”, which means reuse or collaboration at other levels (e.g. a file or a part of a file) is not well supported, especially across different repositories or teams.</li></ul><p>Successful collaboration with git often requires many steps including pulling local changes, branches, conflict resolution, and “pull requests”. While suitable for software development workflows, this is often cumbersome when working with binary data, using git for writing, making many small fast changes, sharing and reusing components of a repository, or exploring ideas that may never make it into a branch that can be shared.</p><p>‍In the rest of this post, we are going to go through some of the basic concepts we have introduced in Curvenote’s version control system in our online, <a href="http://curvenote.com/">collaborative editor</a> and our <a href="https://curvenote.com/for/jupyter/">Jupyter Chrome Extension</a>.‍</p><h3>Version control for scientists</h3><h4>Blocks</h4><p>Curvenote content is organized in blocks, whether that be a block of text, code, an image, or a Jupyter notebook output. For the moment, we’ll think of blocks of text as you would create in our online editor. If you go to any existing Curvenote article and select a block you’ll be able to see the version history for that block in its entirety. Just like block shown below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*cV98X3dpDcL5PXe1.png" /><figcaption>A single block in the Curvenote editor. While currently showing version 6, all the changes in the block’s history are available and can be examined, accessed or used elsewhere.</figcaption></figure><p>Each version of this block is a complete snapshot of the content at the point in time the content was saved. Versions are saved as whole blocks (rather than changesets), are immutable, and can be stepped back to at any time.</p><p>That’s clear enough, but what happens when we are editing a block and have yet to save a new version? This is where Drafts come in.‍</p><h4>Drafts</h4><p>Let’s take a step back and think about a block the has just been created in the editor first time: v1. That will look something like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*RjiQpYpIR_dnpe7m.png" /><figcaption>The initial draft of a single block in the Curvenote editor. Notice the yellow (which means draft) V1 badge at the top right.</figcaption></figure><p>A new block has been created along with an initial draft. Drafts are updated in real-time and are fully collaborative. That is, multiple users can be editing a draft at the same time and all of their changes are captured and recorded as one big changeset. Drafts are persistent and allow changes to be made over multiple browser sessions, from multiple collaborators.</p><p>As we iterate on our writing, we create drafts and close them each time that we save and all the changes are <em>flattened back into a consistent snapshot</em> and stored in the next version. merging and locking of drafts is some internal terminology that you may see crop up in places. New drafts are always created on top of the latest block.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*KwXWGzpANPUtCl-6.png" /><figcaption>A block starts as a draft, versions are created each time a user saves, and new drafts are created each time a user started the latest version. New drafts are always based on the most recent version.</figcaption></figure><p>‍All of the individual blocks in Curvenote behave in this way and practically all content you see in Curvenote are represented by blocks; text, images, citations as well as Jupyter code and output blocks. Even Articles and Notebooks themselves are blocks.</p><h4>Articles</h4><p>Yes, you read that right! Articles themselves are blocks and subject to the versioning flow as shown above.</p><p>Just to be clear there are two document types:</p><p><em>Articles</em> that you create directly in Curvenote online and <em>Notebooks</em> that you create either by uploading an .ipynb file or saving from Jupyter via the Chrome Extension.</p><p>Articles are containers that group together a collection of other blocks (children) along with additional metadata. We use <em>Articles</em> to create content based on writing, import content and reference various other blocks.</p><p>The children blocks of an article can evolve independently, potentially also changing elsewhere, and are likely to be various different versions, whilst the article itself has its own version history. Articles are like manifests detailing the current versions of their children blocks.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*GtfkTxW8AiuihZ4Y.png" /><figcaption>A schematic of a Curvenote Article — — a container for (order) blocks at specific versions which may or may not be their latest version.</figcaption></figure><p>‍This base data structure makes for a very powerful and flexible way to represent and track documents as we work on them supporting things like selective editing, insertion, removal, reverting, and updating of blocks as well as being able to share and reuse blocks between multiple articles (and notebooks!) and easily keep them up to date.</p><p>As we work collaboratively on Articles, they also have drafts of their own which track child blocks, versions, and drafts as we collaboratively edit. This may seem a little complex but it fits well with how we write in practice: thinking about a paragraph, figure, or an equation as a unit of content.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*rO9LW0mvI312m1AP.png" /><figcaption>A schematic showing the evolution of an Article from Version 1 → Version 2 via a new Article Draft. This is similar to any block draft, the article draft tracks the addition and removal of child blocks, changes to their version, creation of drafts on them, and changes to the metadata on the Article itself.</figcaption></figure><h4>Notebooks</h4><p>In the Curvenote system Notebooks are also containers like an Article but with some key differences.</p><p>Articles are focused on <strong>narrative flow</strong>, rather than <strong>computational flow</strong>. The code-output dependency is something that we relax in Curvenote Articles, allowing you to grab output blocks and use them as figures in your writing without the code.</p><p>This stems from the fact that Notebooks are primarily edited and worked on in Juypter and saved to Curvenote in one action via a chrome extension. Also because of additional rules Jupyter enforces for computational reproducibility, mainly <em>that output cells are always children of code cells</em>.</p><p>When editing a notebook in Curvenote online, for example, to update its metadata and add a thumbnail, change its named URL or add a binder link, or to add or edit markdown blocks — things work pretty much the same as an Article. Whereas code and output cells cannot be edited online.</p><p>When working in Jupyter however, using the Curvenote Chrome Extension you of course have the. ability to fully change and execture the notebook as normal — but there are two important behavioural differences in how versioning works:</p><ul><li>There is no draft — when we save we immediately save a new version of the notebook and blocks.</li><li>It is possible to revert to an earlier version of a notebook, make changes and save a new version — effectively “leap-frogging” changes into a new and most recent version. (This is a little like a rebase in git).</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/0*2SuGmyDQ3pVTK-jy.png" /><figcaption>In the Curvenote chrome extension and because of the ‘offline’ nature of working with notebooks in Jupyter, it’s possible to create a new version of a notebook based off an older version. This is actually handy in some scenarios as it allows you to pull forward changes which may have been overwritten. We’re thinking about how this could feature in our future forking and easy merge model.</figcaption></figure><h4>What’s next</h4><p>Curvenote’s version control system is evolving. In our quest to make accessible and easy-to-use version control for scientists and researchers, we have established versioning around blocks and maintaining links in a graph of connections between blocks, containers, and versions whilst you write, code, compute, share, reuse and create new ideas.</p><p>A lot of the work and learning ahead of us is around how to provide the right mental models, appropriate terminology, and user interfaces.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=787ceeb0e7c9" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/version-control-for-scientists-787ceeb0e7c9">Version Control for Scientists</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Transition to Open Science — an interview with Dr. Jiajia Sun]]></title>
            <link>https://medium.com/curvenote/transition-to-open-science-an-interview-with-dr-jiajia-sun-fbbdd29982cc?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/fbbdd29982cc</guid>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[collaboration]]></category>
            <category><![CDATA[open-science]]></category>
            <category><![CDATA[science-communication]]></category>
            <category><![CDATA[open-education]]></category>
            <dc:creator><![CDATA[Liz Maag-Capriotti]]></dc:creator>
            <pubDate>Wed, 24 Nov 2021 23:04:45 GMT</pubDate>
            <atom:updated>2021-11-24T23:04:45.909Z</atom:updated>
            <content:encoded><![CDATA[<h3>Transition to Open Science — an interview with Dr. Jiajia Sun</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4Hhm5MjkUM5cYzYJx2nanA.jpeg" /><figcaption>Photo by <a href="https://unsplash.com/@graphem?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Guillaume Bourdages</a> on <a href="https://unsplash.com/s/photos/data?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a>.</figcaption></figure><p>Open science is fundamentally changing how scientists and researchers approach scholarly communication and collaboration, from publishing preprints and interactive research results in new formats, to sharing methods, code, or data, and having open research meetings and seminars. At Curvenote we strive to support scientists as they conduct their research, compose and develop their findings, and share ideas with collaborators and the world. There can be many benefits to working more openly, however, this can be both daunting and complex for researchers who are adopting these practices.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/394/1*T0fZEP3rP_5t9Sj472wcSQ.jpeg" /><figcaption><a href="https://sites.google.com/view/jiajiasun/home?authuser=0">Dr. Jiajia Sun</a>, current Assistant Professor of Geophysics at the University of Houston</figcaption></figure><p>To better understand how Curvenote can help in the transition towards open science, we are constantly talking to researchers who have transitioned their own work to practicing more in the open, and understanding what Curvenote can do to help in this transition.</p><p>For this blog, we talked with <a href="https://sites.google.com/view/jiajiasun/home?authuser=0">Dr. Jiajia Sun</a>, current Assistant Professor of Geophysics at the University of Houston, about his experiences with open science, open-source programming, and open-educational resources. Throughout our discussion we learned more about Dr. Sun’s transition into open-science practices, as well as the questions that arise about the benefits, challenges, and tools necessary to practice open science.</p><h3>Open Education</h3><p>Dr. Sun’s introduction to open science started with open-educational materials. In his first semester at the University of Houston, he was asked to create a machine learning course. He knew about machine learning theory, but hadn’t personally implemented all the algorithms. He discovered the book, <a href="https://oreilly.com/library/view/hands-on-machine-learning/9781491962282/">Hands-On Machine Learning with Scikit-Learn and TensorFlow</a> by Aurélien Géron, which included openly available code examples. Modifying these examples, Dr. Sun created a collection of Jupyter notebooks that served as lab exercises for his students. When asked how he has benefited from others sharing their work, he explained:</p><blockquote><em>“I feel like I have benefited so much from the open-source community that I feel morally obligated to give back. I would feel guilty if I don’t. They helped me and I should contribute back.”</em></blockquote><p>True to his word, all of Dr. Sun’s course materials are openly <a href="https://github.com/jiajiasun/UHMachineLearning">available on GitHub</a>. Dr. Sun’s experiences in educational resources, where he had transparent access to methods, data, and previous work to easily build upon, have influenced his passion for open science in many other parts of his team’s research process, specifically around how he uses tools like Jupyter, GitHub, and Curvenote.</p><p>Both Jupyter and GitHub are popular within open-source coding and research communities. Jupyter, built within an open-source community, provides a set of tools for scientific computing that have become one of the go-to resources for teaching and learning scientific programming. GitHub’s platform provides collaborative features around version control in many open-source communities. Curvenote is designed to integrate directly with Jupyter, to maintain an active link between research code and the resulting outputs, even when they appear outside of a Jupyter environment. The collaboration and version control features within Curvenote are built specifically for Jupyter notebooks, overcoming many issues of versioning notebooks in Git. Curvenote presents an approachable alternative to sharing and collaborating on scientific work for those not familiar with code development, or who may find GitHub intimidating.</p><p>Dr. Sun has continued to develop courses with open-source materials including an undergraduate geophysics course on electromagnetics using <a href="https://em.geosci.xyz/index.html">EM GeoSci</a>, which was originally created for the <a href="https://seg.org/Education/Courses/DISC/2017-DISC-Doug-Oldenburg">SEG 2017 Distinguished Instructor Short Course</a> on “Geophysical Electromagnetics: Fundamentals and Applications.” For the lab portion of the course Sun, “used a lot of the [Jupyter] Notebooks that they developed and modified [them] for undergraduates.” He added, gratefully that “the core part, background — the hard part — was taken care of by the <a href="https://simpeg.xyz/">SimPEG</a> community.” Dr. Sun’s EM course materials are also openly <a href="https://github.com/jiajiasun/UHElectromagnetics.git">available on GitHub</a>.</p><h3>Fostering a Community</h3><p>As we continued to discuss education, Dr. Sun mentioned that the field of geoscience is experiencing a steep global decline of student enrollment at the university level (<a href="https://doi.org/10.1038/s43017-021-00216-1">Geoscience on the chopping block, 2021</a>). In relation to open science, many fields of geoscience have been slower to adopt such practices, perhaps in part due to the field’s proprietary past in both the oil &amp; gas and mining industries.</p><p>Dr. Sun remarked, “On the other side, if you look at the machine learning community, [it] has been exploding! One thing that they have is a really good community that are willing to share. If you look at the papers published in top machine learning conferences almost all of them share their code on GitHub so you can immediately follow up, reproduce, and improve upon their work.”</p><p>Open science is an opportunity to get engagement and detailed constructive feedback. By sharing our own contributions we provide resources for fellow scientists, and by allowing others to provide feedback we can help to foster a community. These conversations can lead to collaboration on a global scale, working to move science and discovery forward. Given these ideas, Dr. Sun continued with a call for increased and continued openness in the geosciences with a “mindset of collaboration and sharing.”</p><h3>Accelerate Research</h3><p>This goal of global collaborative science can seem ambitious and daunting to a single researcher, but there are several achievable benefits that open-science practices can provide. Open source helps to accelerate knowledge and discoveries because researchers are no longer required to reinvent or reimplement standard resources. Dr. Sun gave an example of how two of his graduate students are using <a href="https://simpeg.xyz/">SimPEG</a>, an open-source Python package for geophysics, to develop their research code. “SimPEG has tremendously accelerated [their] research since they just use it to implement [their ideas],” he said. “Without SimPEG they would be years behind what they have achieved today.”</p><p>Using such open-source packages gives researchers access to more than previously written code. Open-source code is built within a group of researchers who communicate, collaborate, and contribute. Dr. Sun and his students are not only using SimPEG, but are contributing members of its open-source community. The SimPEG group host <a href="https://curvenote.com/@simpeg/meeting-notes">weekly community meetups</a> to discuss code development and implementation, as well as a <a href="https://curvenote.com/@simpeg/seminars/">monthly seminar series</a> where community members present their ongoing research.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*GUgn3mPTh1QJk490.png" /><figcaption>The SimPEG group shares their <a href="https://curvenote.com/@simpeg/meeting-notes">weekly community meetups</a> and <a href="https://curvenote.com/@simpeg/seminars/">monthly seminar series</a> on their Curvenote team profile.</figcaption></figure><p>SimPEG community members use Curvenote to take meeting notes, collaborate on snippets of code in Jupyter, and share their notes and seminar videos. Their material is available on their public Curvenote <a href="https://curvenote.com/@simpeg">profile</a>. Dr. Sun was glad that he and his students could share their ongoing research projects within the seminar series and hopes that other students, “will be inspired by how we do our research and use open source.”</p><p>Communicating earlier and often throughout the research cycle can provide a variety of benefits, especially to early career researchers. Creating code within an open-source package forces developers to write quality code that others will be able to read, use, and edit in the future. Early career researchers can gain valuable experience, participate in meaningful reviews, and be exposed to new productivity tools and practices within these groups.</p><p>By sharing ongoing research projects beyond a small group of co-authors, researchers receive corrective and instructive feedback that can influence a project’s trajectory and results. Often the feedback provided after journal submission or publication is overlooked as researchers feel that project is complete and have moved on to other subjects.</p><p>The content privacy settings on Curvenote provide opportunities for researchers to share their ideas with the public or with only a select group of collaborators. Dr. Sun gave an example, “My student might want to share with me or the whole SimPEG team. I think that would be a really good thing. First of all it protects the students. You aren’t sharing with the whole world but my student is stepping out of my small group and engaging with more people.”</p><h3>Maximize Impact</h3><p>Dr. Sun and his graduate students have also made an effort to share their data and code along with their publications. “What we do when we first submit our manuscript is to also publish code on an open-source repository like <a href="https://zenodo.org/">Zenodo</a>, so when the reviewers and editors get our manuscript they will immediately have access to our code and they can reproduce our figures.”</p><p>Dr. Sun also mentioned the recent addition of a preprint service to their open-science workflow, “Just a few days ago we submitted a paper to JGR (<em>Journal of Geophysical Research)</em> and they offer a service to transfer your papers to <a href="https://www.essoar.org/">ESSOAr</a> (Earth and Space Science Open Archive).”</p><p>Sharing the additional information along with their publications is a “good way to maximize the impact of your work,” Dr. Sun expressed. This fact was evident when he and his student published a paper in the <em>Journal of Geophysical Research: Solid Earth</em> (<a href="http://dx.doi.org/10.1029/2020JB019675">Nurindrawati &amp; Sun, 2020</a>) in September of 2020 and shared their <a href="https://zenodo.org/record/3931029#.YXrxc9bML0p">data and code</a>, using Zenodo. “In just 4 weeks there were 400 downloads!”, he continued, “If you talk about real impact, this is real impact!”</p><p>As scientists, we often think of the impact of our research in number of citations, but how often do we actually implement, reproduce, or even fully read a scholarly article before we cite it? Sharing the building blocks of our research allows others to better understand, contribute to, and expand the science. We discussed how Curvenote links its writing platform and the Jupyter coding environment and its potential to improve how we conduct and share our open science.</p><p>Dr. Sun commented, “Curvenote can do so many things: version control, [Jupyter] Notebook, text, documentation, image creation. It has almost all the features that researches would need to develop, document, communicate and collaborate on their projects and all these features are integrated into one unified framework.”</p><h3>Challenges or Limitations?</h3><p>Even with a long list of benefits, there was still the question of challenges or limitations of open science. Is it possible to still contribute or make use of open-source materials when working within exclusive research contracts?</p><p>“There are certain situations where you can’t do open source because of an agreement or contract,” Dr. Sun said. He added that he was fortunate to not currently be limited by these constraints, and even with industry sponsored projects there are ways to contribute back to open projects. “All the work is done in an open-source framework; it’s just that we can’t publish our results.”</p><p>A commonly debated disadvantage to open science is the idea of being “scooped.” When asked about these concerns, Dr. Sun said, “different people have different interests, focuses, hypotheses, tests and questions they want to answer” and a research project is much more than a single idea or method. He explained, “you can scoop my method but are you going to focus on the same study area, and try to answer the same geological questions that I am interested in? Probably not.”</p><p>Open science changes the cadence in which researchers openly collaborate. New forms of sharing such as Curvenote, GitHub, and Zenodo, and publishing such as preprints and digital archives, allow registration and comprehension of methods or ideas much earlier in a research cycle. All of science is based on the evolution and adaptation of ideas, sharing earlier and more transparently can increase impact.</p><h3>Open Future</h3><p>After our discussion it’s easy to understand how Dr. Sun can be so passionate and enthusiastic about the open-science, open-source, and open-education practices and communities. Sharing information earlier and often throughout the research process accelerates the discoveries and conclusions we are able to make collectively. By getting feedback sooner, we can implement these ideas, improve our skills as researchers and expand the impact of our work.</p><p>When early career researchers participate in open science they learn valuable skills and practices that can only serve to benefit them throughout their career. In regards to promoting open-science among his students, Dr. Sun commented, “these skills are transferable and especially helpful for those students who end up working in a non-geoscience-related industry. Quite a few of my students are now data scientists instead of geoscientists. The skills mentioned above are currently not in the curriculum [but] will serve them well even if they want to switch their career.”</p><p>A variety of tools exist to conduct open science. Zenodo makes it possible to link a publication to shared code and data. GitHub serves as a repository for open-source coding packages and freely available datasets. When publishing papers, open-access journals and preprint services, such as <a href="https://arxiv.org/">arXiv</a>, allow readers earlier access to ideas.</p><p>As the open-science movement continues to grow, Curvenote is being designed to integrate and expand on these tools to serve researchers throughout their workflows: promoting reproducibility and open science. Today, researchers can <a href="https://curvenote.com/for/jupyter/">version control Jupyter Notebooks</a> and integrate directly with <a href="https://curvenote.com/for/writing/">collaborative tools for technical writing</a>. Results and findings remain linked and reproducible, all of which can remain private, be shared publicly on Curvenote, or exported to preprint services. By supporting reproducibility and allowing granular controls on privacy throughout the research process, we aim to support scientists and researchers as they accelerate and share their discoveries — no matter where they are on their open-science journeys.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=fbbdd29982cc" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/transition-to-open-science-an-interview-with-dr-jiajia-sun-fbbdd29982cc">Transition to Open Science — an interview with Dr. Jiajia Sun</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Data-driven LaTeX templates]]></title>
            <link>https://medium.com/curvenote/data-driven-latex-templates-afd07aedaab6?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/afd07aedaab6</guid>
            <category><![CDATA[science-communication]]></category>
            <category><![CDATA[latex]]></category>
            <category><![CDATA[open-source]]></category>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[publishing]]></category>
            <dc:creator><![CDATA[Steve Purves]]></dc:creator>
            <pubDate>Wed, 10 Nov 2021 22:20:11 GMT</pubDate>
            <atom:updated>2021-11-10T22:46:01.012Z</atom:updated>
            <content:encoded><![CDATA[<p><a href="https://github.com/curvenote/jtex">jtex</a> — an open-source library for creating LaTeX documents with templates and data</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*TauE6rCbwCy3o9794VgFHA.jpeg" /></figure><p>As a scientific author today you pick your template <em>before</em> you start writing: what journal, what thesis template, what conference. If your work gets rejected, needs to be submitted somewhere else, or you want to share in another medium like a blog or presentation — these initial choices hold you back and it takes time and effort to migrate your work. At Curvenote we are flipping this idea: <em>pick your template last</em>!</p><p>We believe in sharing science in different mediums and formats to improve accessibility — in blogs, papers, thesis, presentations, and interactive websites. To do this, you need exacting control over a templating engine that is data-driven and structured, and you need a writing tool that helps you structure your content such that it can be reused in multiple ways. At Curvenote, this is core to what we do.</p><p>Our collaborative editor sits atop a modern translation system so you can access your content in any format and also have fine-grained control over the final presentation. To create scientific PDFs we are releasing a new LaTeX <a href="https://github.com/curvenote/jtex">templating system</a> called <a href="https://github.com/curvenote/jtex">jtex</a> and are curating an <a href="https://github.com/curvenote/templates">open-template repository</a> that currently covers over 350 journals in a standardized, data-driven way. We built these tools to address the variability and problems that we have encountered in translating and presenting scientific content in many different templates and formats over the past few years.</p><p>We released <a href="https://github.com/curvenote/jtex">jtex</a> under a permissive open-source license (MIT) allowing anyone to create their own templates using a customized <a href="https://jinja.palletsprojects.com/en/3.0.x/">Jinja2</a> renderer in Python. In this article, we will walk through the library and our goals, compare and contrast with the Pandoc ecosystem, and give you enough context to get started using <a href="https://github.com/curvenote/jtex">jtex</a>.</p><h3>LaTeX</h3><p>LaTeX is a powerful, beautiful, and precise typesetting system that lets you design and create rich professional papers, reports, and documents. In reality, though, you’re more likely to be using LaTeX to fit your writing, equations, figures, and results within someone else’s typesetting design — like from a journal or university.</p><p>LaTeX is a huge ecosystem, with many contributing packages, and multiple ways to solve any particular formatting requirement. So naturally, we see a lot of variation in the templates that people are expected to use, from university to university or from journal to journal. This means even if you are comfortable with LaTeX, a particular template could still send you down an unfamiliar formatting rabbit hole.</p><p>Generally, templates are provided in a few different ways:</p><ul><li>Skeleton .tex files with layout and placeholder content interleaved where you’re expected to strip out the placeholder content and insert your own as you go.</li><li>Style .sty files that can be loaded as packages to alter and introduce environments and commands within one of the standard LaTeX document classes.</li><li>Class .cls files that define a whole document class to work within</li></ul><p>Beyond that, the template, in whichever of these base forms, can use any selection of packages they choose, can rewrite LaTeX commands and environments, and take completely different approaches to provide particular features, like; corresponding author information, citation and bibliography styles, and source code rendering.</p><p>Larger institutions and organizations that lean heavily on LaTeX also create templates with many configuration options. A single LaTeX template can actually serve 10’s or 100’s of different end publications with different flavors of an overall style. For example, the <a href="https://curvenote.com/templates/mdpi">MDPI template</a> which we recently ported to Curvenote can target over 300 different MDPI publications with different options depending on each choice!</p><p>All this means significant learning curves and overhead for researchers working in LaTeX, especially if they want to publish in more than one place. Learn LaTeX, then learn the template, packages, and quirks of the template.</p><p>Creating data-driven LaTeX templates means this overhead is encountered once, when creating the template or adapting an existing one, and once complete many different LaTeX documents can be produced by “rendering” that template with different data.</p><h3>Pandoc</h3><p>One of the first technologies to look at when thinking about moving a written document between different formats is the <a href="https://pandoc.org/">Pandoc</a> project.</p><p>Pandoc is a universal document converter capable of high-quality conversions to, from, and between over 48 different document formats. Beyond just text conversion it understands media, directives, and metadata and is able to preserve/translate these during conversion. Its capabilities are quite awe-inspiring and it’s increasingly used by writers who want a minimalist writing experience in Markdown to target the formats that they need.</p><h3>Pandoc templates</h3><p>Pandoc comes with a <a href="https://pandoc.org/MANUAL.html#templates">built-in templating feature</a>, which is powerful and links to Pandoc’s underlying data structures.</p><p>Pandoc’s <a href="https://pandoc.org/MANUAL.html#template-syntax">templating syntax</a> is very close to the <a href="https://jinja.palletsprojects.com/en/3.0.x/">Jinja</a> style that we have embraced in <a href="https://curvenote.com/templates">Curvenote LaTeX templates</a>, with variable interpolation, control flow, partial templates, and filters all available with specializations for different output formats.</p><p>For LaTeX, Pandoc provides a <a href="https://github.com/jgm/pandoc-templates/blob/master/default.latex">complete default template</a> that allows the rendering of a document with metadata and content. The default template is complete but complex, and as a reference point for users to make their own templates, this can be pretty overwhelming.</p><p>Pandoc is of course set up for document conversion, so the starting point for rendering a document is a complete document in another format. For example, a Markdown document, when provided alongside a yaml file, containing document metadata, will render a document against the default or a custom template. Pandoc does an exceptional job at this conversion task.</p><h3>Why not Pandoc?</h3><p>So why not just use Pandoc to power exporting to LaTeX in Curvenote?</p><p>Well, we did consider this — but decided that our end goal was different to that of Pandoc’s. While Pandoc is about document conversion, Curvenote’s goal with LaTeX is to provide the means to support many different types of existing LaTeX templates with a single templating system.</p><p>We need to be able to interface with people’s templates and while that might be perfectly possible with Pandoc, some of the things we value as part of that are:</p><ul><li>An easy to read syntax that stands out against LaTeX</li><li>Compact templates where template creators do not have to explicitly include boilerplate code to support complex environments and schemas</li><li>The ability to manipulate content flow and render specific content differently on a per template basis</li><li>Flexibility to easily add opinionated behaviors to the engine to specifically support Curvenote’s needs</li><li>Python level transformations so we don’t have to rely solely on LaTeX commands/environments in our implementation</li></ul><p><em>Note: We are planning on integrating Pandoc for some of the other conversions we want to provide. Specifically, we plan to support export to </em><a href="https://pandoc.org/MANUAL.html#pandocs-markdown"><em>Pandoc’s extended flavor of Markdown</em></a><em> which will provide an excellent way for people to both archives their Curvenote projects and articles and to hook Curvenote into their own Pandoc driven content and publishing pipelines.</em></p><h3>Curvenote LaTeX Templates</h3><p>Having stated our aims above, let’s talk about our implementation. There are a few different components to talk about here:</p><ul><li><a href="https://pypi.org/project/jtex/">jtex</a> — a lightweight templating engine that provides a simple command line interface (CLI)</li><li><a href="https://github.com/curvenote/templates">Curvenote’s Open Template Repository</a> — a collection of templates ported to use in Curvenote or through these open-source command line tools</li><li><a href="https://github.com/curvenote/curvenotepy">curvenotepy</a> — a python client library and CLI that can pull content from the Curvenote API</li></ul><p>We’re going to focus on the first two in this post.</p><h3>Curvenote template</h3><p>In our templating CLI jtex, we’ve implemented a modified Jinja environment to provide a clear syntax that stands out well against LaTeX content and markup. The basic markup structure comprises Statements, Expressions and Comments as follows:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/927/1*MZFqUkQivg_6J2kOO5fJBQ.png" /><figcaption>Curvenote’s LaTeX template syntax alongside the standard Jinja markup</figcaption></figure><p>This syntax works nicely resulting in templates that look like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/799/0*upylS7AicezUDpPf" /></figure><p>If you are not familiar with how Jinja templates are constructed their <a href="https://jinja.palletsprojects.com/en/3.0.x/templates/">template designer documentation</a> is excellent and worth a read. Between the <a href="https://jinja.palletsprojects.com/en/3.0.x/templates/">Jinja docs</a> and our <a href="https://github.com/curvenote/jtex#readme">README</a> there is plenty of detailed information on how to construct templates. So we’ll only touch on some of the main points here.</p><ul><li><strong>Nested data structure</strong> — You’ll notice in expressions (e.g. line 13 in the figure above), we are able to expand variables like so, [-doc.title-]. When we pass data to jtex in the form of a dict, we can have multiple levels of nesting and access data fields using dot or square brackets operators, e.g. [-doc[&#39;title&#39;]-].</li><li><strong>Insert control flow statements</strong> — [# if options.a #] Some LaTeX [# endif #] While this is clear, we also have access to the complete Python-like Jinja environment between the [#, #] so you can do things like set persistent variables that remain available elsewhere is the template.</li><li><a href="https://jinja.palletsprojects.com/en/3.0.x/templates/#filters"><strong>Jinja filters</strong></a> — These filters allow typical functional programming style manipulation of data, e.g. line 15, where we expand the list of authors</li><li><strong>Python builtins</strong> — The module has also been added to the environment, which provides access to other <a href="https://docs.python.org/3/library/functions.html#built-in-funcs">common functions</a> like zip.</li><li><strong>Specialized variables</strong> — [-CONTENT-] is a special variable like Pandoc’s body tag that allows insertion of the main body of content into a template.</li></ul><p>We’ve also made some other LaTeX friendly modifications to the Jinja environment that you can read about <a href="https://github.com/curvenote/curvenote-template#other-environment-differences">here</a>.</p><p>Given our ability to create templates, how does the CLI work? There are two modes of operation: build-lite and build.</p><h3>Command: build-lite</h3><p>This is a lightweight un-opinionated command that will allow you to render a LaTeX document against any free-form template that you come up with. You will need a .yml file with your corresponding data structure (let’s call it a DocModel, short for document model) and a .tex file with your main body content.</p><p>In this way, using jtex is similar to a Pandoc template, except that it is free form. Other than the [-CONTENT-] variable there are no other built in variables or metadata. As you craft a template, you define the DocModel as you go and the CLI will render anything you define.</p><h4>Example</h4><p>Given these three files:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/941/1*Ydnf4YRzrY1e9RgRxsYX-Q.png" /></figure><p>and by calling:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/940/1*HQ-BePFDUv_BS5brXWyJ0w.png" /></figure><p>We will render the following LaTeX document:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/941/1*zPq7y3FR9dRMcv_Ax049ng.png" /></figure><p>which when compiled to PDF gives us:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/744/0*tQQg9Z0ff1QUEh5A" /></figure><p>This is a simple example but what is useful here is the fact that we have a completely free-form templating process that can easily be adapted to suit a particular workflow. To get started with templates using build-lite <a href="https://github.com/curvenote/jtex#build-lite">check the readme</a> for more info. In the future, we will also show how this can be used with Pandoc for document conversion, and then last-mile style choices being templated with jtex.</p><h3>Command: build</h3><p>The build command uses a standardized YAML format that we have developed in looking at many different LaTeX templates, this is the format outlined in our <a href="https://github.com/curvenote/templates">open template collection</a>. The structure of the document model used here is prescriptive but configurable via three configuration mechanisms; schema, tagged content and template options — more on this in the next section.</p><p>Templates can be pulled directly from the Curvenote API or from a local folder. This makes it possible to test templates that are in development or being ported to this standardized format.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/938/1*ChnIE0CJwHA0z8mfbp8Aug.png" /></figure><p>The command line itself is very similar to the build-lite command except that we now deal with input (content) and output folders, rather than single files. This allow us to pull together various files including images, a .bib file and various template files, into a consistent package.</p><p>The CONTENT_PATH argument should point to a directory containing the following files:</p><ul><li>data.yml - a yaml file containing the data in line with the expected document model</li><li>main.tex - containing the main content to be rendered at [-CONTENT-]</li><li>main.bib - a bibliography file if needed</li></ul><p>These files will be used to render a LaTeX document at the OUTPUT_PATH with either the built-in default template or any other template specified using the --template-path or --template-name options. --template-path uses a local template, while --template-name will fetch from the Curvenote API (e.g. here is <a href="https://api.curvenote.com/templates/agu2019">AGU2019 template</a>).</p><p>Find out more about the build command <a href="https://github.com/curvenote/curvenote-template#build">in the readme</a>.</p><h3>Curvenote LaTeX Templates</h3><p>Our aim here is to be able to take any existing LaTeX template, make it data-driven and available as an export option directly within Curvenote. In addition to the template markup that we have already talked about, templates have a simple but expected structure and a configuration file.</p><p>Let’s use the simplest template we have, <a href="https://github.com/curvenote/templates/tree/main/latex/plain_latex">plain_latex</a>, as a minimal example. This template provides minimally styled LaTeX and PDF output. It’s <a href="https://github.com/curvenote/templates/tree/main/latex/plain_latex">template folder</a> looks like:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/922/1*7lEV1ec-ns7oj5bNjTeuDQ.png" /></figure><h4>Main Template File (template.tex)</h4><p>This is where the template content, custom commands/environments are defined and pulled together using the template markup. We’ve covered a lot of this in examples above but one additional feature to note is the \input{curvenote.def} command.</p><p>This command is included at the start of each template and pulls in a curvenote.def file that is generated during the rendering process. That file contains commands to include packages, setup options - and if needed custom LaTeX commands, and environments if needed to interface between Curvenote’s schema and those in use in the template. The content of that file is influenced by the “schema” section in the configuration file.</p><h4>Configuration (template.yml)</h4><p>The configuration is a simple yaml file with a metadata and a config section, laid out and validated against the schemas defined <a href="https://github.com/curvenote/jtex/blob/main/jtex/schema/template.schema.yml">here</a> and <a href="https://github.com/curvenote/jtex/blob/main/jtex/schema/config.schema.yml">here</a>.</p><h4>Metadata</h4><p>The metadata section defines the template and is largely informational, providing key details about licensing, originators and social-media usernames.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/699/0*o3_WCYOOHjbpWFMW" /></figure><p>The config section splits into four subsections: build, schema, tagged, options.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/888/0*xhPvU-qmbMXaz74-" /></figure><h4>config.build</h4><p>Commands in this section influence the output structure of the LaTeX document.</p><ul><li><strong>layout</strong> — compact and book options will be supported with a single file option in the near future.</li><li><strong>vanilla</strong> — When true, this instructs the curvnotepy Python client to request content in vanilla TeX from the Curenote API rather than TeX content that uses Curvenote’s custom environments. It will also prevent custom environment definitions from being added to curvenote.def.</li></ul><h4>config.schema</h4><p>The schema section is used to configure how Curvenote’s LaTeX output should be represented in the template LaTeX. Individual schema options allow template creators to specify how these elements should be handled on a case by case basis.</p><p>Take the Curvenote<em> callout</em> as an example.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/707/1*OPjPHgfrkG7Cq3rHy-vOSw.png" /></figure><p>However, when we translate this to a template it may have no direct equivalent — so how should we handle it? In this case, provided vanilla is false, the callout will be represented by the following LaTeX when the API returns that content.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/704/1*T7DMJg3rHAstceUejBVA6w.png" /></figure><p>In the schema section, we can add a callout key with one of the following values to tell the renderer how this should be handled:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/679/1*7JotBIy8RBYzt7-rYIyv1A.png" /></figure><p>There are a number of options right now, some multi-valued like callout, while other are booleans and used to control other LaTeX behaviours. Here’s the current list: aside, callout, code, raggedbottom, sloppy, hidelinks, natbib, bibstyle, citestyle.</p><p>This is an area which we expect to expand further as we include more templates into the repository. These will include templates for papers, reports, articles, theses, books, posters, and more. We expect to have to deal with a fair amount of variation. Watch out for more documentation on using these in our <a href="https://github.com/curvenote/templates">open template repository</a>.</p><h4>config.tagged</h4><p>Tagged content is a mechanism through which we can reroute the main content flow.</p><p>When a Curvenote article is rendered the main body of content will be inserted into the document at the [-CONTENT-] statement. The exception to that are any blocks of content that have been tagged in Curvenote with a tag listed in the tagged section of the config.</p><p>That content will be pulled from the flow and made available to the template in a variable. For example, the abstract tagged content below will be available in the variable tagged.abstract in the template at render time.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*v88mC3FZGoMAMMsv" /></figure><p>The configuration for the tagged content allows for a description and a word count (character count coming soon!) which will be shown and used in the Curvenote API. This allows very specific guidance about a particular template’s requirements. A piece of tagged content can also be marked as required.</p><p>Then the template can place the abstract content exactly where it’s needed with a snippet like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/703/1*7prfRaOcUlstuupHta9EAQ.png" /></figure><p>This allows a template creator to expose features to the end user in Curvenote with helpful descriptions, and if required, enforcing that the tagged content must be available in order to use the template. Tagged blocks will appear to the user like so:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*StKAA-Y0NK3eutVY" /></figure><h4>config.options</h4><p>Similar to tagged content, a template can define a number of options that should be exposed to an end user. These “options” can be used to request additional data like corresponding author information or prompt to set template options like draft, document type, paper size etc. The plain_latex template specifies two options both of type bool.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*5HMrmZTIOJIr0SMN" /></figure><p>Options are specified with a unique ID and description. Options can also be required or left as optional and the Curvenote UI will enforce that rule. In addition to booleans, options can be of type: str, choice, keywords, corresponding_author.</p><p>Here is an additional example, of how the <a href="https://github.com/curvenote/templates/blob/main/latex/agu2019/template.yml">AGU2019</a> template specifies two of these fields to set the journal name and request information on one or more corresponding authors.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/668/0*LD_-Scap0xWRslhh" /></figure><h4>Document Model</h4><p>We saw when using the jtex build-lite command above that the renderer receives a dict like structure that is access from the templates. When using jtex build the structure of that dict is no longer free form and instead should contain data corresponding to both built-in fields and the options and their tagged content blocks specified in the configuration. The data structure is required in this form in order for a given template to render properly.</p><p>An example of a document model for the plain_latex template <a href="https://github.com/curvenote/templates/blob/main/latex/plain_latex/example/data.yml">is here</a> and also shown below.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/899/0*0A0o8Ihp5w9WDbz6" /></figure><p>At the root level there are doc, tagged and options sections where the latter two correspond to the respective configuration sections. The doc section is set by Curvenote and provides key data fields related to the article itself including the title, authors list and date.</p><p>When developing Curvenote templates we can stub out the document model in a yaml file and use them with jtex build to test our template as we go.</p><h3>Create a data-driven template</h3><p>Is there a template that you need to use that is not yet available?</p><ul><li><a href="https://github.com/curvenote/templates/issues">Open an GitHub issue</a> — leave us a link to the template source and we’ll port the template for you!</li><li><a href="https://github.com/curvenote/templates/pulls">Open a Pull Request</a> — if you have a template that you want to port, we’re happy to review and accept contributions. We can also help you get a PR over the line if you’ve made a start!</li></ul><p>We’re building our LaTeX templating system to access any template you need, while writing in an editor that allows you to focus on your work with the confidence that you can export to any format.</p><p>Cover image by <a href="https://unsplash.com/@brunus?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Bruno Martins</a> on <a href="https://unsplash.com/s/photos/printing?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=afd07aedaab6" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/data-driven-latex-templates-afd07aedaab6">Data-driven LaTeX templates</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Curvenote Microsoft Word Export]]></title>
            <link>https://medium.com/curvenote/curvenote-microsoft-word-export-9dc4ba207e3c?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/9dc4ba207e3c</guid>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[ms-word]]></category>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[thesis]]></category>
            <category><![CDATA[scientific-writing]]></category>
            <dc:creator><![CDATA[Steve Purves]]></dc:creator>
            <pubDate>Thu, 21 Oct 2021 20:47:29 GMT</pubDate>
            <atom:updated>2021-10-21T20:47:28.895Z</atom:updated>
            <content:encoded><![CDATA[<p>From Curvenote’s collaborative editor format to docx in two clicks</p><h3>Word or LaTeX</h3><p>Microsoft Word (docx) or LaTeX is a question that is debated daily in both academic circles and <a href="https://twitter.com/search?q=%23AcademicTwitter">#AcademicTwitter</a>. There are proponents of both schools with various arguments either way — from control and precision to ease of use and shallow learning curves.</p><p>Ongoing debate aside, both Word and LaTeX represent the vast majority of formats accepted (or required) for conferences, workshops, and journal or thesis submissions at universities and major academic and professional institutions.</p><p>But really your writing and work should be independent of these formats. You should be able to write in an editor made for technical and scientific content, that’s a pleasure to use, and be able to move your writing to any format you need to — when you need to — and that is what we are really interested in at <a href="https://curvenote.com/">Curvenote</a>. In addition to our <a href="https://curvenote.dev/">editor</a>, we are building infrastructure to power that interchange, and the docx format is our latest export endpoint.</p><h3>Export to Word (docx)</h3><p>Word’s docx format can support many of the features that we include in Curvenote articles - figures, tables, captions, citations, references, internal references, hyperlinks, and so on. Our objective is to give you a copy of your article with all these features enabled in the docx file you download.</p><p>We are almost there but there are still a couple of things to add (e.g. figure captions) and others to improve (e.g. citations). We’ve released the Word export feature today in beta while we make those improvements and gather feedback.</p><p>We’ve extended our export UI, smartening things up in the process, so export to docx is currently just a single click.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Yn068KvHq8rL13so" /><figcaption>Export your paper or report to MS Word’s docx format in a single click</figcaption></figure><p>Export as many times as you like, as you create updated versions of your manuscript. You can export to multiple formats at the same time and the process is fast and easy!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*6UAwCboB87l65BqZ" /><figcaption>Any Curvenote article can be exported to multiple formats and once generated files are available for immediate download</figcaption></figure><h3>Open source at heart</h3><p>In developing this feature, we put together a new library that translates between the docx format and our internal data representation via the Prosemirror editor. We’ve <a href="https://github.com/curvenote/prosemirror-docx">released this library with an open-source license</a> as it has great capability to feed back into the Prosemirror community - a core technology that we of use a good deal of and want to help extend.</p><h3>Publishing or sharing online</h3><p>Exporting from Curvenote means that you are generating a hard copy, which is often for submission elsewhere. However, Curvenote also allows you to publish projects, papers and reports online so others can access them via a link you share or via your profile.</p><p>In those cases, when your article is public or published, files you generate will also be available to your readers to download and consume.</p><p>Publishing online and/or sharing privately with collaborators can be a faster way to get feedback and comments on your report to paper. By commenting in Curvenote they’d be leaving feedback right alongside your writing, making it easier to integrate and iterate. And ok, if your collaborators <em>really</em> want a Word file to read offline, or a PDF to print and read with their coffee, they can download it directly too.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dcPttv-YBu68V0Ue" /><figcaption>Generated files are available to your readers on published or public articles</figcaption></figure><h3>Give it a try</h3><p>If you would like to try out <a href="https://curvenote.com/for/writing">Curvenote for writing</a>, sign up for a free account. You can keep up with our feature releases and share your feedback in our <a href="http://slack.curvenote.dev/">Community Slack</a>. We would love to hear about how you use Word in your writing projects and any templates that you need to work to or submit within!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9dc4ba207e3c" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/curvenote-microsoft-word-export-9dc4ba207e3c">Curvenote Microsoft Word Export</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to export to PDF & LaTeX using Curvenote]]></title>
            <link>https://medium.com/curvenote/how-to-export-to-pdf-latex-using-curvenote-89c56a0b049b?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/89c56a0b049b</guid>
            <category><![CDATA[scientific-research]]></category>
            <category><![CDATA[academic-publishing]]></category>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[preprints]]></category>
            <category><![CDATA[phd]]></category>
            <dc:creator><![CDATA[Steve Purves]]></dc:creator>
            <pubDate>Tue, 12 Oct 2021 21:59:33 GMT</pubDate>
            <atom:updated>2021-10-12T22:16:26.000Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4uopW-y0YhVjbM3rDT3MBg.jpeg" /><figcaption>Image by <a href="https://unsplash.com/@carrier_lost?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Ian Taylor</a> on <a href="https://unsplash.com/s/photos/shipping-containers?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a></figcaption></figure><p>Writing up research for submission to a particular conference, journal, or preprint service is a major task. Researchers need to prepare their hypothesis, methods, data, results, and conclusions to best represent their research, its outcome, and impacts. On top of this, they need to deal with the formatting and layout requirements of the organization where they are publishing that work. The task of formatting and layout is not a core part of research work yet it can be a major effort and time sink because of factors like strict requirements, uncooperative tools, or additional learning curves — like having to learn LaTeX while <em>writing in the context of a specific template</em>.</p><p>Formatting and finalizing a publication should be easy and <a href="https://curvenote.com/why">Curvenote</a> aims to be a writing environment where researchers can move from their day-to-day notes, notebooks, and reports into their manuscripts with a minimum of rework. Curvenote lets you <a href="https://curvenote.com/for/writing">write a manuscript</a>, share it and gather feedback and then export it to multiple different formats. From conference abstract to a preprint through to a journal article, Curvenote aims to let you export your work to the formats you need as your research evolves.</p><h3>Open source LaTeX templates</h3><p>LaTeX, PDF, and Microsoft Word documents represent the predominant formats for the submission of academic work. Curvenote allows you to export to LaTeX and PDF based on a specific LaTeX template (we are <a href="https://twitter.com/stevejpurves/status/1442568085156728841">working on Microsoft Word</a> currently!). We started with LaTeX and PDF, as typically journal articles, preprint services, and universities provide templates to ensure that submissions are correctly laid out and meet their requirements.</p><p>Still, working with a template, especially larger templates with many features can be onerous. At Curvenote we’ve done two things:</p><ol><li>Our export engine is based on <a href="https://github.com/curvenote/curvenote-template">a templating system</a> that allows us to load various templates and provide a user interface to configure them. We’ll cover this a more detail in the rest of this post.</li><li>To be able to accept and integrate a large number of templates, we have created an <a href="https://github.com/curvenote/templates">open template repository</a> where template specifics and our modifications can be easily read and where we can accept both requests and contributions from others.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*F9B2JhU2xYuevGd096eR7A.png" /><figcaption>Curvenote open-source LaTeX templates available on GitHub</figcaption></figure><p>If you are writing or planning to start a paper, report, or thesis and want to do your writing in Curvenote — you can <a href="https://github.com/curvenote/templates/issues">open an issue</a> or <a href="https://github.com/curvenote/templates/pulls">pull request</a> on this repo and we will make sure your template gets integrated.</p><h3>Export to PDF or LaTeX</h3><p>Once templates are tested and accepted in <a href="https://github.com/curvenote/templates">the repository,</a> they are <a href="https://curvenote.com/templates">available for export</a> and appear directly in the Curvenote when you click “Export As” on an article.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1fp-WM60tp9xlgu65-h7KA.png" /><figcaption>Choose a journal or thesis template to export to and which format to target.</figcaption></figure><p>Both PDF and LaTeX options use the same template, but the latter will create a .zip file containing a LaTeX <em>“project”</em> — a folder containing a main.tex and main.bib file as well as definition files and image assets. This enables you to customize and build locally, should you want to.</p><p>But that is not our goal!</p><p>We want to be able to export submission-ready PDF documents directly from Curvenote — to avoid building LaTeX locally at all. We’ve made this possible through <em>Template Options</em> and <em>Tagged Blocks</em>. Setup on a per template basis, these allow you to provide additional information and any specific content required via the user interface during export.</p><h3>Template Options</h3><p>Once you’ve selected a template, the next screen you are shown is a dynamic form showing the options for that template. When integrating the template we look at the author guidelines, nominating required and optional items appropriately — so you’ll need to meet the required options before you can export.</p><p>Here’s an example of options for the <a href="https://curvenote.com/templates/agu2019">AGU 2019 template</a> with two required and one optional field.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6l4L2OOELbyqFuAz2mlCgw.gif" /><figcaption>Curvenote’s option UI is driven from the template specifications included in our open template repository</figcaption></figure><p>We are able to proceed once we’ve entered the required information. This template has relatively few options — other templates have more and/or conditional options that only appear based on the value of certain fields, a typical case being additional options for different journals based on the <em>Journal Name</em> you select.</p><p>Beyond template options, that are appropriate for setting metadata, additional author information, or switching on/off certain template features and styles. Templates also often require specific content from the user that is handled differently in the typesetting process — a well-known example would be the <em>Abstract</em> for a paper.</p><p>In an abstract, we are dealing with more than a line of text or a link. We usually have a paragraph or two of content that may contain maths and symbols but that is also fundamentally part of the document rather than metadata. Since Curvenote also gives you an easy way to publish an interactive online version of your paper, it makes total sense to keep content like the abstract within the document.</p><p>We’ve achieved this through the use of the <em>tags</em> that are available on any block in Curvenote — let’s see how this works. After entering the template options, you move onto the following screen.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AgQmwLXPk37iim_I-hj_Qw.png" /><figcaption>This screen provides an overview of the tagged content this template needs and tells us where required content is missing</figcaption></figure><p>This is essentially a summary of the special content requirements of this template along with flags on whether they have been met or not. When integrating templates, we include as much information from the original author guidelines as possible, as show that information here.</p><p>In the <a href="https://curvenote.com/templates/agu2019">AGU 2019 template</a> example, we can set content for an <em>Abstract</em>, <em>Plain Language Summary,</em> and <em>Acknowledgments</em>. Furthermore, an <em>Abstract</em> is required and in this case, we’ve not provided one.</p><p>To fix this we head back to our manuscript, select the block containing our abstract, and set the tag appropriately.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mFt2_jshS0c_TEFdW9-v5w.gif" /><figcaption>tags can be added to any block, article or notebook in Curvenote via the Block Setting dialog</figcaption></figure><p>Tags can be set to any string we like, in the UI we suggest some of the common tags you’ll find in templates, but any tag you need can be added. (Note that the word Abstract appears as a decoration on the block, that’s a special case as we are still deciding how to best show the block tags while keeping the page uncluttered).</p><p>Now when we head back to export, we can see we’ve provided our abstract and can proceed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fWObmJobK0-AcrbiGKxG2A.png" /><figcaption>Now that the abstract tag was set, we can proceed</figcaption></figure><p>We can of course provide information in any of the optional fields too, and this will be added appropriately, by the template.</p><h3>Write once, export to any format</h3><p>We’ve built our export process to take away the pain from the submission process. We want Curvenote to help its users focus on science and writing while taking care of the formatting and packaging concerns of your paper, report, or thesis.</p><p>This is something we’ll be perfecting over time, but by making our templates configurable like this, we are now able to get people to submission-ready PDFs without having to dive into a LaTeX build — which we think is a solid step forward.</p><p>The philosophy behind Curvenote is to support your day-to-day work in one place and make it easy to reuse your writing, notebooks, figures, and plots across documents, presentations, and papers. This saves you time and effort and keeps you focussed on your research.</p><p>When it comes to writing your paper, you can easily move one manuscript forward and export that one piece of content to multiple formats for your internal group review, preprint service submission, and ultimately conference or journal submission. At the same time, you can easily share supporting work online <a href="https://curvenote.com/@curvenote/getting-started/collaboration">securely with collaborators</a> or publicly and attach it to your <a href="https://curvenote.com/@curvenote/getting-started/your-profile">Curvenote profile</a>.</p><h3>Want to change your writing experience?</h3><p><a href="https://curvenote.com/signup">Try out Curvenote</a> and tell us about which conference or journal paper that you are aiming for — we’ll add the template for you. If you are writing your thesis we can also help, we can get you started now and we will commit to adding your university thesis template in time for your submission. <a href="https://curvenote.com/demo">Book a demo with us to find out more.</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=89c56a0b049b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/how-to-export-to-pdf-latex-using-curvenote-89c56a0b049b">How to export to PDF &amp; LaTeX using Curvenote</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Research Workflows]]></title>
            <link>https://medium.com/curvenote/research-workflows-2cbd9f4f56db?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/2cbd9f4f56db</guid>
            <category><![CDATA[research]]></category>
            <category><![CDATA[education-technology]]></category>
            <category><![CDATA[collaboration]]></category>
            <category><![CDATA[jupyter-notebook]]></category>
            <category><![CDATA[academic-writing]]></category>
            <dc:creator><![CDATA[Liz Maag-Capriotti]]></dc:creator>
            <pubDate>Thu, 07 Oct 2021 18:00:06 GMT</pubDate>
            <atom:updated>2021-10-07T18:00:06.701Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*9HUUQKbnmdtIwf6Ir5XztQ.jpeg" /><figcaption><a href="https://curvenote.com/@lheagy">Dr. Lindsey Heagy</a>, assistant professor in Earth data science at the University of British Columbia and science advisor for Curvenote.</figcaption></figure><p>If you’re a scientist or researcher, you’ll often find yourself in a variety of roles. Sometimes, you’ll be taking meeting notes, other times you’ll be writing manuscripts or grant applications. You may spend time teaching or organizing lab groups, or presenting at conferences. However, you’re probably using a number of different tools for these activities, PowerPoint, Word, Google Docs, LaTeX, Jupyter, and more.</p><p>But it’s likely that with the tools you’re using, you’ve found they don’t integrate well, and they’re decoupled from your research. Diagrams and figures are pasted into PowerPoint, severing the link between your data and your presentation. Manuscripts are published as static PDFs, months or years after the work is completed, with limited feedback opportunities. This affects not only you, but also the speed of scientific discovery — as it impacts scientific reproducibility globally.</p><p>Curvenote was created to address these challenges. Curvenote sits at the intersection of scientific collaboration, publishing, and technology. We believe how we share and communicate scientific knowledge should evolve past the status quo of print-based publishing and all the limitations of paper.</p><p>Curvenote believes in accessible, dynamic, open, reproducible, and connected science for all.</p><blockquote><strong><em>‍</em></strong><em>Curvenote is an interactive text editor for modern science. It supports your entire workflow — from note-taking, research, collaboration, and publishing, to everything in between. It also integrates with Jupyter, so that your Curvenote articles can also be linked to your data, code, and simulations.</em><strong><em>‍</em></strong></blockquote><h4>How Can I Use Curvenote to Improve My Workflows?</h4><p>There are multiple ways to integrate Curvenote into your existing workflows: from introducing it in your preliminary research, to recording in-progress research and meeting notes, to publishing manuscripts.</p><p>To learn more we interviewed <a href="https://curvenote.com/@lheagy">Dr. Lindsey Heagy</a>, an assistant professor in Earth Data Science and researcher at the University of British Columbia. Lindsey’s also a Science Advisor for Curvenote, which she’s using for multiple of her ongoing projects.</p><h3>Curvenote for Individual Research Notes</h3><p>Lindsey uses both Jupyter and Curvenote for her own preliminary research notes.</p><p>“Jupyter is the space where I do a lot of my personal research,” she said. “One of the questions that I’ve been looking at is within electromagnetic geophysics. I’m trying to understand how different physical properties change the data that we observe.”</p><p>Typically, researchers study variations in electrical conductivity; how easily current can pass through a given material. This is important in applications where we need to characterize the subsurface, like locating groundwater or mineral resources, or cleaning up areas with exploded ordnance. Lindsey is studying how magnetic properties also influence these data. The question she’s trying to answer is, if we have variations in both of these properties, how will that change the data we’re seeing?</p><p>“To do that, I first set up simulations and examples in Jupyter,” explained Lindsey. “Then I use <a href="https://curvenote.com/for/jupyter/">Curvenote’s Jupyter extension</a> to version my Jupyter Notebooks, and save my various states of work. What’s really powerful about that, is the peace of mind knowing that with one-click I have a back-up of all my work.”</p><p>With Curvenote’s Jupyter extension, you can also add comments to Jupyter Notebooks — which Lindsey uses to keep track of her own work.</p><p>“Often in the academic world, your time comes in spurts,” she said. “You might have two days to work on something, and then all of a sudden you have four days of meetings. You have to put down your work, but then later you’ll come back and pick it up.”</p><p>“With Curvenote, it’s useful to have that record of what you’ve done at each stage. And you can add comments to yourself to say things like ‘<em>I should check this out later’</em>, or ‘<em>this plot doesn’t make any sense, I have no idea what’s going on’</em>. It helps me capture my workflow, processes, diversions, and updates as I move along.”</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*_R9XA6pXsHUa8P3SgK254g.png" /><figcaption>A sample of Lindsey’s personal research notes: ‍<a href="https://curvenote.com/@simpeg/transform-2020-simpeg-tutorial/geophysical-inversions-with-simpeg">Geophysical Inversions with SimPEG</a></figcaption></figure><h3>Curvenote for Group Research Notes</h3><p>Lindsey also participates in the <a href="https://curvenote.com/@simpeg">SimPEG</a> (Simulation and Parameter Estimation in Geophysics) group — where the note taking process is even more complex.</p><p>“It’s a group of geoscientists who are using SimPEG, an open source software package for geophysics, for their work,” said Lindsey. “Folks are writing code, and showcasing different use cases from their research and applications, so we can improve the code base. This ensures SimPEG continues to serve everyone’s research within this space.”</p><p>The SimPEG group has adopted Curvenote for their weekly Wednesday meetings, where everyone showcases their work and any issues they’ve run into. The benefits have been numerous. For one, the SimPEG group has a centralized team profile — so anyone who misses a meeting can browse the week’s notes to catch up on what they missed. Curvenote also supports interactivity, so if a group member links to a Jupyter figure in the notes, it’ll stay interactive. It’s an accessible, interactive, and easy way for SimPEG to continue to build a light-weight open source community.</p><p>“There have been a couple scenarios that have been really fun to see,” said Lindsey. “There was a meeting a few weeks ago where somebody was prototyping new code, and wanted to talk about the implementation. So they linked their code directly into the group meeting notes.”</p><p>“Similarly, there are folks who have interesting research results they want to share. For example, maybe they have a figure they want to show off — and they can link to that directly in our meeting notes. It allows us to have an interesting collection of interactive scientific artifacts and ideas that different people have contributed to, but are all relevant to this one community.”</p><h4>View examples of the SimPEG group notes:</h4><ul><li><a href="https://curvenote.com/@simpeg/meeting-notes/2021-01-20">Meeting Notes: January 20, 2021</a> (check out this one for code snippets)</li><li><a href="https://curvenote.com/@simpeg/meeting-notes/2021-02-24">Meeting Notes: February 24, 2021</a>(check out this one for interactive plots)</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2umAHyus_jST6VDJKM8Icg.png" /><figcaption>Interactive plots embedded directly in meeting notes.</figcaption></figure><h3>Curvenote for Reproducible Research</h3><p>Reproducibility is something we hear about a lot in science and academia. This is what allows others to verify your claims and ultimately build on your work — which is the basis of science. It may sound simple, but there’s a lot to explore in this concept.</p><p>“There are a few ideas to unpack here: for one, there’s computational reproducibility,” said Lindsey. “Meaning that if you have the right software environment and data, you should be able to reproduce the work that I’ve done.”</p><p>“But there’s another more important term, which is replicability. This is the ability for a researcher to follow the description of what you’ve proposed, but use their own implementation and ideas to get comparable results. That way you can pick up someone’s work, run with it, and build on the ideas.”</p><p>Both of these pieces are needed to push scientific discovery forwards. Researchers and scientists will share their code and notebook repositories to satisfy the reproducibility piece, and produce manuscripts that describe their methods to support the replicability side of things.</p><p>“These areas have been systematically disjointed, though we are moving towards distributing both now,” said Lindsey. “Curvenote strengthens that link, because the figure that we produce in our Jupyter Notebooks is the same thing that’s linked in the article we’re writing.”</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*oRpqbOuzhWPTpCRDtBeeeQ.png" /><figcaption>Connect Jupyter Notebooks and Curvenote articles, and updated figures and comments flow back and forth.</figcaption></figure><p>Related to these concepts are the ideas of collaboration and accessibility; how you can make it easy for others to view, edit, and use your data and research — whether that’s across disciplines, industries or just within your own department. However, challenges can arise depending on the tools used.</p><p>“Typically in geophysics, we’re writing scientific papers in LaTeX because so many equations are involved,” said Lindsey. “It’s basically the same thing as writing Python scripts, which not everyone is comfortable with. And then usually you’re committing your work to GitHub, so any collaborators have to get set up on that too.”</p><p>But if you turn to a lighter-weight option, like Google Docs, to make it easier on your collaborators — you lose the link to reproducible content. Figures are copied and pasted in with no easy links back to the data, there’s no interactivity, and you lose the ability to write out equations.</p><p>“The Curvenote editor is really powerful because it contains all the technical tools needed to write a paper — but it also removes the barriers for collaborators,” said Lindsey. “You can bring in equations, easily create citations, reference figures, and all that. But you can also create headings that look like headings, and when you write the equation, it renders — so you can see it and make sure it’s correct.”</p><p>And of course, there’s also the option to bring in figures and other content from your Jupyter Notebooks with <a href="https://curvenote.com/for/jupyter/">Curvenote’s extension</a>.</p><p>“Curvenote fundamentally changes who can participate in scientific discussions. Someone can look at your Jupyter Notebook in Curvenote and comment on it, without actually having to open or install Jupyter,” said Lindsey. “I can just save my Jupyter Notebook to Curvenote, and then I send them a link! So I’m really excited to see what sort of opportunities this opens up within science.”</p><h3>Creating Open Educational Resources</h3><p>As a professor, Lindsey aims to constantly improve and supplement her teaching practices. She’s currently focused on integrating her open source and reproducibility practices into how she presents educational materials. Specifically, she’s working with a team to create interactive educational courses, and their main project is a geophysics course aimed at engineers and geologists.</p><p>“When we started this project, it was quite early on in the maturity of the open source publishing ecosystem,” said Lindsey. “So we made use of a lot of tools for Python documentation. The workflow was putting together some documents in Markdown or reStructuredText. And then we built that into a book that’s deployed on the web.”</p><p>“All of the collaboration and editing would happen on GitHub. And so there was that barrier of knowing how to version and do push/pull requests, to participate in the project.”</p><p>And it wasn’t just the team that was facing barriers with these tools. They also anticipated readers would have a harder time consuming the content, if it was published in a computational environment they weren’t familiar with.</p><p>“For the majority of the content we’re working on, computation is a part of it — we’re using it to show examples. But we’re not actually teaching computation,” said Lindsey. “For example, for the geophysics course, we want the readers to gain an understanding of different geophysical methods. But they don’t actually need to be the ones running the code or performing the analysis. They just need to have the skillset to be able to ask the right questions of other experts, like a contract geophysicist on their project.”</p><p>As well, Lindsey found the tools they were using weren’t the best for writing the course’s narrative content. These were tools built for programming, and they lacked some of the features needed for quick writing and editing.</p><p>To bridge these gaps, the team started using Curvenote to organize and produce their content.</p><p>“We’re writing out the narrative as much as we would in a paper,” said Lindsey. “But then we’re connecting that to Jupyter Notebooks so readers can run and explore different simulations, which can help them work through the content. It’s effectively pairing narrative content with exploratory notebooks, to provide an enhanced learning experience.”</p><p>And again, Curvenote’s features make it easy for the team to involve other experts.</p><p>“It can be so valuable to be able to email somebody with deep expertise in a topic and just say, <em>hey, can you comment on this</em>? And they can just look at that particular section and provide feedback,” said Lindsey. “With Curvenote articles, they’re always looking at the most up-to-date version, and they don’t need to download any software to access it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*vSywDKvKYIoho45sye4u3w.png" /><figcaption>Creating educational resources in Curvenote. View the <a href="https://curvenote.com/oxa:VNMrkxzChhdveZyf6lmb/xqM34l8moONMZ4iDWIQf">geophysics course sample</a>.</figcaption></figure><p><em>Originally published at </em><a href="https://curvenote.com/blog/research-workflows"><em>https://curvenote.com</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2cbd9f4f56db" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/research-workflows-2cbd9f4f56db">Research Workflows</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Collaboration in scientific writing]]></title>
            <link>https://medium.com/curvenote/collaboration-in-scientific-writing-bb09a53393a?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/bb09a53393a</guid>
            <category><![CDATA[writing]]></category>
            <category><![CDATA[phd]]></category>
            <category><![CDATA[academic-writing]]></category>
            <category><![CDATA[research]]></category>
            <category><![CDATA[scientific-writing]]></category>
            <dc:creator><![CDATA[Steve Purves]]></dc:creator>
            <pubDate>Thu, 30 Sep 2021 15:29:57 GMT</pubDate>
            <atom:updated>2021-09-30T15:40:31.844Z</atom:updated>
            <content:encoded><![CDATA[<p>And building the infrastructure to support it</p><h3>What is Collaboration?</h3><p>While the word is well-defined — modes and types of collaboration vary, especially in science where the concept of collaboration stretches from reviewing someone’s paper through to relationships around research that involve groups of people spanning years or decades.</p><p>When we think of collaboration at <a href="https://curvenote.com/">Curvenote</a>, we are specifically thinking about how people collaborate around distinct pieces of scientific work.</p><p>Of course, this includes co-authoring researcher publications which may occur within a series of months or years, but it means looking at how people collaborate day-to-day and week-to-week through writing, documents, data, and computational artifacts just as Jupyter Notebooks.</p><p>The majority of collaboration within closer peer groups happens through frequent communication; seminar papers &amp; discussion documents, presentations, technical reports, <a href="https://curvenote.com/blog/research-workflows-notes">research meeting notes</a>, research plans — all of which build a body of information and threads of learning, analysis, and discussion, which often culminates in a journal paper or thesis. But it’s the <em>whole</em> body of work and related artifacts that fully represent the research and process that was undertaken to reach the results.</p><p>In moving towards open science, researchers are striving to make more of this body of work openly available, their datasets, working documents, code, and preprints in addition to the final open-access publication — creating a package of work that can be more readily built upon and reused.</p><p>At Curvenote we are interested in <a href="https://curvenote.com/why">creating technology and collaborating on infrastructure</a> to support the entire process. We think about how to lower the barrier for more scientists to be able to work in this way while maintaining first-class support for open-source technologies and protocols that underpin modern science. This can spawn new relationships, connections, and collaborations and bring together people who would not have otherwise collaborated or contributed to a piece of work.</p><p>Some collaboration scenarios like close real-time collaboration, demand significant technology features, while in other scenarios, a single simple feature can significantly improve the collaboration experience in a number of ways, making it much more effective.</p><p>In this post, we talk about some distinct modes of collaboration and the technology and software features that support/enable them. We’ll focus on three modes:</p><ul><li>Gathering feedback — asynchronous, broad &amp; external collaboration</li><li>Asynchronous co-authoring and review</li><li>Real-time pairing / simultaneous editing</li></ul><h3>Gathering feedback</h3><p>This is likely one of the loosest forms of collaboration, typically asynchronous with a long cycle times — gathering feedback from a diverse group can be a significant amount of work. Not just in engaging or preparing the material, but in collecting and processing the feedback itself, which can sometimes come in various forms.</p><p>We’ve heard experiences of very difficult feedback cycles; a researcher emailing a draft document out to collaborators, to receive a variety of responses. Sometimes edited documents with comments interjected in the flow, responses in an email separate from the draft, PDF scans of printed copies with handwritten margin notes, multiple copies of the Word document sent back by email, Dropbox, or Google Drive.</p><p>Processing that feedback and incorporating it into the next draft can often require just as much work as the original study itself. The feedback process should be and can be much easier.</p><h4>Sharing &amp; Commenting</h4><p>Two simple features that are taken for granted in so many apps we use today (just think about how social media works) can completely change this workflow.</p><ul><li><em>Create drafts in a shared environment </em>— Google Docs is a go-to workaround for many people as collaboration is good, but it lacks support for scientific writing, which is <a href="https://curvenote.com/@curvenote/getting-started/writing-with-curvenote">where Curvenote excels</a>.</li><li><em>Share your supporting information</em> — To get useful and constructive feedback you need to formulate your “Ask” and provide those notes along with your manuscript. Curvenote projects let you <a href="https://curvenote.com/@curvenote/getting-started/collaboration">give your collaborators access</a> to multiple documents, such as guidance notes, manuscripts, and supporting materials (e.g., Jupyter notebooks), so everyone is working on the same page, in the same place.</li><li><em>In-place commenting</em> — Threaded commenting in a manuscript allows feedback to be provided and conversations to happen in-place and right beside the content it refers to. This is the ideal context for feedback; it encourages discussions over duplication and collaborators also get the chance to interact. A solid real-time commenting system with threads, notifications, and resolutions is of real benefit and makes it much easier for the author to gather and incorporate feedback. Everything in one place, everything in context.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*etqg6HjjQVxSIRnbtDXXPA.gif" /><figcaption>Feedback and discussion in real-time using threaded comments in Curvenote</figcaption></figure><h3>Asynchronous Coauthoring</h3><p>We aren’t always sitting right beside our co-authors and even when we are it doesn’t always mean that we write together. Often we’ll plan our manuscript, divide labor and draft our different sections to later cross review, revise and contribute to each other’s pieces to author the whole document.</p><p>Most of this authoring is going to happen asynchronously, but we want it to happen in the same place, without having to merge documents or get tied up emailing or spreading updated copies around via Dropbox. For this to work, you need a solid collaborative authoring environment, and because it is readily accessible Google Docs has been an attractive go-to for many people.</p><p>While Google Docs is a great tool for content co-authoring, the big drawback for us scientists is that Google Docs isn’t a scientific writing environment. It doesn’t nicely support many of the features we need; <a href="https://curvenote.com/@curvenote/getting-started/equations">equations</a>, <a href="https://curvenote.com/@curvenote/getting-started/internal-referencing">cross-referencing</a>, <a href="https://curvenote.com/@curvenote/getting-started/citations">citations</a>, footnotes, figures, and <a href="https://curvenote.com/@curvenote/getting-started/tables">tables</a> with numbering and captions — not to mention integrated datasets or computation for interactive figures. Thus, if used for raw text, it will inevitably have to be copied out and integrated into an environment where a manuscript can be constructed.</p><h4>Version Control for Writing</h4><p>A scientific editing environment with clear <a href="https://curvenote.com/blog/version-control-for-scientists">integrated version control</a> can really help here.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*WxgqouIeuSmtQfB9" /><figcaption>Version control in Curvenote is designed for writing. Blocks of content are moved forward through successive drafts with immutable versions being created periodically by the authors.</figcaption></figure><p>A manuscript is started in a shared environment (in Curvenote we call these projects) and authors can collaborate independently: adding blocks of content to the draft. Authors save their blocks as they progress and built-in version control makes it easy to see the progression and changes that people make.</p><p>In the early stages of the draft this co-editing works smoothly but as the work progresses, and authors begin modifying the shared content and refining sections originally written by the others, and the editing process becomes more tentative. Built-in version control means it’s easy to look back before edits were made and identify changes through “diffs” — the difference before and after a change.</p><p>In the later stages, edits are made more sparingly and conversations begin to appear in comments to discuss potential modifications. This is when “suggest changes” features come into their own.</p><h4>Suggest Changes</h4><p>While leaving comments in the draft as co-authors work will always happen, they are often not the best place for suggesting new text changes.</p><p>A solid suggest mode feature can speed up integrating contributions and gives co-authors the confidence to change the text in the first place. As all changes are in place you can view the content close to its edited form but also see easily what has been removed from the text, and how the flow of the prose is affected. Different software tools have experimented with the format of suggesting changes over time, from inline markup to balloons.</p><p>We prefer the inline style of Google Docs because it is relatively clear to read and each change is accompanied by a floating control in the margin, making it easy to isolate and accept to reject the change.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*n3PWvXFlBfA0kG3r" /><figcaption>Suggest changes mode in Google docs with changes from various authors being shown in different colors</figcaption></figure><p>We don’t yet have a “suggest changes” feature available in Curvenote, but it’s firmly on our roadmap so watch this space.</p><h3>Pair Authoring</h3><p>We’ve adapted a phrase here from the software development world where pair programming is the practice of multiple programmers working simultaneously on a single change or task.</p><p>While this may seem less productive, pairing improves quality, reduces defects, and improves team communication. Multiple sets of eyes and an active conversation around the changes being made lead to a better implementation and the additional time spent is recovered through better designs with fewer defects <a href="https://collaboration.csc.ncsu.edu/laurie/Papers/XPSardinia.PDF">Cockburn &amp; Williams, 2000</a>.</p><p>Of course, mileage varies depending on how well the process is supported, and the task at hand but what was previously something that was only possible for developers in the same room, is now both possible and actually more effective when developers are working from their own machines. This is because of the availability of real-time collaboration sessions supported directly by a developer’s coding environment.</p><h4>Real-time collaboration</h4><p>Real-time collaboration is a feature that allows multiple users of a software tool to edit a document simultaneously. This allows people to see others’ changes in real-time and incorporate their changes into the flow as the content updates. Naturally, this means that people can work on a single draft of a manuscript and immediately cut out working in different versions or creating subdocuments to work in on their own, only to later re-incorporate them.</p><p>Real-time interaction like this also promotes new behaviors. Authors can watch others type and join them in the writing flow, whether that’s mopping up typos, filling in references, or continuing the thread after one writer pauses. It is impressive to watch how a good collaborative writing environment can pull together a set of authors to produce a consistent piece of writing.</p><p>Like in software development, this type of activity is synchronous and requires some scheduling if not planning. Curvenote’s editor fully supports real-time collaboration allowing you to work like this right now and have a pair authoring session on your paper.</p><p>Often you can also benefit from being on a voice or video call at the same time, and here at Curvenote HQ, we’re often on Google Meet or Zoom so we can confer while working on a document.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/640/1*PfpU4UF8s3fm1Ys4gJJ81g.jpeg" /><figcaption>Image by Marvin Mayer — <a href="https://unsplash.com/photos/SYTO3xs06fU">https://unsplash.com/photos/SYTO3xs06fU</a></figcaption></figure><p>We have two important features at the top of our roadmap — presence and interactive cursors. If you’ve used Google Docs or other online collaborative editors, you’ll recognize these features. We’re expecting these will improve our real-time collaboration experience — and we’ll incorporate our own flavor of this UX pattern, meaning you’ll see who is actively watching and editing a block as well as seeing their cursor when they have a block in focus, are typing or have made a selection.</p><h3>Collaboration doesn’t stop there</h3><p>Of course, collaboration doesn’t stop there, there are more collaborative models with their own nuances, needs, and ways they can benefit from certain technology features.</p><p>Activities like open community authoring or open community reviews are interesting models. While Wikipedia springs to mind as a massive community-driven authoring project supported by a specific technology “The Wiki”. Another interesting example is GitHub and the increasing use of GitHub as a repository for scientific work in various forms: Markdown documents, posters and papers in pdf form, data, code, <a href="https://curvenote.com/for/jupyter">Jupyter notebooks</a>, interactive HTML documents, and books.</p><p>We are seeing researchers leverage existing technology from software development for version control, archiving, and software documentation tools to produce repositories for work that are open, and can be accessed to reproduce and re-use or build on the work. The community features around these tools enable discussion and contributions from multiple actors, encouraging connections and collaboration between a wider group of researchers who perhaps wouldn’t have otherwise come together.</p><p>This is a powerful example of how technology can play a transformative role in collaboration and interaction and is something to support as we move towards open science.</p><p>At <a href="https://curvenote.com/blog/communicating-science">Curvenote we are creating technology</a> to support these new ways of collaboration that are tailored towards technical writing and communication. We believe that these can help change how we interact with and progress scientific work.</p><p>Curvenote is a writing platform with first-class support for <a href="https://curvenote.com/for/writing">scientific and technical writing</a>, real-time collaboration, and integrations to the <a href="https://curvenote.com/for/jupyter">Jupyter ecosystem</a>. <a href="https://curvenote.com/signup">Try it out</a> for your ongoing research, thesis, next paper, or project.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bb09a53393a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/collaboration-in-scientific-writing-bb09a53393a">Collaboration in scientific writing</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Communicating Science]]></title>
            <link>https://medium.com/curvenote/communicating-science-23c81a737d28?source=rss----ca5f3d19387d---4</link>
            <guid isPermaLink="false">https://medium.com/p/23c81a737d28</guid>
            <category><![CDATA[jupyter]]></category>
            <category><![CDATA[science-communication]]></category>
            <category><![CDATA[version-control]]></category>
            <category><![CDATA[jupyter-notebook]]></category>
            <category><![CDATA[open-access]]></category>
            <dc:creator><![CDATA[Rowan Cockett]]></dc:creator>
            <pubDate>Tue, 16 Feb 2021 02:07:24 GMT</pubDate>
            <atom:updated>2021-09-29T20:34:25.760Z</atom:updated>
            <cc:license>http://creativecommons.org/licenses/by/4.0/</cc:license>
            <content:encoded><![CDATA[<p>One of the biggest challenges I see in communicating science is that how we share ideas is <em>disconnected</em> from how scientists work on them. A majority of researchers write using Microsoft Word, collaborating by email and sharing PDFs; even basic version control and real-time collaboration is often not in place (my_paper_final_3_edited.docx).</p><p>The headaches multiply when working in distributed teams and on large-scale computational models and data, both of which are integral to modern science. Static figures are copy/pasted between your computational environment and your PowerPoint slides or your paper — severing any links that aid in computational reproducibility: “Which code ran this figure again?” “What were the model parameters?”. Additionally, commenting and review of results in computational notebooks is disconnected from where you write and <em>think</em> about them.</p><blockquote><em>This disconnect between sharing and working prevents efficient feedback loops, delays publication, and stunts the evolution of ideas.</em></blockquote><p>We are starting <a href="http://curvenote.com/">Curvenote</a> because we believe that the introduction of tools and platforms that provide feedback loops between working and sharing will accelerate the speed of scientific discovery. We believe that the feedback loops connecting discovery and communication will promote collaborative evolution of ideas and ultimately increase the relevance and pace of scientific breakthroughs.</p><p>That is the dream anyways. 🙂</p><h3>Open Access</h3><p>Our team takes a lot of inspiration from the open-source development community, where two people who have never met can reuse each others ideas (in this case, software packages), and actually improve, fix and generalize these ideas. It happens without them meeting, planning, or really coordinating at all — which, frankly, is amazing.</p><p>The necessary first step in this scenario is clear and open licensing of content. The analogue in science is the open access movement — it is a hard fought, critically important, ongoing movement, which is starting to make changes in regulation and the actions of scientific researchers in where and how they publish their work. Open licensing is critical — with openly licensed content there can <em>then</em> be conversations about reuse and remixing.</p><blockquote><em>The legal possibility of reuse from open-access licensing will start to challenge social norms and concepts of plagiarism, authorship and contribution.</em></blockquote><p>If an author shares their work with a <a href="https://creativecommons.org/licenses/by/2.0/">CC-BY license</a>, the <em>legal</em> definition says you can reuse it as long as you attribute the source. Social norms, however, are quite different: “Can I reuse that great introduction paragraph — it is perfect!” “Nope, thats still plagiarism!” “Wait what?! It is openly licensed!”.</p><h3>Infrastructure</h3><p>These are exciting questions and thought experiments that will require more sophisticated ways of tracking attribution, licensing, changes, and suggestions. In the same way that licensing in the programming world opened up possibilities for collaborations between unknown contributors, it also required new technologies and infrastructure to really get off the ground.</p><blockquote><em>Scientific exploration and experimentation is different from programming.</em></blockquote><blockquote><em>Writing is different than programming.</em></blockquote><p>Most scientists are not trained in software development and the tools built for programmers are necessarily complex but difficult to adopt and don’t quite fit. Researchers focus much of their time on writing, teaching, presenting, experimenting, and exploring new ideas. Many of these use-cases are just not supported, or are needlessly complicated.</p><h3>Jupyter Notebooks</h3><p>One of the tools that falls in the middle between developers and experimentation is <a href="https://jupyter.org/">Jupyter</a>. Jupyter Notebooks have caused a pivotal change in relatively little time, allowing researchers and data-scientists to visually explore and interrogate data.</p><blockquote><em>Jupyter Notebooks have changed how we do science; the way we are communicating science is not keeping up.</em></blockquote><p>We believe it is not yet easy or fast enough to share and communicate scientific results to a broad audience.</p><blockquote><em>Where we write, summarize, share and </em>think together<em> about results is different from where the results are produced.</em></blockquote><p>Researchers copy their results into slide decks to get feedback, they print to PDF, take screenshots, use whiteboards. <strong><em>But.</em></strong> These tools are not linked, an insight from a colleague in your email gets lost; your team doesn’t have access to the latest chart; heck — <em>you</em> don’t even know how to reproduce it sometimes!</p><h3>Dreams</h3><p>In the future, every scientific report will feature interactive graphs with live data and computation that will make it significantly easier to share, attribute and reproduce the work.</p><p>We believe that the tools for sharing, thinking and writing should be linked to the <em>actual</em> data; the <em>actual</em> science. We believe in continual review and integrated feedback. We believe in evolving ideas and communicating them in <em>living </em>documents.</p><blockquote><em>How does open-science allow us to </em>reimagine<em> how we stand on the shoulders of giants?</em></blockquote><p>Our goal with <a href="https://curvenote.com/">Curvenote</a> is to explore the intersection between scientific collaboration, publishing, and technology.</p><p><em>We are building a text editor for modern science.</em></p><p>If you believe like we do that the way we communicate science should be more inspired. Accessible, dynamic, open, reproducible, connected. <strong>We want to hear from you!</strong></p><p>Send us an <a href="/service/mailto:hi@curvenote.com">email</a>, join the <a href="https://slack.curvenote.dev/">Slack Community</a>, or <a href="https://curvenote.com/">try what we have built</a> so far. <em>We are just getting started.</em></p><p>The main point of this is to say: “Hello world 👋!”</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=23c81a737d28" width="1" height="1" alt=""><hr><p><a href="https://medium.com/curvenote/communicating-science-23c81a737d28">Communicating Science</a> was originally published in <a href="https://medium.com/curvenote">Curvenote</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>