Tools

mswh.tools.plots module

class mswh.tools.plots.Plot(title='', label_h='Time [h]', label_v='Component performance', data_headers=None, save_image=True, legend=True, outpath='', duration_curve=False, boxmode='group', notebook_mode=False, width=1200, height=800, fontsize=28, legend_x=0.4, legend_y=1.0, margin_l=200.0, margin_b=200.0)

Bases: object

Creates and saves plots to visualize and correlate arrays, usually timeseries

Parameters:

title: str

Plot title

data_headers: list

A list of labels in the same order as the corresponding data If None the labels will be the df column labels, or integer indices if a list got provided

label_h: str

Horizontal axis label

label_v: str

Vertical axis label

legend: boolean

Plot the legend or not

save_image: boolean

If True saves the created image with either a given or default path and filename. Supported file types are ‘png’ and ‘pdf’, as specified in the filename.

duration_curve: boolean

If True it sorts the columns (df or arrays) and plots the duration_curve, returns a duration_curve metric as a real

outpath: string or ‘’ (for current directory)

Path to save the png image of the plot

boxmean: True, False, ‘sd’, ‘Only Mean’

notebook_mode: boolean

Plot in the notebook if True

width: int

Image width

height: int

Image height

fontsize: int

Axis label font size

Returns:

fig: plotly figure if self.interactive

else True

box(dfs, plot_cols=None, groupby_cols=None, df_cat=None, outfile='box.png', boxmean=False, colors=['#3D9970', '#FF4136', '#FF851B'], title='Energy Use', boxpoints='outliers')

Creates box plots for the chosen plot_col and can group plots by the groupby_col.

Parameters:

dfs: list of dfs

df_cat: list of str

Indicator of the category carried by the dfs (E.g. the dfs differ by housing type)

plot_col: list of columns to plot, one from each df in

dfs. If multiple dfs are passed, the values will be shown as groups on the plot

groupby_cols: list of cols to use as x axis, from each

df. Use the same column if it has the same elements. Use None if x axis category not used

boxpoints: False, ‘all’, ‘outliers’, ‘suspectedoutliers’

See https://plot.ly/python/reference/#box

Returns:

fig: plotly figure if self.interactive

else True

scatter(data, outfile='scatter.png', modes='lines+markers')

Creates a scatter plot

Parameters:

data: array/list, pd series, list of arrays/lists, pd df

Provide a list or arrays/lists or a pandas dataframe. The variables should be ordered in pairs such that each odd variable in the list/first column in the df gets assigned to the horizontal axis, each even variable to the vertical axes. Each pair needs to have the same length, but pairs can be of a different length.

outfile: str

Filename, include .png, .png .pdf

modes: str or list of str

‘markers’, ‘lines’, ‘lines + markers’ or a list of the above to assign to each plot (one string in a list for each pair of data)

Returns:

fig: plotly figure if self.interactive

else True

series(data, index_in_a_column=None, outfile='series.png', modes='lines+markers')

Plots all series data against either the index or the first provided series. It can sort the data and plot the duration_curve.

Parameters:

data: array/list, pd series, list of arrays/lists, pd df

Provide an array or a list if plotting a single variable. If plotting multiple variables provide a list of arrays or a pandas dataframe.

Horizontal axis corresponds to:

• if pd df: the index of the dataframe or the first columns of the dataframe

• if list or arrays/lists: a range of array length of the first array/list in the list

All arrays in the list need to have the same length.

index_in_a_column: boolean

Horizontal axis labels If None, dataframe index is used, otherwise pass a column label for a column (it will not be considered as a series to plot)

outfile: str

Filename, include .png, .png .pdf

modes: str or list of str

‘markers’, ‘lines’, ‘lines+markers’ or a list of the above to assign to each column of data, excluding the first column if index_in_a_column is not None

Returns:

fig: plotly figure if self.interactive

else True

mswh.tools.unit_converters module

class mswh.tools.unit_converters.UnitConv(x_in, scale_in=1.0, scale_out=1.0)

Bases: object

Unit conversions using conversion parameters from ASHRAE Fundamentals 2017.

Parameters:

x_in: float, array

Input value to be converted to a desired unit

scale_in: str or 1.

Scale of the input value, options: ‘k’, ‘kilo’, ‘mega’, ‘million’, ‘M’, ‘MM’, ‘giga’, ‘G’, ‘tera’, ‘T’, ‘peta’, ‘P’, ‘milli’, ‘micro’. Default: 1.

scale_out: str or 1.

Scale of the input value, options: ‘k’, ‘kilo’, ‘mega’, ‘million’, ‘M’, ‘MM’, ‘giga’, ‘G’, ‘tera’, ‘T’, ‘peta’, ‘P’, ‘milli’, ‘m’, ‘micro’. Default: 1.

Examples:

To convert temperature from degF to degC

>>> t_in_degC = UnitConv(t_in_degF).degF_degC(unit_in='degF')

To convert power in hp to kW:

>>> p_in_kW = UnitConv(p_in_hp, scale_out='kilo').hp_W(unit_in='hp')

To convert energy from GJ to MMBtu:

>>> e_MMBtu = UnitConv(e_GJ, scale_in='G', scale_out='MM').Btu_J(unit_in='J')

Btu_J(unit_in='Btu')

Converts work / energy / heat content between Btu and joule

Parameters:

x: float, array

Input value

unit_in: string, options: ‘Btu’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

Wh_J(unit_in='J')

Converts work / energy / heat content between watthour and joule

Parameters:

x: float, array

Input value

unit_in: string, options: ‘Wh’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

degC_K(unit_in='degC')

Converts temperature between degree Celsius and Kelvin

Parameters:

unit_in: string, options: ‘K’, ‘degC’

Unit of the input value

Returns:

x_out: float, array

Output value

degF_degC(unit_in='degF')

Converts temperature between degree Fahrenheit and Celsius

Parameters:

unit_in: string, options: ‘degF’, ‘degC’

Unit of the input value

Returns:

x_out: float, array

Output value

ft_m(unit_in='ft')

Converts length between foot and meter

Parameters:

x: float, array

Input value

unit_in: string, options: ‘Wh’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

hp_W(unit_in='hp')

Converts power between watt and horsepower

Parameters:

unit_in: string, options: ‘hp’, ‘W’

Unit of the input value

Returns:

x_out: float, array

Output value

m3_gal(unit_in='gal')

Converts volume between cubic meter and gallon

Parameters:

unit_in: string, options: ‘m3’, ‘gal’

Unit of the input value

Returns:

x_out: float, array

Output value

m3perh_m3pers(unit_in='m3perh')

Converts volume flow between cubic meter per hour and cubic meter per second

Parameters:

x: float, array

Input value

unit_in: string, options: ‘Wh’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

sqft_m2(unit_in='sqft')

Converts area between square foot and square meter

Parameters:

x: float, array

Input value

unit_in: string, options: ‘Wh’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

therm_J(unit_in='therm')

Converts work / energy / heat content between therm and joule

Parameters:

x: float, array

Input value

unit_in: string, options: ‘therm’, ‘J’

Unit of the input value

Returns:

x_out: float, array

Output value

class mswh.tools.unit_converters.Utility(quantity_in)

Bases: object

Converts gas or electricity consumption into commonly used units.

Parameters:

quantity_in: float, array

Quantity to be converted. E.g. gas use in kJ

gas(unit_in='kJ', unit_out='MMBtu')

Converts gas consumption.

Parameters:

unit_in: string

Units of the input quantity that needs to be converted. Options: ‘kWh’, ‘kJ’

unit_out: string

Desired output unit Options: ‘m3’, ‘cf’, ‘therm’, ‘MMBtu’

Returns:

gas_use: float

Gas use in output units