App stage

AppStageCompute ¶

add_alert ¶

add_alert(headline, message, alert_style, visible=True, var_name=None)

Adds an alert banner to the report.

Parameters:

Name	Type	Description	Default
`headline` ¶	`str`	Represents the headline of the alert in bold.	required
`message` ¶	`str`	Represents the message the user would like to inform the user of.	required
`alert_style` ¶	`str`	Allowable entries: ["normal", "info", "success", "warning", "error"].	required
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True.	`True`
`var_name` ¶	`str`	Optional, if None, then defaults to a GUID. Default = None.	`None`

Returns:

Type	Description
`None`	None

Examples:

self.add_alert(
    headline="Input Warning",
    message="Input value outside scope of calculation",
    alert_style="warning"
)

add_calc ¶

add_calc(var_name, fullname, equation=None, reference='', unit='', format_str='{:.4g}', visible=True, override_previous=False, set_value=None)

Adds an input parameter to the calculation report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`equation` ¶	`str`	The equation should be input as string with the parameters in the equation tagged with {} brackets either side.	`None`
`reference` ¶	`str`	Reference to the code, website or book. Default = "".	`''`
`unit` ¶	`str`	Should typically be "MPa" or other SI unit. Default = "".	`''`
`format_str` ¶	`str`	Default = '{:.3g}' automatically switches between fixed-point and scientific notation depending on the value, the 3 in this instance represents the number of digits to render. If you want to enforce scientific notation use the following format '{:.3e}'. If you wish to use a fixed decimal point value use '{:.3f}'. Other formats are permitted and are according to standard Python formatters. More information can be found at: https://peps.python.org/pep-3101/#standard-format-specifiers	`'{:.4g}'`
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True	`True`
`override_previous` ¶	`bool`	Allows the values of this calculation to be overridden.	`False`
`set_value` ¶	`str or float`	Sets the value of the variable without an equation. This can be set only if "equation=None".	`None`

Returns:

Type	Description
	None

Examples:

self.add_calc(var_name="A", fullname="Area", unit="mm^2", equation="{width}*{length}")

add_collapsible ¶

add_collapsible(title='', end=False, visible=True)

Adds a collapsible element to the report. A Collapsible element will create a hidden/expandable section with the inputs defined within two add_collapsible calls.

Parameters:

Name	Type	Description	Default
`title` ¶	`str`	Gives a title to the collapsible element. Must be given in the start of a collapsible group.	`''`
`end` ¶	`bool`	Marks the end of a collapsible element if end = True. If there was an add_collapsible element with end = False set before, then there must be an add_collapsible(end=True) before the end of register_inputs().	`False`
`visible` ¶	`bool`	Set False to hide this collapsible element in the "Detailed output" section.	`True`

Returns:

Type	Description
	None

Examples:

self.add_collapsible(title="Rectangle Dimensions")

self.input_parameter(
    bind_ui=UiNumberInput(min_val=1, max_val=100, step=1.0)),
    var_name="h", fullname="Height of Rectangle")
self.input_parameter(
    bind_ui=UiNumberInput(min_val=1, max_val=100, step=1.0)),
    var_name="b",
    fullname="Width of Rectangle")
self.add_collapsible(end=True)

add_dataframe ¶

add_dataframe(var_name, dataframe, title='', show_index=False)

Adds a dataframe to the report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	Provide a unique var_name so that it can be added to the report and referenced in the summary.	required
`dataframe` ¶	`DataFrame`	Provide a Pandas dataframe to be bound to the report.	required
`title` ¶	`str`	Provide the fullname or title of the table.	`''`
`show_index` ¶	`bool`	Default = False, state whether the index items should be displayed in the table.	`False`

Returns:

Type	Description
`None`	None

Examples:

import pandas as pd

table1 = pd.DataFrame({"x":[1,2,3,4,5], "y":[6,7,8,9,10]})
self.add_dataframe(var_name="a_dataframe", dataframe=table1)

add_decision ¶

add_decision(calc_var_name, decision_var_name, headlines=None, messages=None, role_styles=None, util_bands=None, heading_style='h4', show_base_calc=False)

Adds a conditional decision to the calculation object that has been added to the report.

Parameters:

Name	Type	Description	Default
`calc_var_name` ¶	`str`	This should be the unique identifier of the utilisation that you would like to style. The equation must return a numerical result.	required
`decision_var_name` ¶	`str`	This should be the unique identifier for the decision box itself.	required
`headlines` ¶	`Optional[List[str]]`	This will appear at the head of the utilisation banner in the report. Default = ["Pass", "Pass", "Fail"].	`None`
`messages` ¶	`Optional[List[str]]`	This will appear below the calculation used to determine the utilisation. Default = None.	`None`
`role_styles` ¶	`Optional[List[str]]`	List of alert styles that are synchronous with the "util_bands". Allowable entries: ["normal", "info", "success", "warning", "error"]. Default = ["success", "warning", "error"].	`None`
`util_bands` ¶	`Optional[List[float, int]]`	Must be greater than zero and list muse be same length / corresponding with "role_styles". Default = [0.95, 1.0, math.inf]. i.e. result<=0.95 = "success", 0.95<result<=1.0 = "warning", 1.0<result<=infinity = "danger".	`None`
`heading_style` ¶	`str`	Must be one of the following h1, h2, h3, h4 or h5. Default = h4.	`'h4'`
`show_base_calc` ¶	`bool`	(To be deprecated) This parameter will be deprecated. Default=False	`False`

Returns: None

Examples:

self.add_calc(var_name ="UBend_z", fullname="Minor axis bending utilisation", unit="%", equation="100 *
{km}*{S11_MyEd} / {fmyd} + {S11_MzEd} / {fmzd}", format_str="{:.2f}")
self.add_decision(calc_var_name="UBend_z", util_bands=[95, 100, math.inf], messages=["", 'Fails check',
'Fails check'], decision_var_name="decision_UBend_z")

add_download ¶

add_download(var_name, file=None, label='Download File', tooltip_text='', **kwargs)

Adds a download component to the detailed results section of the report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`file` ¶	`BaseFile`	The file to be downloaded.	`None`
`label` ¶	`str`	The label of the download button. Default = "Download File".	`'Download File'`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`

Returns:

Type	Description
	None

add_format_option ¶

add_format_option(page_break_before)

Adds text element to the calculation report.

Parameters:

Name	Type	Description	Default
`page_break_before` ¶	`bool`	Provides a page break before the current section of the report.	required

Returns:

Type	Description
`None`	None

Examples:

self.add_format_option(add_page_break_before=True)

add_image ¶

add_image(cb_image=None, **kwargs)

Adds an image to the header of the calculation. Images will only be rendered in "html" type output. Supports images in the following formats ".png", ".jpg", ".jpeg". The images should be saved in a folder called "resources". The file will only be discovered if it is located within a folder called "resources" all files which are not in the "resources" folder will not be discovered. Avoid saved ancillary files such as ".pdf" files and other resources in this folder as these files will contribute to your file storage space.

Parameters:

Name	Type	Description	Default
`cb_image` ¶	`Optional[CbImage]`	(CbImage): Object containing the relevant data to render an image.	`None`

Returns:

Type	Description
	None

Examples:

'''
.
├── shared/
│   └── images/
│       └── shared_image.jpg
└── apps/
    └── my_app/
        ├── my_images/
        │   └── local_image.jpg
        └── my_app.py
'''
# Adding a local image
image_renderer = ImageRenderExpandable(is_expanded=True)
local_image = CbImage(
    var_name = "my_local_image",
    filepath="my_images/local_image.png",
    image_renderer=image_renderer,
    image_width=400,
    image_caption="Local Image",
    is_local=True
    ),
self.add_image(local_image)
# Adding a shared image
shared_image = CbImage(
    var_name = "my_shared_image",
    filepath="images/shared_image.png",
    image_renderer=image_renderer,
    image_width=400,
    image_caption="Shared Image",
    is_local=False
    ),
self.add_image(shared_image)

add_matplotlib ¶

add_matplotlib(var_name, fig, plot_width, fullname=None, visible=True, is_expanded=True, plot_description='')

Adds a matplotlib figure to the report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	Provide a unique var_name so that it can be added to the report and referenced in the summary.	required
`fig` ¶	`Figure`	Provide a single figure to publish within the report.	required
`plot_width` ¶	`str`	The display image size in pixels. Recommended max width is 450.	required
`fullname` ¶	`Optional[str]`	A verbose name for the var_name.	`None`
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True.	`True`
`is_expanded` ¶	`bool`	Set to `False` if you want the container to be minimized by default. Default = True.	`True`
`plot_description` ¶	`str`	The text attributed to the image. Default = "".	`''`

Returns:

Type	Description
`None`	None

Examples:

import matplotlib.pyplot as plt

fig, ax = plt.subplots()
ax.bar(['apple', 'grape', 'banana'], [40, 100, 30])
self.add_matplotlib(var_name="a_matplotlib_figure",
                    fig=fig,
                    plot_description="This is the caption",
                    plot_width=450)

add_plotly ¶

add_plotly(var_name, fig, fullname=None, title='', plot_description='', new_window_only=False)

Adds a plotly figure to the report. The default width of a plot is set to 700 pixels is set on the graph - use the plotly layout properties to update the width and height.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	Provide a unique var_name so that it can be added to the report and referenced in the summary.	required
`fullname` ¶	`Optional[str]`	A verbose name for the var_name.	`None`
`fig` ¶	`Figure`	Provide a single figure to publish within the report.	required
`title` ¶	`str`	The title header of the plot.	`''`
`plot_description` ¶	`str`	The description of the plot.	`''`
`new_window_only` ¶	`bool`	If True the plot will only show in a new window and not in the report mode. Default = False.	`False`

Returns:

Type	Description
`None`	None

Examples:

import plotly.graph_objects as px
import numpy as np

plot = px.Figure(data=[px.Scatter(
    x = np.random.randint(1,101,100),
    y = np.random.randint(1,101,100),
    mode = 'markers',)
])
self.add_plotly(var_name="plot1", fig=plot)

add_plotly_many ¶

add_plotly_many(var_name, figs, fullname=None, titles=None, plot_descriptions=None, new_window_only=False)

Adds a plotly figure to the report. The default width of a plot is set to 700 pixels is set on the graph - use the plotly layout properties to update the width and height.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	Provide a unique var_name so that it can be added to the report and referenced in the summary. NB: All graphs will be exported to the report as a result.	required
`fullname` ¶	`str`	A verbose name to describe the collection of plots.	`None`
`figs` ¶	`List[Figure]`	Provide a list of figures to publish within the report.	required
`titles` ¶	`Optional[List[str]]`	The list of titles relating to each of the plots. Default = None.	`None`
`plot_descriptions` ¶	`Optional[List[str]]`	The list of description relating to each of the plots. Default = None.	`None`
`new_window_only` ¶	`bool`	If True the plot will only show in a new window and not in the report mode. Default = False.	`False`

Returns:

Type	Description
`None`	None

Examples:

import plotly.graph_objects as px
import numpy as np

plot = px.Figure(data=[px.Scatter(
    x = np.random.randint(1,101,100),
    y = np.random.randint(1,101,100),
    mode = 'markers',)
])
list_of_plots = [plot, plot, plot]
self.add_plotly_many(var_name="multiple_plots", figs=list_of_plots)

add_text ¶

add_text(text, style=None, visible=True, page_break_before=None, tooltip_text='')

Adds a text element to the calculation report.

Parameters:

Name	Type	Description	Default
`text` ¶	`str`	Provide the string to represent within the calculation report.	required
`style` ¶	`str`	Provide either ["p", "h1", "h2", "h3", "h4", "h5", "h6"]. If no style is provided, the text will be rendered in Markdown.	`None`
`page_break_before` ¶	`bool`	Optional. Default = False for all format styles other than "h1". If set to True print formatting of the report will break before. Only relevant for "html" report style. Default = "".	`None`
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True.	`True`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`

Returns:

Type	Description
`None`	None

Examples:

self.add_text(text="Sample Calculation Heading", style="h1", page_break_before=False)

add_visualizer ¶

add_visualizer(var_name, fullname, visualizer, title='', background_color_rgb=(1, 1, 1))

Adds a visualizer to the Visualizers section of the report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`visualizer` ¶	`VisualizerGeneric`	Add the Visualizer object.	required
`title` ¶	`str`	Title of the Visualizer object.	`''`
`background_color_rgb` ¶	`Tuple[int, int, int]`	Background color of the visualizer in RGB. Default "(1, 1, 1)".	`(1, 1, 1)`

Returns:

Type	Description
	None

exec_app ¶

exec_app(inner_app, map_values=None, map_objs=None, return_vars=None, var_names_to_render=None, show_inner_app_results=True, allow_override=False)

Runs an application from the library given the inputs provided in map_values or map_objs which maps the resulting values from the objects already created. Use return_vars to map the variables created during the inner_app execution to new objects.

Parameters:

Name	Type	Description	Default
`inner_app` ¶	`Type[AppStageCompute]`	This is the app to be loaded as an instance into the app.	required
`map_values` ¶	`Dict[str, object] \| None`	Dictionary with the app's input arguments. e.g. {"fck":30, "fcm":50}. Default = None.	`None`
`map_objs` ¶	`Dict[str, str] \| None`	Map the to the . This can be useful if you have parameters in the host app that you want to map as inputs to the child app. Default = None.	`None`
`return_vars` ¶	`Dict[str, str] \| None`	Map the variable to a new after the inner app finished execution. e.g. {"fck_host": "fck_inner"} creates a copy of "fck_inner" from the inner app, and assigns it to a new variable "fck_host" in the host app. Default = None.	`None`
`var_names_to_render` ¶	`List[str] \| None`	List with the variables (output) names to include in the report. If "None" all variable names will be rendered. If you want to exclude all output, enter and empty list. Default=None.	`None`
`show_inner_app_results` ¶	`bool`	Show the calculations of the loaded app in the report. Default=True.	`True`
`allow_override` ¶	`bool`	[DEPRECATED]	`False`

Returns:

Type	Description
`None`	None

Examples:

self.exec_app(
    inner_app=EC2_ConcreteProperties,
    map_values={"fck": 30},
    return_vars={"Ecm": "Ecm", "fcm":"fcm"},
    var_names_to_render=["fcm"]
)

expose_all_parameters ¶

expose_all_parameters()

Exposes all parameters input parameters in the order that they are defined within the "register_parameters" section. If a custom order is required or to insert images between parameters the "expose_parameter" function may be more useful in this scenario.

Returns:

Type	Description
`None`	None

Examples:

self.expose_all_parameters()

expose_parameter ¶

expose_parameter(var_name)

Exposes the parameter defined within the current host application.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The string that matches the parameter name.	required

Returns: None

Examples:

self.expose_parameter(var_name="f_ck")

get_result ¶

get_result(var_name)

Retrieves the variable result that is stored within the calculation report object.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The string that matches the parameter name.	required

Returns:

Type	Description
	Str \| Numeric \| pd.DataFrame: Provides the result of the argument requested, either as a
	primitive numerical, string or table-like (DataFrame) object.

Examples:

self.get_result("fck")

get_result_from_stage ¶

get_result_from_stage(stage_index, var_name, default)

Retrieves the result from a variable if available from the staged specified by stage_index. If the variable is not available, the default variable will be returned.

Parameters:

Name	Type	Description	Default
`stage_index` ¶	`int`	Index of the stage to get the result from.	required
`var_name` ¶	`str`	The string that matches the parameter name.	required
`default` ¶	`Any`	Default value required if the specified stage has not provided a result.	required

Returns:

Type	Description
	Str or Numeric: Provides the result of the argument requested, either as a primitive numeric or string
	object.

Examples:

self.get_result_from_stage(stage_index=0, var_name="fck")

get_result_history ¶

get_result_history(var_name)

AppStage.get_result_history Retrieves the variable result history that is stored within the calculation report object.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The string that matches the parameter name.	required

Returns:

Type	Description
	List[str] or List[float]: Provides the result of the argument requested,
	either as a primitive numeric or string.

Examples:

self.get_result_history("fck")

input_file_upload ¶

input_file_upload(var_name, fullname, visible=True, tooltip_text='', description='', allowed_extensions=None, label=None, max_size_mb=20.0, is_multiple=False, is_dynamic=False)

AppStage.input_file_upload Adds a fragment_content file to the report data. Low-level function, returns the bytes of the input file.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`visible` ¶	`bool`	This can be set to False if the component should be calculated / evaluated but not be displayed in the body of the report. Default = True.	`True`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`
`description` ¶	`str`	Text to describe the documentation for the parameter. Only shown in the "App Details" section.	`''`
`allowed_extensions` ¶	`List[str]`	List with the allowed extensions for this input, if None then all extensions are allowed. Default = None.	`None`
`label` ¶	`str`	Text to be displayed on the file uploader.	`None`
`max_size_mb` ¶	`Union[int, float]`	Maximum allowed file size in Megabytes per file. Must be less than 200 Megabytes. Default = 20.0.	`20.0`
`is_multiple` ¶	`bool`	Allow multiple files to be uploaded. Default = False.	`False`
`is_dynamic` ¶	`bool`	If set to True this will allow the input parameter to be dynamically created within the register_parameters section rather than the register_parameters section which is responsible for caching static input variables that are subsequently used to generate the documentation for an application. If the is_dynamic is used - it must be noted that the input properties created will not form part of the documentation as the input properties will be generated dynamically.	`False`

Returns:

Type	Description
`None \| BaseFile \| List[BaseFile]`	`None` if no file is selected, a `BaseFile` if `is_multiple=False` or a list of `BaseFile` if `is_multiple=True`.

Examples:

self.input_file_upload(
    var_name="excel_input",
    fullname="Longer description about what this file or files are used for",
    label="Click to upload Excel file",
    allowed_extensions=["xlsx"],
    is_multiple=False,
    max_size_mb=1.0
)

input_filter_param ¶

input_filter_param(file_name, filter_columns, default_filter_spec, var_name, visible=True, is_local=True, fullname='', reference='', description='', tooltip_text='')

Adds an input parameter to the calculation report.

Parameters:

Name	Type	Description	Default
`file_name` ¶	`str`	The name of the csv resource to load (including the extension, i.e. file.csv).	required
`filter_columns` ¶	`List[str]`	List of the column names from the csv to filter the data on.	required
`default_filter_spec` ¶	`List[str]`	A starting entry that must be provided to the filter.	required
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True	`True`
`is_local` ¶	`bool`	Specifies if the resource is located locally to the app python file. Otherwise, the app will look within global resources folder for the file. Default = True.	`True`
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	`''`
`reference` ¶	`str`	Reference to the code, website or book. Default = "".	`''`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`
`description` ¶	`str`	Text to describe the documentation for the parameter.	`''`

Returns:

Type	Description
	None

input_multi_selection ¶

input_multi_selection(var_name, fullname, list_vals, default=None, is_numeric=False, is_dynamic=False, visible=True, description='', tooltip_text='')

Adds a multi-selection input type.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`list_vals` ¶	`List`	A list of string values which the user can select from.	required
`default` ¶	`List`	List with the items selected by default. Default = None (no items selected by default).	`None`
`is_numeric` ¶	`bool`	Default = false, therefore it is assumed to be a string, otherwise a numerical value (i.e. float). Default = False.	`False`
`is_dynamic` ¶	`bool`	If set to True this will allow the input parameter to be dynamically created within the register_parameters section rather than the register_parameters section which is responsible for caching static input variables that are subsequently used to generate the documentation for an application. If the is_dynamic is used - it must be noted that the input properties created will not form part of the documentation as the input properties will be generated dynamically.	`False`
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True	`True`
`description` ¶	`str`	Text to describe the documentation for the parameter.	`''`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`

Returns:

Type	Description
	None

Examples:

self.input_multi_selection(var_name="a_multi_select",
                           fullname="My Multi-Select Input",
                           list_vals=["opt1", "opt2", "opt3"],
                           default=["opt2", "opt3"])

input_parameter ¶

input_parameter(var_name, fullname, bind_ui, reference='', unit='', format_str='{:.2f}', visible=True, tooltip_text='', description='', is_dynamic=False, helper_images=None)

AppStage.input_parameter Adds an input parameter to the calculation report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`bind_ui` ¶	`UiGeneric`	Add either a UI object here to ensure that custom user inputs can be bound to this value.	required
`reference` ¶	`str`	Reference to the code, website or book. Default = "".	`''`
`unit` ¶	`str`	Should typically be "MPa" or other SI unit. Default = "".	`''`
`format_str` ¶	`str`	Should be in the format '{:.2f}' or similar. Default = "{:.2f}"	`'{:.2f}'`
`visible` ¶	`bool`	This can be set to False if the component should be calculated / evaluated but not be displayed in the body of the report. Default = True.	`True`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`
`description` ¶	`str`	Text to describe the documentation for the parameter. Only shown in the "App Details" section.	`''`
`is_dynamic` ¶	`bool`	If set to True this will allow the input parameter to be dynamically created within the register_parameters section rather than the register_parameters section which is responsible for caching static input variables that are subsequently used to generate the documentation for an application. If the is_dynamic is used - it must be noted that the input properties created will not form part of the documentation as the input properties will be generated dynamically.	`False`
`helper_images` ¶	`Optional[List[CbImage]]`	Choose helper images for the input. This adds a button on the side of the input parameter which, when clicked, opens a pop-up window with the provided helper images and the input parameter itself. Default = None.	`None`

Returns:

Type	Description
	None

Examples:

self.input_parameter(
    var_name="b",
    fullname="Width of timber member",
    reference="",
    bind_ui=UiNumberInput(min_val=10, max_val=500, step=5.0, default=250),
    unit="mm"
)

input_text ¶

input_text(var_name, fullname, reference='', default='', visible=True, max_chars=100, max_rows=1, description='', tooltip_text='', is_dynamic=False)

AppStage.input_text Adds a text field input parameter to the calculation report.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`reference` ¶	`str`	Reference to the code, website or book. Default = "".	`''`
`default` ¶	`str`	The default reference value for the input string.	`''`
`visible` ¶	`bool`	This can be set to false if the equation should not be displayed in the calculation report. Default = True.	`True`
`max_chars` ¶	`int`	Specifies the maximum number of characters that the user can enter. Default = 100.	`100`
`max_rows` ¶	`int`	Specifies the maximum number of rows that the user can enter. Default = 1. Default = "".	`1`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`
`description` ¶	`str`	Text to describe the documentation for the parameter.	`''`
`is_dynamic` ¶	`bool`	If set to True this will allow the input parameter to be dynamically created within the register_parameters section rather than the register_parameters section which is responsible for caching static input variables that are subsequently used to generate the documentation for an application. If the is_dynamic is used - it must be noted that the input properties created will not form part of the documentation as the input properties will be generated dynamically.	`False`

Returns:

Type	Description
	None

Examples:

self.input_text(var_name="element_location", fullname="Location of the Element", set_value=element_location)

input_upload_db ¶

input_upload_db(fullname, var_name, visible=True, max_file_size_mb=100, description='')

Gives the user the ability to upload an SQLite database which can then subsequently be read by a following stage.

Parameters:

Name	Type	Description	Default
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True	`True`
`max_file_size_mb` ¶	`float`	This by default is set to 100MB.	`100`
`description` ¶	`str`	Text to describe the documentation for the parameter.	`''`

Returns:

Type	Description
	None

input_user_table ¶

input_user_table(var_name, fullname, col_formats, visible=True, default=None, title=None, min_rows=1, max_rows=100, is_file=False, description='', tooltip_text='')

AppStage.input_user_table Adds a table to the report that can be used to enter user data or copy data into the application from Excel.

Parameters:

Name	Type	Description	Default
`var_name` ¶	`str`	The parameter name. Should be short and concise with no white spacing.	required
`fullname` ¶	`str`	The full name of the parameter, can be descriptive.	required
`col_formats` ¶	`List[ColumnFormat]`	Provide a list of column formats for the table. The column formats define the type of data input, and other constraining parameters.	required
`visible` ¶	`bool`	Define if the component is to be made visible in the "Detailed Output" section. Default = True	`True`
`default` ¶	`List[List[]]`	Default=None. The data can be of either, string or float type. None value can be provided since default values can be generated from the information provided by the col_formats.	`None`
`title` ¶	`str`	Set a specific longer title for the input table.	`None`
`min_rows` ¶	`int`	Default=1 (>0). Specifies the minimum number of rows that should be supplied by the user. Default = 1.	`1`
`max_rows` ¶	`int`	Default=100 (>0). Specifies the maximum number of rows that can be supplied by the user. "max_rows" must be greater than or equal to "min_rows". NB: min_rows and max_rows can be the same value, therefore fixing the total number of rows. Default = 100.	`100`
`is_file` ¶	`bool`	True if the table should be imported as a csv file or if the user should manually input data to the table. For tables larger than a few rows, import from a csv file is recommended.	`False`
`description` ¶	`str`	Text to describe the documentation for the parameter.	`''`
`tooltip_text` ¶	`str`	Text to display as a tooltip in the webapp. Default = "".	`''`

Returns:

Type	Description
`None`	None

Examples:

col1 = ColumnFormat(data_type="string_type", heading="name")
col2 = ColumnFormat(data_type="float_type", heading="value")
self.input_user_table(fullname="A Table", var_name="table1", col_formats=[col1, col2])

load_csv_as_df ¶

load_csv_as_df(file_name, is_local=True)

Load the csv from the app resource collection.

Parameters:

Name	Type	Description	Default
`file_name` ¶	`str`	The filename of the resource to load. Accepts only .csv files.	required
`is_local` ¶	`bool`	If local the file should reside within the parent folder of this app. Alternatively, this can be set to False and the file should be located within the "shared" folder.	`True`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: Returns the file as a Pandas.Dataframe object.

Examples:

self.load_csv_as_df(file_name="table.csv")

load_file_as_bytes ¶

load_file_as_bytes(file_name, is_local=True)

Load the file as bytes.

Parameters:

Name	Type	Description	Default
`file_name` ¶	`str`	The filename of the resource to load.	required
`is_local` ¶	`bool`	If local the file should reside within the parent folder of this app. Alternatively, this can be set to False and the file should be located within the "shared" folder.	`True`

Returns: bytes: Returns the file as bytes.

Examples:

'''
An example folder structure below:
.
├── shared/
│   └── db/
│       └── sql_lite_table.db
└── apps/
    └── my_app/
        ├── local_data/
        │   └── local_excel_file.xlsx
        └── my_app.py
'''
self.load_file_as_bytes(
    file_name="db/sql_lite_table.db",
    local_resource=False
)
self.load_file_as_bytes(
    file_name="local_data/local_excel_file.xlsx",
    local_resource=True
)

map_vars_from_stage ¶

map_vars_from_stage(stage_index, var_mapping, var_names_to_render=None)

Maps variables from a previous stage defined by "stage_index" to the current stage using the mapping defined "var_mapping". This mapping creates a copy of the objects in the current stage. This function is only available in multi-stage apps.

Parameters:

Name	Type	Description	Default
`stage_index` ¶	`int`	Index of the stage to get the results from.	required
`var_mapping` ¶	`Dict[str, str]`	Map the variable to a new . e.g. {"area_stage1": "area_stage0"} creates a copy of "area_stage0" from the stage with index "0" and assigns it to a new variable "area_stage1" in the current stage.	required
`var_names_to_render` ¶	`List[str] \| None`	List with the variables (output) names to include in the report. If "None" all variable names will be rendered. If you want to exclude all output, enter and empty list. Default=None.	`None`

Returns:

Type	Description
	None

Examples:

self.map_vars_from_stage(
    stage_index=0,
    var_mapping={"area_stage1": "area_stage0"}
)

ref_to_summary ¶

ref_to_summary(ref_var_name)

Adds the chart calculation, decision, to the summary tab of the report.

Parameters:

Name	Type	Description	Default
`ref_var_name` ¶	`str`	Provide the string that matches the parameter name.	required

Returns: None

Examples:

self.ref_to_summary("fck")

run_batch ¶

run_batch(inner_app, df, var_names_to_append)

Runs other applications within your app collection in a batch mode. The variables provided in the form of a pandas dataframe.

Parameters:

Name	Type	Description	Default
`inner_app` ¶	`Type[AppStageCompute]`	Provide the type of the app to be executed within this host app	required
`df` ¶	`Dataframe`	Provide a dataframe of all the input variables required to execute the "inner_app". Each column should be named identically with the variable name. NB: Default variables will be used if not all the parameters are supplied in the dataframe.	required
`var_names_to_append` ¶	`List[str]`	Provide a list of strings that are the variable names generated when the "inner_app" is executed the resulting values are appended to the dataframe.	required

Returns:

Type	Description
`DataFrame`	pd.Dataframe

App stage

AppStageCompute ¶

add_alert ¶

headline ¶

message ¶

alert_style ¶

visible ¶

var_name ¶

add_calc ¶

var_name ¶

fullname ¶

equation ¶

reference ¶

unit ¶

format_str ¶

visible ¶

override_previous ¶

set_value ¶

add_collapsible ¶

title ¶

end ¶

visible ¶

add_dataframe ¶

var_name ¶

dataframe ¶

title ¶

show_index ¶

add_decision ¶

calc_var_name ¶

decision_var_name ¶

headlines ¶

messages ¶

role_styles ¶

util_bands ¶

heading_style ¶

show_base_calc ¶

add_download ¶

var_name ¶

file ¶

label ¶

tooltip_text ¶

add_format_option ¶

page_break_before ¶

add_image ¶

cb_image ¶

add_matplotlib ¶

var_name ¶

fig ¶

plot_width ¶

fullname ¶

visible ¶

is_expanded ¶

plot_description ¶

add_plotly ¶

var_name ¶

fullname ¶

fig ¶

title ¶

plot_description ¶

new_window_only ¶

add_plotly_many ¶

var_name ¶

fullname ¶

figs ¶

titles ¶

plot_descriptions ¶

new_window_only ¶

add_text ¶

text ¶

style ¶

page_break_before ¶

visible ¶

tooltip_text ¶

add_visualizer ¶

var_name ¶

fullname ¶

visualizer ¶

title ¶

background_color_rgb ¶

exec_app ¶

`headline` ¶

`message` ¶

`alert_style` ¶

`visible` ¶

`var_name` ¶

`var_name` ¶

`fullname` ¶

`equation` ¶

`reference` ¶

`unit` ¶

`format_str` ¶

`visible` ¶

`override_previous` ¶

`set_value` ¶

`title` ¶

`end` ¶

`visible` ¶

`var_name` ¶

`dataframe` ¶

`title` ¶

`show_index` ¶

`calc_var_name` ¶

`decision_var_name` ¶

`headlines` ¶

`messages` ¶

`role_styles` ¶

`util_bands` ¶

`heading_style` ¶

`show_base_calc` ¶

`var_name` ¶

`file` ¶

`label` ¶

`tooltip_text` ¶

`page_break_before` ¶

`cb_image` ¶

`var_name` ¶

`fig` ¶

`plot_width` ¶

`fullname` ¶

`visible` ¶

`is_expanded` ¶

`plot_description` ¶

`var_name` ¶

`fullname` ¶

`fig` ¶

`title` ¶

`plot_description` ¶

`new_window_only` ¶

`var_name` ¶

`fullname` ¶

`figs` ¶

`titles` ¶

`plot_descriptions` ¶

`new_window_only` ¶

`text` ¶

`style` ¶

`page_break_before` ¶

`visible` ¶

`tooltip_text` ¶

`var_name` ¶

`fullname` ¶

`visualizer` ¶

`title` ¶

`background_color_rgb` ¶

`inner_app` ¶

`map_values` ¶

`map_objs` ¶

`return_vars` ¶

`var_names_to_render` ¶

`show_inner_app_results` ¶

`allow_override` ¶

`var_name` ¶

`var_name` ¶

`stage_index` ¶

`var_name` ¶

`default` ¶

`var_name` ¶

`var_name` ¶

`fullname` ¶

`visible` ¶