reviewed, ready for submission
added doc strings