mikecroucher / jupyter-interactions

A repository of jupyter interactions

Jupyter Interactions repository

This site was created to show off not only interesting maths, programming, and data science, but also the power of Jupyter notebooks. Each notebook is a demonstration of a single concept and makes use of ipywidgets to generate an interactive mini-application within the Jupyter notebook.

Contributing a notebook

To contribute a notebook to the collection, make sure that it follows the structure of the template laid out in template.ipynb and make a Pull Request. Your contribution will then be reviewed by members of the community.

The Website

We have a prototype website for this project at https://mikecroucher.github.io/jupyter-interactions/. This was built during a hackathon session at the Computational Mathematics with Jupyter Workshop in early 2017. Code to generate the site is at https://github.com/christianp/jupyter-interactions-site

jupyter-interactions's Issues

Steps to get started with running interactions

I'm writing this down because two of us had the same problem.

• I installed vanilla Python 3.6, then pip install jupyter[notebook] matplotlib
• In order to get the javascript for ipywidgets to work, I had to run jupyter nbextension enable --py --sys-prefix widgetsnbextension, and restart jupyter (I think I had to do this a couple of times before it worked)

SageMath

Can one use Sage kernel ?

Add a Binbderhub button

Would be useful to add a launch on Binder button to the readme.

There are also some packages that need installing, eg via an Anaconda environment.yml file, for the notebooks to run directly via Binderhub:

• matplotlib
• sklearn
• sympy
• seaborn
• graphviz (both as a Linux package and a python package)

Examples of pre-existing interaction repos

Include all examples (that adhere to template) in one repo or have many repos?

Should each Notebook be single file in one repo?

Or should we have a collection of repos, each containing one Notebook plus supporting files, docker/conda env files etc.

If we have multiple repos then would this make peer review more difficult? Could we have a very simple service that allocates reviewers to repos? Or should we focus on using existing infrastructure?

If we wanted this project to look and feel a little like an academic journal then we could have a repository per volume? How to make it look like a journal? Want DOIs for items. Can get DOI (from zenodo/figshare) for single file in a repo?

Could we use a Conda-Forge-style model where have lots of single repos from which info is migrated to a central repo if it passes CI service tests. Downside is lots of different CI services interacting with GH - high maintenance?

How can we test notebooks?

Libraries change over time...how can we flag up notebooks that don't work on latest versions of things?

Interactions create many copies

I've just been trying these notebooks out on IPython 6.0 and run into ipython/ipython#10376, which causes each change to a widget to append a new plot instead of replacing what came before.

Long story short, until they make a better fix each interaction using matplotlib needs to include plt.show() after it's finished setting up the plot, in order to flush the previous plots. I'm happy to make a pull request, but not sure of the implications of editing notebooks on a more recent version of IPython and resubmitting.

Use list instead of comma separated value?

We use lists for references and we could use lists instead of comma separated value for keywords and requirements/dependencies.

Where do we store additional data?

Some demos will need extra files/data to work.

Keywords and subject classification

Tag by both discipline and widget type?

How to embed tags in Notebooks? Separate cell(s) at the bottom of each Notebook?

For discipline we could use the 2010 Mathematics Subject Classification

Website

What mechanisms could be used to turn this repo into a searchable website that is automatically updated when a new notebook is accepted.

Files created as a side-effect of running a notebook

The "Divisors of a positive integer" notebook creates a couple of files as a side-effect of running the notebook (graphviz writes its output to a file before displaying it).

Is this a problem? If notebooks run in one-off containers anyway, this might not matter.

Or if it is a problem, checking that no other files are created could be a step for the linter.

Plan

• - Sort out the template
• - Populate with a set of examples
• - Automatically generate a gallery from them
• - Publish to Azure for running them automatically

Kernel name issues

A Travis build failed https://travis-ci.org/mikecroucher/jupyter-interactions/builds/192734354

==================================== ERRORS ====================================
___________________________ ERROR at setup of cell 1 ___________________________
self = <nbval.kernel.NbvalKernelspecManager object at 0x7f7d1e9d73c8>
kernel_name = 'Python [Root]'
    def get_kernel_spec(self, kernel_name):
        """Returns a :class:`KernelSpec` instance for the given kernel_name.
    
            Raises :exc:`NoSuchKernel` if the given kernel name is not found.
            """
        d = self.find_kernel_specs()
        try:
>           resource_dir = d[kernel_name.lower()]
E           KeyError: 'python [root]'

Gallery view inc. thumbnails

Would be good to have an attractive gallery view. Could either use curated thumbnails or decide on an automated way of generating thumbnails. Could also turn off fine detail (axes labels etc) for thumbnails.

Create a notebook linter

That e.g. checks to see that the keyword cell makes sense

Licensing

What licence should (a) this repository, and (b) the submitted notebooks be released under?

CC-BY would be appropriate for the notebooks. The linter should check for a copyright and licence declaration.

I'm happy to put the code to make the website under MIT or Apache.

Rendering in gallery appears to be broken

See https://mikecroucher.github.io/jupyter-interactions/notebooks/clustering-using-dbscan/

Where would we run the notebooks?

A python library to get the metadata from an ipynb file

In order to create the website, we need some code to extract the metadata (and a representative image) from each notebook.

Devise submission scheme

How would someone submit a notebook to this repository? Should there be a review process? We need the process to be documented.

Number format Trait Error - Unknown readout_format='i'

Several notebooks have a readout_format='i' setting in the widget call that returns an error:

TraitError: The type specifier of a NumberFormat trait must be one of ['', 'o', 'c', 'p', 'b', 'x', 'g', 'd', 'f', 'X', '%', 'e', 's', 'r'], but a value of 'i' was specified.

What should be in the template?

The aim is to ensure that contributed notebooks are short and to the point. The current template is rather sparse. Is it enough? What else should be added?