hillmaker is a Python package that computes time of day and day of week specific occupancy statistics from transaction data containing arrival and departure timestamps. Typical use is for capacity planning problems in places like hospital emergency departments, surgical recovery rooms or any system in which entities arrive, occupy capacity for some amount of time, and then depart. It gets its name from the hill-like nature of plots based on temporal occupancy statistics.

• usable via a CLI, a function based API and and objected oriented API
• takes a pandas DataFrame or csv file as the input data type
• computes arrival, departure and occupancy summary statistics by time of day, day of week, and entity category based on a dataframe containing one record per visit.
• computes arrival, departure and occupancy for each datetime bin in a specified date range
• select any time bin size (minutes) that divides evenly into a day.
• output statistics includes sample size, mean, min, max, standard deviation, coefficient of variation, standard error, skew, kurtosis, and percentiles.
• weekly and day of week plots can be created by default or on demand; numerous plot related input parameters are available,
• summary report for length of stay automatically created
• outputs are stored in a dictionary containing pandas dataframes and as matplotlib figures. These can be accessed by methods for further post-processing or for exporting to external files.
• Requires Python >= 3.10, pandas >= 1.5.0, numpy >= 1.22, pydantic >= 2.1.1, seaborn >= 0.12.2, matplotlib >= 3.7.1, and tomli >= 2.0.1 (if not using Python 3.11)
• MIT License

See the CHANGELOG for details on latest and older versions.

• Project repo: http://github.com/misken/hillmaker
• PyPI: https://pypi.python.org/pypi/hillmaker
• Documentation: https://hillmaker.readthedocs.io/en/latest/intro.html
• More Examples: See notebooks and scripts at http://github.com/misken/hillmaker-examples

We also have a paper under review at the Journal of Open Source Software.

HTML: Markdown:

You can install using pip:

pip install hillmaker

You should also be able to install hillmaker from conda-forge shortly into a virtual environment.

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install hillmaker 

If you want to get the latest update which is not yet on PyPI or conda-forge, you can install from the GitHub repo's develop branch:

pip install git+https://github.com/misken/hillmaker@develop

See the Getting Started page in the hillmaker docs.

Use the GitHub issue tracking system to report problems with the software, seek support, or suggest improvements. Code contributions can be suggested using GitHub pull requests.

The develop branch contains the latest working code that has not been released yet. Any contributed code should branch off of develop.

If you use Conda to manage your virtual environments, you can use environment.yml to create a Conda virtual environment named hillmaker_dev that will install dependencies for doing hillmaker development.

conda env create -f environment.yml

If you don't use Conda, you can use pip along with requirements.txt to set up your development environment.

pip install -r requirements.txt

After the dependencies are installed, you can do an editable install of hillamker into your virtual environment from the project root (where setup.py lives).

pip install -e .

See the History page at the hillmaker docs.