research-to-production/salary/README.md

Salary Assessment App

Demonstration of an interactive web-application built in python. This application takes in an employee roster (built interactively, best for small teams), with names, positions, and salaries for each employee. It then allows someone (e.g. a manager) to simulate promotions and/or salary raises and see the overall impact on the final payroll budget (visualized as a pair of overlaying distributions which show the before/after scenario under the provided ranges). Finally, the app "solves the problem" of assigning a new salary to each employee while staying below some pre-defined budget for payroll, using a novel Monte-Carlo method implemented directly within the app itself (rather than relying on importing another library).

This example shows "a small amount of effort" exerted to ensure reproducibility and readability but ultimately lacks in overall user-friendliness.

Takeaways: Good reproducibility, passable style/formatting.

• Of particular note here is the executable run shell script which provides support for running the application using a docker image as well as simultaneously supporting native shell execution if docker is not in the system $PATH
• Note the style in which functions are written in app.py
  • There is a mixture of functions and procedural code, wide abuse of global variables, and a lot of messy plotting code. Is it readable overall?
  • The app's "state" is held in data.json, is saved in a human-readable format (as opposed to binary), and is small enough to be negligible
  • The functions that are defined at least have readable names
  • If the app grew any larger than this, one might be wise to migrate functions into a separate module and import it in app.py
• Note the lack of a proper README / we just "presume" the user knows what to do with the presence of a Makefile. Is this acceptable in your opinion?
  • Very minimal Makefile is "sort of self-documenting" but many people don't know to look there. It could use documentation so that make help at least produces some sort of a helpful guide

Usage

(if using local python instead of docker):

make install

then

make run

and visit localhost:8501 (or <tld>/<user>/proxy/8501/ in Jupyter if you have jupyter-server-proxy installed to access the app via proxy)