API Reference

API Reference#

Scenario#

The hillmaker.scenario module defines the Scenario class and the OO API for using hillmaker.

class hillmaker.scenario.EdgeBinsEnum(value)#: An enumeration.

class hillmaker.scenario.Scenario(*, scenario_name: str, data: str | Path | DataFrame, in_field: str, out_field: str, start_analysis_dt: date | datetime | Timestamp | datetime64, end_analysis_dt: date | datetime | Timestamp | datetime64, cat_field: str | None = None, bin_size_minutes: int = 60, cats_to_exclude: List[str] | None = None, occ_weight_field: str | None = None, percentiles: Tuple[float] | List[float] = (0.25, 0.5, 0.75, 0.95, 0.99), los_units: str | None = 'hours', export_bydatetime_csv: bool = False, export_summaries_csv: bool = False, csv_export_path: Path | str | None = PosixPath('.'), make_all_dow_plots: bool = False, make_all_week_plots: bool = True, export_all_dow_plots: bool = False, export_all_week_plots: bool = False, plot_export_path: Path | str | None = None, plot_style: str | None = 'ggplot', figsize: tuple = (15, 10), bar_color_mean: str | None = 'steelblue', alpha: float = 0.5, plot_percentiles: Tuple[float] | List[float] = (0.95, 0.75), pctile_color: Tuple[str] | List[str] = ('black', 'grey'), pctile_linestyle: Tuple[str] | List[str] = ('-', '--'), pctile_linewidth: Tuple[float] | List[float] = (0.75, 0.75), cap: int | None = None, cap_color: str | None = 'r', xlabel: str | None = 'Hour', ylabel: str | None = 'Volume', main_title: str | None = '', main_title_properties: None | Dict = {'fontsize': 16, 'loc': 'left'}, subtitle: str | None = '', subtitle_properties: None | Dict = {'loc': 'left', 'style': 'italic'}, legend_properties: None | Dict = {'facecolor': 'w', 'frameon': True, 'loc': 'best'}, first_dow: str = 'mon', edge_bins: EdgeBinsEnum = EdgeBinsEnum.FRACTIONAL, highres_bin_size_minutes: int = 5, keep_highres_bydatetime: bool = False, nonstationary_stats: bool = True, stationary_stats: bool = True, verbosity: int = VerbosityEnum.WARNING, stops_preprocessed_df: DataFrame | None = None, los_field_name: str | None = None, hills: dict | None = None)#

pydantic model for creating scenario objects from input parameters

Parameters:

scenario_name (str) – Used in output filenames
data (str, Path, or DataFrame) – Base data containing one row per visit. If Path-like, data is read into a DataFrame.
in_field (str) – Column name corresponding to the arrival times
out_field (str) – Column name corresponding to the departure times
start_analysis_dt (datetime-like, str) – Starting datetime for the analysis (must be convertible to pandas Timestamp)
end_analysis_dt (datetime-like, str) – Ending datetime for the analysis (must be convertible to pandas Timestamp)
cat_field (str, optional) – Column name corresponding to the categories. If none is specified, then only overall occupancy is summarized. Default is None
bin_size_minutes (int, optional) – Number of minutes in each time bin of the day, default is 60. This bin size is used for plots and reporting and is an aggregation of computations done at the finer bin size resolution specified by resolution_bin_size_mins. Use a value that divides into 1440 with no remainder.
cats_to_exclude (list, optional) – Category values to ignore, default is None
occ_weight_field (str, optional) – Column name corresponding to the weights to use for occupancy incrementing, default is None which corresponds to a weight of 1.0
percentiles (list or tuple of floats (e.g. [0.5, 0.75, 0.95]), optional) – Which percentiles to compute. Default is (0.25, 0.5, 0.75, 0.95, 0.99)
los_units (str, optional) – The time units for length of stay analysis. See https://pandas.pydata.org/docs/reference/api/pandas.Timedelta.html for allowable values (smallest value allowed is ‘seconds’, largest is ‘days’. The default is ‘hours’.
export_bydatetime_csv (bool, optional) – If True, bydatetime DataFrames are exported to csv files. Default is False.
export_summaries_csv (bool, optional) – If True, summary DataFrames are exported to csv files. Default is False.
csv_export_path (str or Path, optional) – Destination path for exported csv and png files, default is current directory
make_all_dow_plots (bool, optional) – If True, day of week plots are created for occupancy, arrivals, and departures. Default is False.
make_all_week_plots (bool, optional) – If True, full week plots are created for occupancy, arrivals, and departures. Default is True.
export_all_dow_plots (bool, optional) – If True, day of week plots are exported for occupancy, arrivals, and departures. Default is False.
export_all_week_plots (bool, optional) – If True, full week plots are exported for occupancy, arrivals, and departures. Default is False.
plot_export_path (str or None, default is None) – If not None, plot is exported to export_path
plot_style (str, optional) – Matplotlib built in style name. Default is ‘ggplot’.
figsize (Tuple, optional) – Figure size. Default is (15, 10)
bar_color_mean (str, optional) – Matplotlib color name for the bars representing mean values. Default is ‘steelblue’
alpha (float, optional) – Transparency level for bars. Default = 0.5.
plot_percentiles (list or tuple of floats (e.g. [0.75, 0.95]), optional) – Which percentiles to plot. Default is (0.95, 0.75)
pctile_color (list or tuple of color codes (e.g. ['blue', 'green'] or list('gb'), optional) – Line color for each percentile series plotted. Order should match order of percentiles list. Default is (‘black’, ‘grey’).
pctile_linestyle (List or tuple of line styles (e.g. ['-', '--']), optional) – Line style for each percentile series plotted. Default is (‘-’, ‘–‘).
pctile_linewidth (List or tuple of line widths in points (e.g. [1.0, 0.75])) – Line width for each percentile series plotted. Default is (0.75, 0.75).
cap (int, optional) – Capacity of area being analyzed, default is None
cap_color (str, optional) – matplotlib color code, default=’r’
xlabel (str, optional) – x-axis label, default=’Hour’
ylabel (str, optional) – y-axis label, default=’Patients’
main_title (str, optional) – Main title for plot, default = ‘Occupancy by time of day and day of week - {scenario_name}’
main_title_properties (None or dict, optional) – Dict of suptitle properties, default={{‘loc’: ‘left’, ‘fontsize’: 16}}
subtitle (str, optional) – title for plot, default = ‘All categories’
subtitle_properties (None or dict, optional) – Dict of title properties, default={{‘loc’: ‘left’, ‘style’: ‘italic’}}
legend_properties (None or dict, optional) – Dict of legend properties, default={{‘loc’: ‘best’, ‘frameon’: True, ‘facecolor’: ‘w’}}
first_dow (str, optional) – Controls which day of week appears first in plot. One of ‘mon’, ‘tue’, ‘wed’, ‘thu’, ‘fri’, ‘sat, ‘sun’
edge_bins (int, default 1) – Occupancy contribution method for arrival and departure bins. 1=fractional, 2=entire bin
highres_bin_size_minutes (int, optional) – Number of minutes in each time bin of the day used for initial computation of the number of arrivals, departures, and the occupancy level. This value should be <= bin_size_minutes. The shorter the duration of stays, the smaller the resolution should be. The current default is 5 minutes.
keep_highres_bydatetime (bool, optional) – Save the high resolution bydatetime dataframe in hills attribute. Default is False.
nonstationary_stats (bool, optional) – If True, datetime bin stats are computed. Else, they aren’t computed. Default is True
stationary_stats (bool, optional) – If True, overall, non-time bin dependent, stats are computed. Else, they aren’t computed. Default is True
verbosity (int, optional) – Used to set level in loggers. 0=logging.WARNING (default=0), 1=logging.INFO, 2=logging.DEBUG

stops_preprocessed_df#

Preprocessed dataframe that only contains necessary fields and does not include records with missing: timestamps for the entry and/or exit time. This DataFrame is the one used for hill making.

Type:: DataFrame (initialized to None)

hills#

Stores results of make_hills.

Type:: dict (initialized to None)

Examples

Example 1 - using keyword arguments:

# Required inputs
scenario_name = 'ssu_oo_1'
stops_df = ssu_stops_df
in_field_name = 'InRoomTS'
out_field_name = 'OutRoomTS'
start_date = '2024-06-01'
end_date = pd.Timestamp('8/31/2024')

# Optional inputs
cat_field_name = 'PatType'
bin_size_minutes = 60

scenario_1 = hm.Scenario(scenario_name=scenario_name,
                     data=stops_df,
                     in_field=in_field_name,
                     out_field=out_field_name,
                     start_analysis_dt=start_date,
                     end_analysis_dt=end_date,
                     cat_field=cat_field_name,
                     bin_size_minutes=bin_size_minutes)

Example 2 - using TOML config file

Here’s what an example config file might look like.:

[scenario_data]
scenario_name = "ss_oo_2"
data = "./data/ssu_2024.csv"

[fields]
in_field = "InRoomTS"
out_field = "OutRoomTS"
# Just remove the following line if no category field
cat_field = "PatType"

[analysis_dates]
start_analysis_dt = 2024-01-02
end_analysis_dt = 2024-03-30

[settings]
bin_size_minutes = 120
verbosity = 1
csv_export_path = './output'
plot_export_path = './output'

# Add any additional arguments here
# Strings should be surrounded in double quotes
# Floats and ints are specified in the normal way as values
# Dates are specified as shown above

# For arguments that take lists, the entries look
# just like Python lists and following the other rules above

# cats_to_exclude = ["IVT", "OTH"]
# percentiles = [0.5, 0.8, 0.9]

# For arguments that take dictionaries, do this:
# main_title_properties = {loc = 'left', fontsize = 16}
# subtitle_properties = {loc = 'left', style = 'italic'}
# legend_properties = {loc = 'best', frameon = true, facecolor = 'w'}

Then we can pass the filename like this:

scenario_2 = hm.create_scenario(config_path='./input/ssu_oo_2.toml')

Example 3 - using a dictionary of input values:

ssu_oo_3_dict = {
'scenario_name': 'ssu_oo_3',
'data': ssu_stops_df,
'in_field': 'InRoomTS',
'out_field': 'OutRoomTS',
'start_analysis_dt': '2024-01-01',
'end_analysis_dt': '2024-09-30',
'cat_field': 'PatType',
'bin_size_minutes': 60
}

ssu_oo_3 = hm.create_scenario(params_dict=ssu_oo_3_dict)
print(ssu_oo_3)

compute_hills_stats()#

Computes the bydatetime and summary statistics (no plotting or exporting).

Return type:: dict stored in hills attribute of Scenario object

compute_implied_operating_hours(by_category: bool = True, statistic: str = 'mean', threshold: float = 0.2)#

Infers operating hours of underlying data.

Computes implied operating hours based on exceeding a percentage of the maximum occupancy for a given statistic.

Parameters:

by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
statistic (str) – Column name for the statistic value. Default is ‘mean’.
threshold (float) – Percentage of maximum occupancy that will be considered ‘open’ for operating purposes, inclusive. Default is 0.2.

Return type:

pandas styler object

get_bydatetime_df(by_category: bool = True)#

Get bydatetime dataframe

Parameters:: by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
Return type:: DataFrame

get_los_plot(by_category: bool = True)#

Get length of stay histogram from length of stay summary

Parameters:: by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
Return type:: Matplotlib plot

get_los_stats(by_category: bool = True)#

Get length of stay stats table from length of stay summary

Parameters:: by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
Return type:: pandas Styler

get_plot(flow_metric: str = 'occupancy', day_of_week: str = 'week')#

Get plot object for specified flow metric and whether full week or specified day of week.

Parameters:

flow_metric (str) – Either of ‘arrivals’, ‘departures’, ‘occupancy’ (‘a’, ‘d’, and ‘o’ are sufficient). Default=’occupancy’
day_of_week (str) – Either of ‘week’, ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, ‘Sat’. Default=’week’

Return type:

plot object from matplotlib

get_summary_df(flow_metric: str = 'occupancy', by_category: bool = True, stationary: bool = False)#

Get summary dataframe

Parameters:

flow_metric (str) – Either of ‘arrivals’, ‘departures’, ‘occupancy’ (‘a’, ‘d’, and ‘o’ are sufficient). Default=’occupancy’
by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
stationary (bool) – Default=False corresponds to the standard nonstationary statistics (i.e. by TOD and DOW)

Return type:

DataFrame

make_daily_plot(day_of_week: str, metric: str = 'occupancy', **kwargs)#

Create daily plot

Parameters:

day_of_week (str) – One of ‘mon’, ‘tue’, ‘wed’, ‘thu’, ‘fri’, ‘sat, ‘sun’
metric (str) – One of ‘occupancy’, ‘arrivals’, ‘departures’
kwargs (dict) – Plot related keyword arguments

Return type:

matplotlib.Figure

Example

scenario_1.make_daily_plot(day_of_week = ‘mon’, metric=’arrivals’,: plot_export_path=’./output’, plot_style=’default’)

make_hills()#

Wrapper for module level hillmaker.make_hills() function.

Return type:: dict stored in hills attribute of Scenario object

make_weekly_plot(metric: str = 'occupancy', **kwargs)#

Create weekly plot

Parameters:

metric (str) – Some abbreviated version of occupancy, arrivals or departures
kwargs (dict) – Plot related keyword arguments

Return type:

matplotlib.Figure

Example

scenario_1.make_weekly_plot(metric=’occupancy’, plot_export_path=’./output’, cap=40, plot_style=’default’)

model_computed_fields: ClassVar[dict[str, ComputedFieldInfo]] = {}#: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'forbid'}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields: ClassVar[dict[str, FieldInfo]] = {'alpha': FieldInfo(annotation=float, required=False, default=0.5), 'bar_color_mean': FieldInfo(annotation=Union[str, NoneType], required=False, default='steelblue'), 'bin_size_minutes': FieldInfo(annotation=int, required=False, default=60), 'cap': FieldInfo(annotation=Union[int, NoneType], required=False), 'cap_color': FieldInfo(annotation=Union[str, NoneType], required=False, default='r'), 'cat_field': FieldInfo(annotation=Union[str, NoneType], required=False), 'cats_to_exclude': FieldInfo(annotation=Union[List[str], NoneType], required=False), 'csv_export_path': FieldInfo(annotation=Union[Path, str, NoneType], required=False, default=PosixPath('.')), 'data': FieldInfo(annotation=Union[str, Path, DataFrame], required=True), 'edge_bins': FieldInfo(annotation=EdgeBinsEnum, required=False, default=<EdgeBinsEnum.FRACTIONAL: 1>), 'end_analysis_dt': FieldInfo(annotation=Union[date, datetime, Timestamp, datetime64], required=True), 'export_all_dow_plots': FieldInfo(annotation=bool, required=False, default=False), 'export_all_week_plots': FieldInfo(annotation=bool, required=False, default=False), 'export_bydatetime_csv': FieldInfo(annotation=bool, required=False, default=False), 'export_summaries_csv': FieldInfo(annotation=bool, required=False, default=False), 'figsize': FieldInfo(annotation=tuple, required=False, default=(15, 10)), 'first_dow': FieldInfo(annotation=str, required=False, default='mon'), 'highres_bin_size_minutes': FieldInfo(annotation=int, required=False, default=5), 'hills': FieldInfo(annotation=Union[dict, NoneType], required=False), 'in_field': FieldInfo(annotation=str, required=True), 'keep_highres_bydatetime': FieldInfo(annotation=bool, required=False, default=False), 'legend_properties': FieldInfo(annotation=Union[NoneType, Dict], required=False, default={'loc': 'best', 'frameon': True, 'facecolor': 'w'}), 'los_field_name': FieldInfo(annotation=Union[str, NoneType], required=False), 'los_units': FieldInfo(annotation=Union[str, NoneType], required=False, default='hours'), 'main_title': FieldInfo(annotation=Union[str, NoneType], required=False, default=''), 'main_title_properties': FieldInfo(annotation=Union[NoneType, Dict], required=False, default={'loc': 'left', 'fontsize': 16}), 'make_all_dow_plots': FieldInfo(annotation=bool, required=False, default=False), 'make_all_week_plots': FieldInfo(annotation=bool, required=False, default=True), 'nonstationary_stats': FieldInfo(annotation=bool, required=False, default=True), 'occ_weight_field': FieldInfo(annotation=Union[str, NoneType], required=False), 'out_field': FieldInfo(annotation=str, required=True), 'pctile_color': FieldInfo(annotation=Union[Tuple[str], List[str]], required=False, default=('black', 'grey')), 'pctile_linestyle': FieldInfo(annotation=Union[Tuple[str], List[str]], required=False, default=('-', '--')), 'pctile_linewidth': FieldInfo(annotation=Union[Tuple[float], List[float]], required=False, default=(0.75, 0.75)), 'percentiles': FieldInfo(annotation=Union[Tuple[Annotated[float, NoneType, Interval, NoneType, NoneType]], List[Annotated[float, NoneType, Interval, NoneType, NoneType]]], required=False, default=(0.25, 0.5, 0.75, 0.95, 0.99)), 'plot_export_path': FieldInfo(annotation=Union[Path, str, NoneType], required=False), 'plot_percentiles': FieldInfo(annotation=Union[Tuple[float], List[float]], required=False, default=(0.95, 0.75)), 'plot_style': FieldInfo(annotation=Union[str, NoneType], required=False, default='ggplot'), 'scenario_name': FieldInfo(annotation=str, required=True), 'start_analysis_dt': FieldInfo(annotation=Union[date, datetime, Timestamp, datetime64], required=True), 'stationary_stats': FieldInfo(annotation=bool, required=False, default=True), 'stops_preprocessed_df': FieldInfo(annotation=Union[DataFrame, NoneType], required=False), 'subtitle': FieldInfo(annotation=Union[str, NoneType], required=False, default=''), 'subtitle_properties': FieldInfo(annotation=Union[NoneType, Dict], required=False, default={'loc': 'left', 'style': 'italic'}), 'verbosity': FieldInfo(annotation=int, required=False, default=<VerbosityEnum.WARNING: 0>), 'xlabel': FieldInfo(annotation=Union[str, NoneType], required=False, default='Hour'), 'ylabel': FieldInfo(annotation=Union[str, NoneType], required=False, default='Volume')}#

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo].

This replaces Model.__fields__ from Pydantic V1.

class hillmaker.scenario.VerbosityEnum(value)#: An enumeration.

hillmaker.scenario.create_scenario(params_dict: Dict | None = None, config_path: str | Path | None = None, **kwargs)#: Function to create a Scenario from a dict, a TOML config file, and/or keyword args

hillmaker.scenario.update_params_from_toml(params_dict, toml_dict)#

Update dict of input parameters from toml_config dictionary

Parameters:

params_dict (dict) –
toml_dict (dict from loading TOML config file) –

Return type:

Updated parameters dict

legacy#

The hillmaker.legacy module provides a function based API for using hillmaker.

Compute occupancy, arrival, and departure statistics by category, time bin of day and day of week.

Main function that first calls bydatetime.make_bydatetime to calculate occupancy, arrival and departure values by date by time bin and then calls summarize.summarize to compute the summary statistics.

Parameters:

scenario_name (str) – Used in output filenames
data (str, Path, or DataFrame) – Base data containing one row per visit. If Path-like, data is read into a DataFrame.
in_field (str) – Column name corresponding to the arrival times
out_field (str) – Column name corresponding to the departure times
start_analysis_dt (datetime-like, str) – Starting datetime for the analysis (must be convertible to pandas Timestamp)
end_analysis_dt (datetime-like, str) – Ending datetime for the analysis (must be convertible to pandas Timestamp)
cat_field (str, optional) – Column name corresponding to the categories. If none is specified, then only overall occupancy is summarized. Default is None
bin_size_minutes (int, optional) – Number of minutes in each time bin of the day, default is 60. This bin size is used for plots and reporting and is an aggregation of computations done at the finer bin size resolution specified by resolution_bin_size_mins. Use a value that divides into 1440 with no remainder.
cats_to_exclude (list, optional) – Category values to ignore, default is None
occ_weight_field (str, optional) – Column name corresponding to the weights to use for occupancy incrementing, default is None which corresponds to a weight of 1.0
percentiles (list or tuple of floats (e.g. [0.5, 0.75, 0.95]), optional) – Which percentiles to compute. Default is (0.25, 0.5, 0.75, 0.95, 0.99)
los_units (str, optional) – The time units for length of stay analysis. See https://pandas.pydata.org/docs/reference/api/pandas.Timedelta.html for allowable values (smallest value allowed is ‘seconds’, largest is ‘days’). The default is ‘hours’.
export_bydatetime_csv (bool, optional) – If True, bydatetime DataFrames are exported to csv files. Default is False.
export_summaries_csv (bool, optional) – If True, summary DataFrames are exported to csv files. Default is False.
csv_export_path (str or Path, optional) – Destination path for exported csv files, default is the current directory
make_all_dow_plots (bool, optional) – If True, day of week plots are created for occupancy, arrival, and departure. Default is True.
make_all_week_plots (bool, optional) – If True, full week plots are created for occupancy, arrival, and departure. Default is True.
export_all_dow_plots (bool, optional) – If True, day of week plots are exported for occupancy, arrival, and departure. Default is False.
export_all_week_plots (bool, optional) – If True, full week plots are exported for occupancy, arrival, and departure. Default is False.
plot_export_path (str or Path, optional, default is the current directory) – Destination path for exported png files, default is the current directory
plot_style (str, optional) – Matplotlib built in style name. Default is ‘ggplot’.
figsize (Tuple, optional) – Figure size. Default is (15, 10)
bar_color_mean (str, optional) – Matplotlib color name for the bars representing mean values. Default is ‘steelblue’
alpha (float, optional) – Transparency level for bars. Default = 0.5.
plot_percentiles (list or tuple of floats (e.g. [0.75, 0.95]), optional) – Which percentiles to plot. Default is (0.95)
pctile_color (list or tuple of color codes (e.g. ['blue', 'green'] or list('gb'), optional) – Line color for each percentile series plotted. Order should match order of percentiles list. Default is (‘black’, ‘grey’).
pctile_linestyle (List or tuple of line styles (e.g. ['-', '--']), optional) – Line style for each percentile series plotted. Default is (‘-’, ‘–‘).
pctile_linewidth (List or tuple of line widths in points (e.g. [1.0, 0.75])) – Line width for each percentile series plotted. Default is (0.75, 0.75).
cap (int, optional) – Capacity of area being analyzed, default is None
cap_color (str, optional) – matplotlib color code, default=’r’
xlabel (str, optional) – x-axis label, default=’Hour’
ylabel (str, optional) – y-axis label, default=’Patients’
main_title (str, optional) – Main title for plot, default = ‘{Occupancy or Arrivals or Departures} by time of day and day of week’
main_title_properties (None or dict, optional) – Dict of main title properties, default={{‘loc’: ‘left’, ‘fontsize’: 16}}
subtitle (str, optional) – subtitle for plot, default = ‘Scenario: {scenario_name}’
subtitle_properties (None or dict, optional) – Dict of subtitle properties, default={‘loc’: ‘left’, ‘style’: ‘italic’}
legend_properties (None or dict, optional) – Dict of legend properties, default={{‘loc’: ‘best’, ‘frameon’: True, ‘facecolor’: ‘w’}}
first_dow (str, optional) – Controls which day of week appears first in plot. One of ‘mon’, ‘tue’, ‘wed’, ‘thu’, ‘fri’, ‘sat, ‘sun’
edge_bins (int, default 1) – Occupancy contribution method for arrival and departure bins. 1=fractional, 2=entire bin
highres_bin_size_minutes (int, optional) – Number of minutes in each time bin of the day used for initial computation of the number of arrivals, departures, and the occupancy level. This value should be <= bin_size_minutes. The shorter the duration of stays, the smaller the resolution should be. The current default is 5 minutes.
keep_highres_bydatetime (bool, optional) – Save the high resolution bydatetime dataframe in hills attribute. Default is False.
nonstationary_stats (bool, optional) – If True, datetime bin stats are computed. Else, they aren’t computed. Default is True
stationary_stats (bool, optional) – If True, overall, non-time bin dependent, stats are computed. Else, they aren’t computed. Default is True
verbosity (int, optional) – Used to set level in loggers. 0=logging.WARNING (default=0), 1=logging.INFO, 2=logging.DEBUG

Returns:

The bydatetime DataFrames, all summary DataFrames and any plots created.

Return type:

dict of DataFrames and plots

Example

Use like this:

# Required inputs
scenario_name = 'ssu_summer24'
in_field_name = 'InRoomTS'
out_field_name = 'OutRoomTS'
start_date = '2024-06-01'
end_date = '2024-08-31'

# Optional inputs
cat_field_name = 'PatType'
bin_size_minutes = 30
csv_export_path = './output'

# Optional plotting inputs
plot_export_path = './output'
plot_style = 'default'
bar_color_mean = 'grey'
percentiles = [0.85, 0.95]
plot_percentiles = [0.95, 0.85]
pctile_color = ['blue', 'green']
pctile_linewidth = [0.8, 1.0]
cap = 110
cap_color = 'black'
main_title = 'Occupancy summary'
main_title_properties = {'loc': 'center', 'fontsize':20}
subtitle = 'Summer 2024 analysis'
subtitle_properties = {'loc': 'center'}
xlabel = ''
ylabel = 'Patients'

# Optional plotting related inputs

# Use legacy function interface
hills = hm.make_hills(scenario_name=scenario_name, data=ssu_stops_df,
                      in_field=in_field_name, out_field=out_field_name,
                      start_analysis_dt=start_date, end_analysis_dt=end_date,
                      cat_field=cat_field_name,
                      bin_size_minutes=bin_size_minutes,
                      csv_export_path=csv_export_path,
                      plot_export_path=plot_export_path, plot_style = plot_style,
                      percentiles=percentiles, plot_percentiles=plot_percentiles,
                      pctile_color=pctile_color, pctile_linewidth=pctile_linewidth,
                      cap=cap, cap_color=cap_color,
                      main_title=main_title, main_title_properties=main_title_properties,
                      subtitle=subtitle, subtitle_properties=subtitle_properties,
                      xlabel=xlabel, ylabel=ylabel
                     )

hills#

Hillmaker

hillmaker.hills.compute_hills_stats(scenario)#

Compute occupancy, arrival, and departure statistics by category, time bin of day and day of week.

Main function that first calls bydatetime.make_bydatetime to calculate occupancy, arrival and departure values by date by time bin and then calls summarize.summarize to compute the summary statistics.

Parameters:: scenario (Scenario) –
Returns:: The bydatetime DataFrames and all summary DataFrames.
Return type:: dict of DataFrames

hillmaker.hills.export_bydatetime(bydt_dfs, scenario_name, export_path)#

Export bydatetime DataFrames to csv files.

Parameters:

bydt_dfs (dict of DataFrames) – Output from make_hills to be exported
scenario_name (str) – Used in output filenames
export_path (str or Path) – Destination path for exported csv files

hillmaker.hills.export_summaries(summary_all_dfs, scenario_name, export_path, temporal_key)#

Export occupancy, arrival, and departure summary DataFrames to csv files.

Parameters:

summary_all_dfs (dict of DataFrames) – Output from make_hills to be exported
scenario_name (str) – Used in output filenames
export_path (str) – Destination path for exported csv files
temporal_key (str) – ‘nonstationary’ or ‘stationary’

hillmaker.hills.get_bydatetime_df(hills: dict, by_category: bool = True)#

Get summary dataframe

Parameters:

hills (dict) – Created by make_hills
by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.

Return type:

DataFrame

hillmaker.hills.get_los_plot(hills: dict, by_category: bool = True)#

Get length of stay histogram from length of stay summary

Parameters:

hills (dict) – Created by make_hills
by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.

Return type:

plot object from matplotlib

hillmaker.hills.get_los_stats(hills: dict, by_category: bool = True)#

Get stats from length of stay summary

Parameters:

hills (dict) – Created by make_hills
by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.

Return type:

pandas Styler object

hillmaker.hills.get_plot(hills: dict, flow_metric: str = 'occupancy', day_of_week: str = 'week')#

Get plot object for specified flow metric and whether full week or specified day of week.

Parameters:

hills (dict) – Created by make_hills
flow_metric (str) – Either of ‘arrivals’, ‘departures’, ‘occupancy’ (‘a’, ‘d’, and ‘o’ are sufficient). Default=’occupancy’
day_of_week (str) – Either of ‘week’, ‘Sun’, ‘Mon’, ‘Tue’, ‘Wed’, ‘Thu’, ‘Fri’, ‘Sat’. Default=’week’

Return type:

plot object from matplotlib

hillmaker.hills.get_summary_df(hills: dict, flow_metric: str = 'occupancy', by_category: bool = True, stationary: bool = False)#

Get summary dataframe

Parameters:

hills (dict) – Created by make_hills
flow_metric (str) – Either of ‘arrivals’, ‘departures’, ‘occupancy’ (‘a’, ‘d’, and ‘o’ are sufficient). Default=’occupancy’
by_category (bool) – Default=True corresponds to category specific statistics. A value of False gives overall statistics.
stationary (bool) – Default=False corresponds to the standard nonstationary statistics (i.e. by TOD and DOW)

Return type:

DataFrame

API Reference

Contents

API Reference#

Scenario#

legacy#

hills#