added new function, updated docstrings