Jupyter Physical Science Lab Suite (JPSL)
Documentation for the Jupyter Physical Science Lab Suite of Packages.
Introduction | Try It | Quick
Start |
Packages | Packages being
considerd |
JPSL Project Repository |
JPSL Documentation Repository |
License
Introduction
The key goals of this suite of packages is to provide:
- an open source electronic laboratory notebook that is practical in physical
science laboratories where data is collected by hand, from instrumentation
and sensors;
- the ability to run on minimal hardware (things like the Raspberry Pi) to
make it affordable for educational use;
- adaptability, allowing for use in a variety of teaching situations;
- GUI elements that allow students in introductory courses without programming
experience to collect data and analyze it, while also facilitating
scaffolding learning to write data analysis code/scripts in more advanced
course;
- tools for instructors allowing them to create worksheets or more open-ended
assignments (there is some potential feature overlap
with nbgrader, but nbgrader tools are
aimed more at math and programming assignments);
- ability to generate compact pdf formatted “reports” for grading;
- easy ways to have students analyze data while properly tracking units and
what analysis was done, thus facilitating grading and trouble-shooting of
student work.
There are two basic flavors of this suite of packages: student; and instructor.
The instructor flavor includes tools for generating content in worksheets that
students cannot edit. As well as ways to control what is displayed to the
students and in the final version submitted for grading. The student version
purposely leaves out the tools that
allow unlocking of locked cells in a notebook, so that the instructor can
include unchanging instructions, examples and questions.
Try it
You can try the parts of Jupyter Physical Science lab without installing
anything. The packages can be run in the cloud. Links to do this are
provided on the Github pages for each package. It is recommended that you
start with JPSLInstructor,
which includes all the supported packages.
Quick Start
- Install python on your machine, if necessary.
- Check current system python install by opening a command line
terminal and issuing the command
python3 --version
. If it is >= 3.
7 you can use it. Otherwise, follow the next step to install a
newer version.
- Get the installer for your computer from python.org.
Follow the instructions for installing on your system.
- Install a tool for managing and using virtual environments. This
allows you to have multiple independent sets (virtual environments)
of python packages installed.
- I recommend you use this so that you can have both an “instructor”
and “student” environment for testing.
- I personally like using pipenv.
You can install it using the command
pip3 --user install pipenv
. On
Windows you will probably have to do python3 -m pip --user install
pipenv
.
See the website for more information.
- Set up an instructor work environment.
- Create a directory to contain your virtual environment and navigate
into it (in *nix:
cd path-to-directory
).
- Create the empty virtual environment
pipenv shell
(on Windows
python3 -m pipenv shell
). This will
create the environment, activate it and leave you inside it.
WARNING:
on Windows I have seen it move you to another directory. If it does
this navigate back using the cd
command.
- Still within the environment use pip to install the JPSLInstructor
pseudo package
pip install JPSLInstructor
. This will take a while
to run. There are a lot of packages to download and install.
- Example notebooks are not installed by pip. You should download the
JPSLInstructor pseudo package
as a zip file and extract the
Examples
folder into the directory for this
virtual environment.
- To work with the software launch the jupyter notebook with the
command
jupyter lab
(for the complex user interface) or juptyer
notebook
(for the simplified user interface). This will
launch a local jupyter server on your machine and open a page
connected to it in your web browser (Chrome and Firefox work best).
- Open an example notebook to try things.
- After quiting the Jupyter notebook server you can exit the virtual
environment with the command
exit
.
- Set up a student work environment for testing.
- Create a directory to contain your virtual environment and navigate
into it (in *nix:
cd path-to-directory
).
- Create the empty virtual environment
pipenv shell
. This will
create the environment, activate it and leave you inside it.
- Still within the environment use pip to install the JPSLStudent
pseudo package
pip install JPSLStudent
. This will take a while
to run. There are a lot of packages to download and install.
- To work with the software launch the jupyter notebook with the
command
juptyer notebook
(the simplified interface is recommended
most use with students).
- Copy notebooks you want to see from a student perspective into this
directory.
- After quiting the Jupyter notebook server you can exit the virtual
environment with the command
exit
.
Packages
(Under active development, please try and send feedback)
The packages are available from PyPi (using pip for installation) or by
installing from these repositories. The packages are broken up to allow using
only the tools necessary.
- jupyter-datainputtable
provides tools for generating a GUI table into which data can be typed and
the data will survive clearing of the cell outputs from a notebook.
- jupyter-instructortools
provides menu based tools for locking and unlocking text (Markdown) and code
cells, inserting tables, some boilerplate language, etc.
- jupyter-pandas-GUI
provides jupyter widget based GUI code composers for tasks such as
calculating a new column in a Pandas DataFrame, making a scatter or line
plot from data in a DataFrame, or fitting data in a DataFrame.
- JupyterPiDAQ provides
tools for interactive data collection using A/D boards and
visualization of that data, presently supports specific boards attached
to Raspberry Pi 3B+ or above and sensors connected to Vernier LabQuest
interfaces.
- jupyterpidaq_menu
provides a menu of useful commands for initiating
data collections and analyzing data.
- JPSL_Tools_Menu
provides a convenience menu with access to documentation on the parts of
the Jupyter Physical Science Lab and menu items to insert common
initialization code, commands to activate each tool and control hiding of
cells for printing.
- Algebra_with_SymPy provides
a definition for an equation with a lhs and a rhs. This tool applies
operations to both sides of the equation simultaneously, just as students are
taught to do when attempting to isolate (solve for) a variable. Thus the
statement
Equation/b
yields a new
equation Equation.lhs/b = Equation.rhs/b
. This facilitates clearly
documented symbolic algebraic manipulations and calculations with units
included.
- Pseudo Packages
Packages being considered
These are packages that are under development elsewhere, but might be included
if there is interest:
- DeltaSymbol allows adding a symbol
in SymPy that displays as the typeset Δ
X
in Jupyter notbooks. Where
ΔX
is the common abbreviation for final(X) - initial (X)
.
- jupyter-wysiwyg provides
a what you see is what you get mode for Markdown/Richtext cells activated by
clicking a button.
- ipysketch. Tool for making and
embedding sketches in a notebook.
- ipysheet. Tool that provides
a widgets based alternative to jupyter-datainputtable
. To use,
data persistence will have to be addressed.
- WYSIWYGcell provides what you see is what you get text edit cells in
Jupyter notebooks, but involves significant changes to the Jupyter notebook
code, thus will either require providing a fully custom Jupyter notebook or
monkey patching a current installation.
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
Copyright - Jonathan Gutow, 2021 - 2024.