sededu 1.1.10

sediment-related educational activity suite

SedEdu is a suite of educational activities related to geomorphology and sedimentology. The suite is targeted at educators who want to bring engaging, interactive, and scientifically relevant activities into their classroom. SedEdu is built entirely in Python and is free and open source software. Modules included in SedEdu are built by researchers at the cutting edge of their fields and are designed to showcase their research in a digestible manner.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for use in the classroom. See Contributing to SedEdu for information on becoming a part of the SedEdu project.

Installing dependencies

SedEdu runs in Python 3 and utilizes PyQt5 for rendering the graphical user interface. Modules included in SedEdu rely on scipy, matplotlib, pillow, and shapely.

You can check your Python version by running: python3 -V in a terminal. Note that you may need to specify the path to your Python executable on some systems. If you do not have Python 3 installed, you will need to do so to use SedEdu. This will not disrupt an existing Python 2.x installation, if you rely on that for other uses.

If you are new to Python, it is strongly recommended that you install Anaconda Python, which is an open source distribution of Python which includes many basic scientific libraries, some of which are used in the module. Anaconda can be downloaded at https://www.anaconda.com/download/ for Windows, macOS, and Linux. If you do not have storage space on your machine for Anaconda or wish to install a smaller version of Python for another reason, see below on options for Miniconda or vanilla Python.

1. Visit the website for Anaconda https://www.anaconda.com/download/ and select the installer for your operating system. Be sure to select the Python 3.x installation.
2. Start the installer.
3. If prompted, select to "install just for me", unless you know what you are doing.
4. When prompted to add Anaconda to the path during installation, select yes if you know you do not have any other Python installed on your computer; otherwise select no.
5. If you received no errors, proceed to installing below.

If you want a more flexible and lightweight Python distribution, you can use whatever your favorite package manager is distributing (e.g., homebrew or apt), check the Windows downloads here, or compile from source. If you go this route, you will need to also install pip3, PyQt5 (python3-pyqt5), and the dependency python packages listed below.

Note that on Linux, users may need to specify an installation of pyqt and/or tkinter directly from apt: Install PyQt5:

sudo apt install python3-pyqt5 python3-tk

Installing SedEdu

If you installed Anaconda Python or Miniconda, you can follow the instructions below for your operating system. Otherwise see the instructions for PyPi installation below.

Please open an issue if you encounter any troubles installing or any error messages along the way! Please include 1) operating system, 2) installation method, and 3) copy-paste the error.

Windows users

1. Open your "start menu" and search for the "Anaconda prompt"; start this application.
2. Install pyqt5 with the following command and hit "enter":

conda install -c conda-forge pyqt

3. Install with the module type the following command and hit "enter":

conda install -c sededu sededu

If asked to proceed at either step, type Y and press "enter" to continue installation. 4. This process may take a few minutes as the necessary source code is downloaded. If the installation succeeds, proceed below to the "Run the module" section.

Note on permissions: you may need to run the Anaconda prompy "as administrator" on Windows.

Mac OSX and Linux users

1. Install the module by opening a terminal and typing the following command.

conda install -c sededu sededu

If asked to proceed at either step, type Y and press enter to continue installation. 2. This process may take a few minutes as the necessary source code is downloaded. If the installation succeeds, proceed below to the "Run the module" section.

Note on permissions: you may need to use sudo on OSX and Linux.

Advanced user installations

Install with pip To install with pip from Pypi use (not recommended for entry-level users):

pip install pyqt5 sededu

or in the event of a failed install, try:

pip install pyqt sededu

See below instructions for downloading the source code if you wish to be able to modify the source code for development or for exploration.

Install by cloning the repository

Developers see below: You can clone the git repository to get the latest release version with:

git clone --recurse-submodules -b develop https://[e-mail]/sededu/sededu.git

and SedEdu is then run with:

python sededu/run_sededu.py

Note that if you have no modules: run git submodule update --init --recursive.

Running SedEdu

1. Open a Python shell by typing python (or python3) at the terminal (OSX and Linux users) or at the Anaconda / Command Prompt (Windows users).
2. Windows users only: run activate root
3. Run the module from the Python shell with:

import sededu

Instructions will indicate to use the following command to then run the module:

sededu.run()

Alternatively, you can do this in one line from the standard terminal with:

python -c "import sededu; sededu.run()"

Alternatively, run the module with provided script:

python <path-to-installation>run_sededu.py

Please open an issue if you encounter any additional error messages! Please include 1) operating system, 2) installation method, and 3) copy-paste the error.

Troubleshooting

• SedEdu won't launch: you're probably missing some Python or PyQt dependencies. If you pip installed, did you install pyqt? Linuz users: try sudo apt install python3-pyqt5.

• There are no modules in SedEdu: you probably didn't get the submodules when you git cloned. Try git submodule update --init --recursive inside the cloned repository.

Contributing to SedEdu

The SedEdu project needs contributions from the community to be successful. However, there are many different ways you can contribute! You do not even need to write code to contribute to SedEdu. Some opportunities for contributions are listed below (in no particular order):

• write (code) a standalone interactive module
• write an activity for an existing module
• write (code) features and bug fixes for existing modules
• write (code) features and bug fixes for SedEdu
• write documentation for SedEdu

Please read CONTRIBUTING.md for details on our code of conduct, and the process for contributing to SedEdu (which includes any pull request).

Developer installation

Dev channel stats:

You should get the entire repository and work off of the develop branch:

git clone --recurse-submodules https://github.com/sededu/sededu.git
git checkout -b <name-of-working-branch> develop

If you have already git cloned and need to pull the submodules now try:

git submodule update --init --recursive

See CONTRIBUTING.md for more information on the preferred git workflow for SedEdu, including a note on hot-fixes.

Authors

• Andrew J. Moodie - 3 modules - github.com/amoodie
• Kensuke Naito - 1 module - github.com/kensukename2
• Jeffrey Kwang - 1 module - github.com/jeffskwang

See also the list of contributors who have participated in this project in other ways.

License

This project is licensed under the GNU GPL License - see the full license file for details. It is provided without warranty or guaranteed support. Each submodule may be licensed under a different license, please see the relevant module's license file, README, or project homepage for more information.

Acknowledgments

The SedEdu framework was created by Andrew J. Moodie but has been built through the efforts of many authors (see Authors above). The authors have been supported by:

• The US National Science Foundation under Grant Nos. 1427262 and 1450681.

Disclaimer

Any opinion, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of any funding agency.