Merge pull request #1033 from StochSS/develop

v2.1.2

CODE_OF_CONDUCT.md

@@ -0,0 +1,44 @@
+Contributor Covenant Code of Conduct
+====================================
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project contributors are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project contributors have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project contributors.
+
+## Enforcement
+
+If a contributor engages in harassing behaviour, the project organizers may take any action they deem appropriate, including warning the offender or expelling them from online forums, online project resources, face-to-face meetings, or any other project-related activity or resource.
+
+If you are being harassed, notice that someone else is being harassed, or have any other concerns, please contact a member of the project team immediately.  Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team.  All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.  The project team is obligated to maintain confidentiality with regard to the reporter of an incident.  Further details of specific enforcement policies may be posted separately.
+
+## Attribution
+
+Portions of this Code of Conduct were adapted from Electron's [Contributor Covenant Code of Conduct](https://github.com/electron/electron/blob/master/CODE_OF_CONDUCT.md), which itself was adapted from the [Contributor Covenant](http://contributor-covenant.org/version/1/4), version 1.4.

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# CONTRIBUTING  
+By contributing to StochSS, you agree to the [Code of Conduct](/CODE_OF_CONDUCT.md) and the conditions of the [GNU GPL v3](/LICENSE). Please review both of these documents before contributing.
+
+## Making Changes
+1. Fork [the project repository](https://github.com/StochSS/StochSS).
+2. Create a new branch from the 'develop' branch. Use a meaningful name and include an issue number if applicable.
+3. Add new changes to your branch. Be sure to document your code and remove any dead code.
+4. Add the [COPYRIGHT](/COPYRIGHT) notice to the beginning of any new files you create.
+5. Create unit tests to cover changes. Unit tests should be placed in the [test](/stochss/tests) subdirectory.
+6. Use [pylint](https://pylint.org) to validate any new Python code to ensure [PEP 8](https://www.python.org/dev/peps/pep-0008/) compliance.
+
+## Submitting a Pull Request
+1. Make a pull request to 'develop'.
+2. Include a list of changes in the PR description.
+3. Link relevant issues to the pull request.
+4. Add labels relevant to any changes made.
+5. Provide a clear description of any new features in the PR description.
+6. Add any relevant StochSS team members as reviewers.

README.md

@@ -1,29 +1,34 @@
-# StochSS: The Stochastic Simulation Service
+# StochSS: Software as a service for simulation-driven investigations of stochastic biochemical models
 
-StochSS is a platform for simulating biochemical systems supporting both continuous ODE and discrete stochastic simulations with [GillesPy2](https://github.com/GillesPy2/GillesPy2). 
+StochSS provides advanced tools for simulating and analyzing biochemical systems as Software as a Service. StochSS supports a wide range of model types ranging from continuous ODEs to discrete (spatial) stochastic simulations as well as advanced model analysis workflows.  
+
+**Try out [StochSS Live!](https://live.stochss.org)**  
+
+## Why use StochSS
+StochSS provides both an easy-to-use UI for constructing biochemical models as well as intuitive UIs for the most common model analysis tools such as visualization of results, parameter sweeps and parameter inference. StochSS is built on top of Jupyter Hub, and this lets you seemlessly switch between UI representations and Notebooks exposing the full backend API. In this way a user can benefit from the best of graphical representations with a clear upgrade path to modeling as code. For this reason, StochSS is also uniquely suited for the computational biologist starting out with mathematical modeling of biochemical systems. 
 
-At the moment StochSS development on Windows is not supported. You can try using [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm), but this is untested!
+StochSS is a software project involving several leading research groups in computational systems biology. We welcome collaborators to help expand the capabilities of StochSS. Read more about the project at [www.stochss.org](http://www.stochss.org).   
+
+StochSS is intended to be used as Software as a Service via [StochSS Live!](https://live.stochss.org). The following instructions can help you set up your own local development environment or deploy your own instance as SaaS.
 
-## Requirements
+## Deploying your own Single-User StochSS Instance
+### Requirements
 
 - [Nodejs](https://nodejs.org/)
 
 - [Docker Desktop](https://www.docker.com/products/docker-desktop) (Windows and Mac) or [Docker Engine](https://docs.docker.com/install/) (Linux, Mac, and Windows)
 
-- [Docker Compose](https://docs.docker.com/compose/install/) (Only required if you want to run StochSS with [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/#))
+At the moment StochSS development on Windows is not supported. You can try using [Make for Windows](http://gnuwin32.sourceforge.net/packages/make.htm), but this is untested!
 
-## Quickstart
+### Quickstart
 
 - Build and run the stochss notebook server: `make`. This starts a local docker container running StochSS.
 
-- Once your terminal calms down you'll see a link to your server that looks something like this: `127.0.0.1:8888/?token=X8dSfd...`
-
-- Navigate to that link and get started.
+- Once your terminal calms down you'll see a link to your server that looks something like this: `127.0.0.1:8888/?token=X8dSfd...` Navigate to that link and get started.
 
 - Your files are persisted on your local machine to the `local\_data/` directory by default.
 
-
-## Setup
+### Setup
 
 - Build the docker container: `make build`.
 
@@ -35,28 +40,29 @@ At the moment StochSS development on Windows is not supported. You can try using
 
 - [Optional] By default your files are saved to your local machine at `./local\_data/`. You can change this location by the changing value of `DOCKER\_WORKING\_DIR` in the file `.env`.
 
-
-### Add a python dependency
+#### Add a python dependency
 
 Use requirements.txt to add Python dependencies that will be installed into the StochSS docker container.
 
-## JupyterHub
-
-JupyterHub is a multi-user system for spawning Jupyter notebook servers. We use JupyterHub to serve the StochSS home page and spawn StochSS notebook servers.
+## Deploying Multi-User StochSS
 
+StochSS uses [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/#) as the basis for the multi-user deployment.  See their documentation for more details on configuring the JupyterHub environment.
+
 ### Setup
 
-- [Optional] To set admins for JupyterHub, make a file called `userlist` in the `jupyterhub/` directory. On each line of this file place a username followed by the word 'admin'. For example: `myuser admin`. If using Google OAuth, the uesrname will be a gmail address. Navigate to `/hub/admin` to use the JupyterHub admin interface.
+- In addition to the single-user requirements, you will need [Docker Compose](https://docs.docker.com/compose/install/).  
+
+- [Optional] To set admins for JupyterHub, make a file called `userlist` in the `jupyterhub/` directory. On each line of this file place a username followed by the word 'admin'. For example: `myuser admin`. If using Google OAuth, the uesername will be a gmail address. Navigate to `/hub/admin` to use the JupyterHub admin interface.
 
 - [Optional] By default multi-user StochSS is set up to allocate 2 logical cpus per user, reserving 2 logical cpus for the hub container and underlying OS. You can define a list of "power users" that are excluded from resource limitations by adding a text file called `.power_users` (note the leading period) to the `jupyterhub/` directory with one username/email address on each line of the file.
 
 ### Run Locally
 
-- To run JupyterHub locally run `make hub` and go to 127.0.0.1:8888.
+To run JupyterHub locally run `make hub` and go to 127.0.0.1:8888.
 
-### Setup Staging Server
+### Set Up A Staging Server
 
-To setup the staging environment you'll need the correct Google OAuth setup in `jupyterhub/secrets/.oauth.staging.env`. Do not wrap these environment variables in quotes!
+To set up the staging environment you'll need to [set up Google OAuth](https://developers.google.com/identity/protocols/oauth2) for your instance.  Once you're set up, you'll need to put your OAuth credentials in `jupyterhub/secrets/.oauth.staging.env`. Do not wrap these environment variables in quotes!
 
 Example oauth file:
 
@@ -74,7 +80,7 @@ make build_hub
 make run_hub_staging
 ```
 
-### Setup Production Server
+### Set Up A Production Server
 
 Similar to staging, except you'll need the correct Google OAuth credentials set in `jupyterhub/secrets/.oauth.prod.env`.
 

client/app.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //var config = require('./config.js')(process.env.NODE_ENV);
 let path = require('path');
 

client/config.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 let path = require('path');
 
 

client/graphics.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 module.exports = {
   logo:
 `<?xml version="1.0" encoding="UTF-8" standalone="no"?>

client/modals.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 let help = require('./page-help')
 
 let templates = {

client/models/creator.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //models
 var State = require('ampersand-state');
 

client/models/event-assignment.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //models
 var State = require('ampersand-state');
 

client/models/event-assignments.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //models
 var EventAssignment = require('./event-assignment');
 //collections

client/models/event.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //models
 var State = require('ampersand-state');
 //collections

client/models/events.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 var _ = require('underscore');
 //models
 var Event = require('./event');

client/models/function-definition.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //models
 var State = require('ampersand-state');
 

client/models/function-definitions.js

@@ -1,3 +1,21 @@
+/*
+StochSS is a platform for simulating biochemical systems
+Copyright (C) 2019-2020 StochSS developers.
+
+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.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
 //collections
 var Collection = require('ampersand-collection');
 //models