Merge pull request #63 from paxtonfitzpatrick/main

edits to statement of need, DOIs for citations where available

Author: paxtonfitzpatrick

paper/paper.bib

@@ -7,6 +7,7 @@ @article{GranGrou16
 
 @article{HarrEtal20,
 	author = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J. van der Walt and Ralf Gommers and Pauli Virtanen and David Cournapeau and Eric Wieser and Julian Taylor and Sebastian Berg and Nathaniel J. Smith and Robert Kern and Matti Picus and Stephan Hoyer and Marten H. van Kerkwijk and Matthew Brett and Allan Haldane and Jaime Fern{\'{a}}ndez del R{\'{i}}o and Mark Wiebe and Pearu Peterson and Pierre G{\'{e}}rard-Marchant and Kevin Sheppard and Tyler Reddy and Warren Weckesser and Hameer Abbasi and Christoph Gohlke and Travis E. Oliphant},
+	doi = {10.1038/s41586-020-2649-2},
 	journal = {Nature},
 	number = {7825},
 	pages = {357--362},
@@ -16,6 +17,7 @@ @article{HarrEtal20
 
 @article{Hunt07,
 	author = {J D Hunter},
+	doi = {10.1109/MCSE.2007.55},
 	journal = {Computing in Science and Engineering},
 	number = {3},
 	pages = {90--95},
@@ -27,6 +29,7 @@ @inproceedings{KluyEtal16
 	address = {Netherlands},
 	author = {Thomas Kluyver and Benjamin Ragan-Kelley and Fernando P{\'e}rez and Brian Granger and Matthias Bussonnier and Jonathan Frederic and Kyle Kelley and Jessica Hamrick and Jason Grout and Sylvain Corlay and Paul Ivanov and Dami{\'a}n Avila and Safia Abdalla and Carol Willing},
 	booktitle = {Positioning and Power in Academic Publishing: Players, Agents and Agendas},
+	doi = {10.3233/978-1-61499-649-1-87},
 	editor = {Fernando Loizides and Birgit Scmidt},
 	pages = {97--90},
 	publisher = {IOS Press},
@@ -54,12 +57,14 @@ @misc{Mann21b
 @inproceedings{McKi10,
 	author = {W McKinney},
 	booktitle = {Proceedings of the {Python} in Science Conference},
+	doi = {10.25080/Majora-92bf1922-00a},
 	pages = {51--56},
 	title = {Data structures for statistical computing in {P}ython},
 	year = {2010}}
 
 @article{MullEtal15,
 	author = {Muller, Eilif and Bednar, James A and Diesmann, Markus and Gewaltig, Marc-Oliver and Hines, Michael and Davison, Andrew P},
+	doi = {10.3389/fninf.2015.00011},
 	journal = {Frontiers in Neuroinformatics},
 	pages = {11},
 	title = {Python in neuroscience},
@@ -68,6 +73,7 @@ @article{MullEtal15
 
 @article{PereGran07,
 	author = {F P{\'e}rez and B E Granger},
+	doi = {10.1109/MCSE.2007.53},
 	journal = {Computing in science \& engineering},
 	number = {3},
 	pages = {21--29},
@@ -78,6 +84,7 @@ @article{PereGran07
 @inproceedings{RagaWill18,
 	author = {Ragan-Kelley, Benjamin and Willing, Carol},
 	booktitle = {Proceedings of the 17th Python in Science Conference},
+	doi = {10.25080/MAJORA-4AF1F417-011},
 	editor = {Akici, F and Lippa, D and Niederhut, D and and Pacer, M},
 	pages = {113--120},
 	title = {Binder 2.0-Reproducible, interactive, sharable environments for science at scale},
@@ -94,6 +101,7 @@ @techreport{vanREtal14
 
 @article{VirtEtal20,
 	author = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and {van der Walt}, St{\'e}fan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, C J and Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and {VanderPlas}, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and {van Mulbregt}, Paul and {SciPy 1.0 Contributors}},
+	doi = {10.1038/s41592-019-0686-2},
 	journal = {Nature Methods},
 	number = {3},
 	pages = {261--272},
@@ -103,7 +111,8 @@ @article{VirtEtal20
 
 @article{Wask21,
 	author = {Michael L. Waskom},
-	journal = {The Open Journal},
+	doi = {10.21105/joss.03021},
+	journal = {Journal of Open Source Software},
 	number = {60},
 	pages = {3021},
 	title = {seaborn: statistical data visualization},

paper/paper.md

@@ -5,8 +5,8 @@ tags:
  - Jupyter Notebook
  - JupyterLab
  - Google Colab
- - Reproducibility
- - package-management
+ - reproducibility
+ - package management
  - import
  - install
  - pip
@@ -20,7 +20,7 @@ authors:
 affiliations:
  - name: Department of Psychological and Brain Sciences, Dartmouth College
    index: 1
-date: 17 December 2021
+date: 21 January 2022
 bibliography: paper.bib
 link-citations: true
 ---
@@ -36,22 +36,22 @@ users to distribute their code and environment together in a single,
 ready-to-run Jupyter notebook [@KluyEtal16].
 
 Importing `davos` enables an additional Python keyword: `smuggle`. The `smuggle`
-keyword can be used as a drop-in replacement for the built-in `import` keyword
-to load libraries, modules, and other objects into the current namespace.
-However, whereas `import` will fail if the requested package is not installed
-locally, `smuggle` statements can handle missing packages on the fly. If a
-smuggled package does not exist in the local environment, `davos` will install
-it, make its contents visible to Python's `import` machinery, and load it into
-the namespace for immediate use.
-
-To provide greater control over the behavior of `smuggle` statements, `davos`
-also defines an additional construct, called *onion comments*. An onion comment
-is a special type of inline comment that can be placed on any line containing a
-`smuggle` statement to customize how `davos` determines whether and how
-smuggled packages should be installed. Onion comments follow a simple syntax
+statement can be used as a drop-in replacement for the built-in `import`
+statement to load libraries, modules, and other objects into the current
+namespace. However, whereas `import` will fail if the requested package is not
+installed locally, `smuggle` statements can handle missing packages on the fly.
+If a smuggled package does not exist in the local environment, `davos` will
+install it, make its contents visible to Python's `import` machinery, and load
+it into the namespace for immediate use.
+
+For greater control over the behavior of `smuggle` statements, `davos` defines
+an additional construct called the *onion comment*. An onion comment is a
+special type of inline comment that can be placed on a line containing a
+`smuggle` statement to customize how `davos` determines whether and how the
+smuggled package should be installed. Onion comments follow a simple syntax
 based on the type comment syntax introduced in PEP 484 [@vanREtal14] and are
-designed to make controlling installation via `davos` intuitive and familiar.
-To construct an onion comment, simply provide the name of the installer program
+designed to make controlling installation via `davos` intuitive and familiar. To
+construct an onion comment, simply provide the name of the installer program
 (e.g., `pip`) and the same arguments one would use to install the package as
 desired manually via the command line:
 
@@ -67,9 +67,9 @@ However, the most powerful use of the onion comment is making `smuggle`
 statements *version-sensitive*. Adding a [version
 specifier](https://www.python.org/dev/peps/pep-0440/#version-specifiers) to an
 onion comment will cause `davos` to search for the smuggled package in the local
-environment (as usual), and if it exists, additionally check whether the
-installed version satisfies the given constraint(s). If either check fails,
-`davos` will install and use a suitable version of the package:
+environment (as usual), and if it is found, further check whether the installed
+version satisfies the given constraint(s). If either check fails, `davos` will
+install and use a suitable version of the package:
 
 ![](snippets/snippet3.pdf)
 
@@ -107,65 +107,89 @@ Data*](https://github.com/ContextLab/storytelling-with-data) [@Mann21b\; an open
 course on data science, visualization, and communication] and `abstract2paper`
 [@Mann21a\; a toy application of
 [GPT-Neo](https://github.com/EleutherAI/gpt-neo)]. A more extensive guide to
-using `davos`, additional examples, and a description of how it works are
-available [here](https://github.com/ContextLab/davos).
+using `davos`, additional examples, and implementation details are available
+[here](https://github.com/ContextLab/davos).
 
 
 # Statement of Need
 
 Modern open science practices encourage sharing code and data to enable others
-to explore, reproduce, and extend existing work. Scientists, researchers, and
-educators may seek to share analyses with collaborators, students, the research
-community, or the general public. Python is among the most widely used and
-fastest-growing scientific programming languages [@MullEtal15]. In addition to
-the language's high-level, accessible syntax and large standard library, the
-Python ecosystem offers a powerful and extensive data science toolkit designed
-to facilitate rapid development and collaboration, including platforms for
-interactive development [e.g., Project Jupyter, @KluyEtal16\; Google
-Colaboratory], community-maintained libraries for data manipulation [e.g.,
-`NumPy`, @HarrEtal20; `SciPy`, @VirtEtal20; `Pandas`, @McKi10] and
+to explore, reproduce, and build on existing work. Scientists, researchers, and
+educators may seek to share research-related code with collaborators, students,
+the research community, or the general public. Python is among the most widely
+used and fastest-growing scientific programming languages [@MullEtal15]. In
+addition to the language's high-level, accessible syntax and large standard
+library, the Python ecosystem offers a powerful and extensive data science
+toolkit designed to facilitate rapid development and collaboration, including
+platforms for interactive programming [e.g., Project Jupyter, @KluyEtal16\;
+Google Colaboratory], community-maintained libraries for data manipulation
+[e.g., `NumPy`, @HarrEtal20; `SciPy`, @VirtEtal20; `Pandas`, @McKi10] and
 visualization [e.g., `Matplotlib`, @Hunt07; `seaborn`, @Wask21], and myriad
-other tools. 
+other tools.
 
 However, one impediment to sharing and reproducing computational work
 implemented in Python is that different versions of a given package or library
 can behave differently, use different syntax, add or drop support for specific
-functions or other libraries, address (or introduce) bugs, and so on. These
-challenges are true to some extent in any language or ecosystem, but they have a
-particular impact on the Python community due to its unusually rapid growth
-relative to other languages. Ensuring stable and reproducible results across
-users typically requires ensuring that the same versions of each library are
-installed. One approach is to use containerized or virtualized environments
-(e.g., using [Docker](https://www.docker.com/),
+functions or other libraries, address (or introduce) bugs, and so on. While
+these challenges are present to some extent in any language or ecosystem, they
+have a particular impact on the Python community due to its unusually rapid
+growth relative to other languages. Ensuring stable and reproducible results
+across users typically requires ensuring that shared code is always run with the
+same set of versions for each package used. One common approach to solving this
+problem is to create containerized or virtualized environments (e.g., using
+[Docker](https://www.docker.com/),
 [Singularity](https://sylabs.io/singularity/), or
-[conda](https://docs.conda.io/en/latest/)) that are effectively cordoned off
-from the user's primary Python installation. Configuration files may be used
-alongside these tools to construct environments that guarantee (within limits)
-the same or similar functionality across systems. However, a downside to
-relying on this approach is that it is highly resource intensive. For example,
-distributing research code that relies on a particular Docker image to run
-correctly requires the authors to distribute additional configuration files and
-instructions alongside their main code. Users must then download or build the
-image on their machine, which uses additional time and storage.
-
-`davos` provides an alternative way of ensuring stable functionality of iPython
-notebooks across users that is lightweight and contained entirely within the
-notebook file itself. All setup and configuration of packages needed to run the
-code in the notebook, including ensuring that the correct version of each
-package is utilized, may be managed by `davos`. Bypassing the need for
-the user to set up containers or virtual environments can enable users to run
-the notebook quickly and more easily.
-
-A second benefit of using `davos` (either in lieu of or alongside a different
-environment management tool) is that `smuggle` statements and onion comments
-continue to ensure requirements are satisfied after they are initially
-installed. For example, suppose a developer decides to install version 1.0 of
-package `x`, a critical library for some code they are working on. If `x`
-version 1.1 is a dependency of another package, `y`, then installing package `y`
-might overwrite version 1.0 of package `x` with version 1.1. This can lead to
-unexpected behavior if versions 1.0 and 1.1 of package `x` differ. To protect
-against unexpected behavior, `smuggle` statements and onion comments may be
-used to ensure that the expected versions of each library are imported.
+[conda](https://docs.conda.io/en/latest/)) that house fully isolated Python
+installations tailored to specific projects. These environments may be shared
+publicly as configuration files from which other users may build identical
+copies themselves. While effective, one drawback to this approach is that it can
+introduce a level of complexity beyond what is warranted for many simpler use
+cases. For example, distributing research code that relies on a particular
+Docker image to run properly not only necessitates extra configuration files and
+setup steps, but requires that both the author and end user install and navigate
+additional software that is often more complicated and resource-intensive than
+the actual code being shared. These added prerequisites clash with the
+simplicity and accessibility that have helped popularize Python among
+researchers, and can create barriers to both contributing to and taking
+advantage of open science.
+
+`davos` provides an alternative way to ensure stable functionality of Jupyter
+notebooks across users and over time that is intuitive, lightweight, and
+contained entirely within the notebook file itself. Using `smuggle` statements
+and onion comments, required packages can be specified directly within the code
+that uses them and automatically installed as they are needed. This offers two
+notable advantages over typical approaches to dependency management. First, it
+simplifies and expedites the process of sharing reproducible workflows by
+eliminating the need for additional configuration files, pre-execution setup,
+and environment management software (aside from `davos` itself). With `davos`,
+analyses, tutorials, and demos can be packaged and shared as "batteries
+included" notebooks that can be downloaded and immediately run, making them more
+accessible to less technical users.
+
+Second, `smuggle` statements and onion comments continue to ensure requirements
+are satisfied after they are initially installed. Most dependency specification
+schemes follow a common strategy: required packages and package versions are
+listed in a configuration file (e.g., a `requirements.txt`, `pyproject.toml`,
+`environment.yml`, `Pipfile`, `RUN` instructions in a `Dockerfile`, etc.) which
+is used to install them in a Python environment upfront. After this initial
+setup, however, this method generally does not ensure that the specified
+requirements *remain* installed, allowing them to be easily
+altered—sometimes inadvertently. This can lead to subtle issues when
+writing reproducible code in such a preconfigured environment. For instance,
+suppose a researcher has implemented a series of analyses using version 1.0 of
+"Package *X*," and later decides to perform an additional analysis that requires
+installing "Package *Y*." If Package *Y* depends on version 1.1 of Package *X*,
+then Package *X* will be upgraded to accommodate this new requirement. And if
+the researcher does not notice this change, differences between the two Package
+*X* versions risk introducing bugs into previously written code. Using `davos`,
+either in lieu of or alongside a different environment management tool, provides
+a safeguard against this situation. `smuggle` statements and onion comments
+enforce requirements every time they are executed, guaranteeing the expected
+version of each package is always used. This would not only catch and correct
+the unintentional change to Package *X*, but would also allow the researcher to
+choose whether to manually resolve the inconsistency or, if appropriate,
+`smuggle` different versions of the package as necessary.
+
 
 # Origin of the Name