alt.hst.gui.custom_plot Module#

class Channel(varname: str, label: str, channelType: ChannelTypes)#

Bases: object

getLabel() → str#

Get the label of the selected channel item.

Returns:: The label of the channel.
Return type:: str

getType() → ChannelTypes#

Get the type of the selected channel item.

Returns:: The type of the channel.
Return type:: ChannelTypes

getVarname() → str#

Get the varname of the selected channel item.

Returns:: The varname of the channel.
Return type:: str

class ChannelConfig#

Bases: object

addSection(title: str) → ChannelSection#

Add an additional section (tab) to the channel selection widget. If a section with the same name already exists, it will be replaced.

Parameters:: title (str) – The display name of the section (tab).
Returns:: The section that was added.
Return type:: ChannelSection

getItemTypes(sectionName: str, tableName: str) → List[str]#

Get the names of the possible types that can be in the given table in the given section (tab) of the channel selection widget.

Parameters:

sectionName (str) – The name of the section (tab).
tableName (str) – The name of the table.

Returns:

The item types in the table.

Return type:

List[str]

getSectionNames() → List[str]#

Get the list of section names (tabs) in the channel selection widget.

Returns:: The section names (tabs) in the channel selection widget.
Return type:: List[str]

getTableMultiSelect(sectionName: str, tableName: str) → bool#

Check whether the given table in the given section (tab) of the channel selection widget allows multiple rows to be selected.

Parameters:

sectionName (str) – The name of the section (tab).
tableName (str) – The name of the table.

Returns:

True if multiple rows can be selected, False otherwise.

Return type:

bool

getTableNames(sectionName: str) → List[str]#

Get the names of the tables in the given section (tab) of the channel selection widget.

Parameters:: sectionName (str) – The name of the section (tab).
Returns:: The names of the tables in the section.
Return type:: List[str]

class ChannelSection#

Bases: object

Represents a tab in the channel selection widget.

addTable(title: str, itemTypes: List[ChannelTypes], allowMultiSelect: bool = False) → ChannelTable#

Add an additional table to the section. If a table with the same name already exists in this section, it will be replaced.

Parameters:

title (str) – The display name of the table.
itemTypes (List[ChannelTypes]) – The types of items that can be in the table.
allowMultiSelect (bool) – True if multiple rows can be selected, False otherwise.

Returns:

The table that was added.

Return type:

ChannelTable

getItemTypes(tableName: str) → List[str]#

Get the names of the possible types that can be in the given table.

Parameters:: tableName (str) – The name of the table.
Returns:: The item types in the table.
Return type:: List[str]

getTableMultiSelect(tableName: str) → bool#

Check whether the given table allows multiple rows to be selected.

Parameters:: tableName (str) – The name of the table.
Returns:: True if multiple rows can be selected, False otherwise.
Return type:: bool

getTableNames() → List[str]#

Get the display names of the tables in the section.

Returns:: The names of the tables in the section.
Return type:: List[str]

class ChannelSelection(selectionDict: Dict[str, Dict[str, Dict[str, Dict[str, str]]]])#

Bases: object

Contains the selected channels for a given section and table. The user would have chosen these in the GUI based on the given channel configuration.

See also

ChannelConfig

getItems(sectionName: str, tableName: str) → List[Channel]#

Get the items in the given section and table.

Parameters:

sectionName (str) – The name of the section (tab).
tableName (str) – The name of the table containing the items.

Returns:

The items in the table.

Return type:

List[Dict[str, str]]

class ChannelTable(allowMultiSelect: bool)#

Bases: object

Represents a single table in a channel selection tab.

addItemType(itemType: ChannelTypes) → None#

Add an additional item type to the table.

Parameters:: itemType (ChannelTypes) – The type of item to add.

getItemTypes() → List[str]#

Get the names of the possible types that can be in the table.

Returns:: The item types in the table.
Return type:: List[str]

getMultiSelect() → bool#

Check if the table allows multiple rows to be selected.

Returns:: True if multiple rows can be selected, False otherwise.
Return type:: bool

enum ChannelTypes(value)#

Bases: Enum

Valid values are as follows:

ALL_VARIABLES = <ChannelTypes.ALL_VARIABLES: 'AllVariables'>#

VARIABLES = <ChannelTypes.VARIABLES: 'InputVariables'>#

RESPONSES = <ChannelTypes.RESPONSES: 'ResponseVariables'>#

FIT_VARIABLES = <ChannelTypes.FIT_VARIABLES: 'FitVariables'>#

DATASOURCES = <ChannelTypes.DATASOURCES: 'DataSources'>#

GRADIENTS = <ChannelTypes.GRADIENTS: 'Gradients'>#

USERCHANNELS = <ChannelTypes.USERCHANNELS: 'UserChannels'>#

class CustomPlot#

Bases: object

exception StopException#: Bases: Exception

checkIfStopped() → None#

Check if the stop flag is set. If it is, raise a StopException to stop the plot from being generated. Custom plot scripts should call this intermittently to check if the user has requested to stop the plot. This is especially important to do before long running calculations.

Raises:: CustomPlot.StopException – If the stop flag is set.

cleanup() → None#: Clean up the temporary output file. This is called when the plot is closed or when the plot is no longer needed. Subclasses can override this function to perform additional cleanup, but should always call the parent method to ensure the temporary file is removed.

createEventHandler(objectName: str, event: str, script: str) → str#

Convenience method for wrapping event handling code in a QWebChannel scope.

Parameters:

objectName (str) – The name of the object that the event is triggered on.
event (str) – The name of the event to handle.
script (str) – The JavaScript code to execute when the event is triggered.

Returns:

JavaScript code that sets up the event handler.

Return type:

str

Note

This function is used to create the event handler for the plot. It should be called in the getEventSetupScript method to set up the event handling functionality.

getApproach() → Approach#

Get the Approach Item for the data we are currently plotting.

Returns:: The Approach Item for the data we are currently plotting.
Return type:: api_objects.Approach

getChannelConfig() → ChannelConfig#

Get the channel configuration for the plot. This determines which tables will be shown in the channel selection area and what types of items are in those tables.

Returns:: The channel configuration for the plot.
Return type:: ChannelConfig

getDataSet() → DataSet#

Get the dataset for the plot. This is used to retrieve the data that will be plotted.

Returns:: The dataset for the plot.
Return type:: dataset.DataSet

classmethod getDefaultSettings() → CustomPlotSettings#

Get the default settings for the plot. This is used to store and retrieve settings for the registered plot and is used to initialize instance specific settings. This must be a class method and subclasses should override this method to provide their own settings

Returns:: The settings for the plot.
Return type:: CustomPlotSettings

getEventSetupScript() → str#

This function should be overridden to provide any event handling functionality. The script should call hst_plot.handlePointClickEvent(pointNumber); where pointNumber is the number of the point that was clicked. There is a a constant CustomPlot.HST_JS_OBJECT_NAME that can be used to get the name of the JavaScript object that HyperStudy creates for the plot connector.

Example - Event Handling Script#

script = '''
    var pointNumber='', curveNumber='', colors=[];
    for(var i=0; i < data.points.length; i++){
        pointNumber = data.points[i].pointNumber;
        curveNumber = data.points[i].curveNumber;
    };
'''
script += f'{CustomPlot.HST_JS_OBJECT_NAME}.handlePointClickEvent(pointNumber, curveNumber);'

return '''
    var plot = document.querySelector(".plotly-graph-div");
    if (plot === null) {
        console.log("Plotly graph object not found");
    } else {''' + self.createEventHandler('plot', 'plotly_click', script) + "}"

Returns:: JavaScript source code that will be executed when events are triggered by the plot.
Return type:: str

classmethod getIcon() → str#

Get a small icon for the plot. This must be a class method.

Returns:: The icon for the plot.
Return type:: str

getJsPolyfill() → str#

Additional JavaScript code to add compatibility for older browsers. Subclasses can override this method to provide different or additional JavaScript code. The parent implementation should always be called and the result appended or prepended to the returned string. Changes may be made to this function in the future to allow for more complex JavaScript to be added, so it is recommended to always call the parent implementation.

Returns:: JavaScript code.
Return type:: str

getPlotOutputFile() → str#

Get the path to the temporary output file. This is used to store the plot output when writing the HTML to a file and returning the path. This function should be overridden by subclasses if a different location should be used to write plot HTML.

Returns:: The path to the temporary output file.
Return type:: str

getPointSelectionScript(points: List[str | int], curve: List[str | int] | None = None) → str#

This function should be overridden to provide any point selection functionality. It should return JavaScript source code that will be executed when one or more points are selected. The point numbers are the evaluation indexes that have been selected on this plot or another plot or table. The script returned by this function will be called by HyperStudy.

Parameters:

points (List[Union[str, int]]) – The point number that was selected.
curve (Optional[List[Union[str, int]]]) – The curve that was selected. This is optional and can be None.

Returns:

JavaScript source code that will be executed when a point is selected.

Return type:

str

getSettings() → CustomPlotSettings#: Get the settings for the plot. This is settings instance is unique to the instance of the plot. Changes to these settings doe not affect the settings of the registered plot.

classmethod getThumbnail() → str#

Get a larger icon for the plot. This is used when choosing which post-processing areas are visible. This must be a class method.

Returns:: The preview icon for the plot.
Return type:: str

getUpdateControlsDefault() → bool#

Get the default value for whether the plot should automatically update. This is only relevant if the update controls are enabled.

Returns:: True if the plot should update automatically by default, False otherwise.
Return type:: bool

getUpdateControlsEnabled() → bool#

Check whether plot update controls are enabled.

Returns:: True if the update controls are enabled, False otherwise.
Return type:: bool

Get user channel data from the Approach Summary table. This data is not present in the dataset so it must be retrieved through the tables.

Parameters:: userChannel (str) – The label of the user channel. This function finds the correct column index by matching the label with the column header.
Returns:: The data for the user channel.
Return type:: List[api_objects.hstApiVariant]
Raises:: RuntimeError – If the user channel is not found in the summary table.

isStopped() → bool#

Check if the stop flag is set. This can be used if there is additional cleanup that would need to be done when a plot is stopped. For most cases, checkIfStopped should be used instead.

Returns:: True if the plot should be stopped, False otherwise.
Return type:: bool

makeChannelConfig() → ChannelConfig#

Create the channel configuration for the plot. This determines which tables will be shown in the channel selection area and what types of items are in those tables.

This should be overridden by subclasses to provide the actual channel configuration for the plot.

Example - Channel Configuration#

config = ChannelConfig()

# Add table for input variables that only allows a single selection
inputSection = config.addSection('Inputs')
inputSection.addTable('Variables', [ChannelTypes.VARIABLES],
                    allowMultiSelect=False)

# Add table for responses that allows multiple selections
outputSection = config.addSection('Outputs')
outputSection.addTable('Responses',
                    [ChannelTypes.RESPONSES, ChannelTypes.GRADIENTS],
                    allowMultiSelect=True)

Returns:: The channel configuration for the plot.
Return type:: ChannelConfig

plot(channelSelection: ChannelSelection) → Tuple[PlotOutputType, str]#

Create the plot and return the HTML string or file path to be rendered by HyperStudy. This function should be overridden by subclasses to provide the actual plotting functionality. The default implementation does nothing and returns an empty string.

Note

Some plots may make network requests to retrieve JavaScript. If this should be blocked, set the environment variable HW_HST_CUSTOM_PLOTS_OFFLINE=1

Note

If you are returning a file path, make sure the file is saved to a writable location. Keep in mind that the file will contain data from your HyperStudy session and should be cleaned up after use. If you are returning a string, the total size of the string must be <2MB. Content that is larger than this threshold should be written to a file and the file path should be returned instead.

Parameters:: channelSelection (ChannelSelection) – The selected channels for the plot.
Returns:: A tuple containing the output type (HTML_FILE or HTML_STRING) and the HTML string or file path.
Return type:: Tuple[PlotOutputType, str]

setUpdateControlsEnabled(enabled: bool, defaultValue: bool) → None#

Determine whether plot update controls will be shown to the end user in the GUI. The default value determines whether the plot will update auomatically by default. Otherwise, the user would need to either check the automatic update box or click the update button to update the plot.

Example - Update controls configuration#

# Update controls shown and plot updates automatically by default
plot.setUpdateControlsEnabled(True, True)

# Update controls shown but plot does not update automatically by default
plot.setUpdateControlsEnabled(True, False)

# Update controls are not shown.
plot.setUpdateControlsEnabled(False, False)

Note

If update controls are not shown, the plot will update automatically, regardless of the default value.

Note

This function should be called in the __init__ method of the plot.

Parameters:

enabled (bool) – True if the update controls should be shown, False otherwise.
defaultValue (bool) – True if the plot should update automatically by default, False otherwise.

stop() → None#

Set the stop flag for the plot. This is used to stop the plot from being generated. This is not an error.

Parameters:: stopFlag (bool) – True if the plot should be stopped, False otherwise.

HST_JS_OBJECT_NAME: Final[str] = 'hst_plot'#

class CustomPlotSettings#

Bases: HstSettingObject

This class can be overridden to provide custom settings for the plot that can be configured by the user through HyperStudy.

Example - Basic Custom Plot Settings#

class MyCustomPlotSettings(custom_plot.CustomPlotSettings):
    FONT_SIZE = 'font_size'

    def __init__(self):
        super().__init__()
        self._fontSize = 20

    def getNames(self):
        return [self.FONT_SIZE]

    def getLabel(self, name):
        if name == self.FONT_SIZE:
            return hsttr.gt('Font Size')
        return super().getLabel(name)

    def getValue(self, name):
        if name == self.FONT_SIZE:
            return self._markerSizeValue
        return super().getValue(name)

    def setValue(self, name, value) -> None:
        if name == self.FONT_SIZE:
            self._markerSizeValue = int(value)
        super().setValue(name, value)

    def getDefault(self, name: str):
        if name == self.FONT_SIZE:
            return 20
        return super().getDefault(name)

    def getValid(self, name: str) -> bool:
        if name == self.FONT_SIZE:
            return self._fontSize >= 0
        return super().getValid(name)

enum PlotOutputType(value)#

Bases: IntEnum

Member Type:: int

Valid values are as follows:

HTML_FILE = <PlotOutputType.HTML_FILE: 0>#

HTML_STRING = <PlotOutputType.HTML_STRING: 1>#

getPlotClass() → Type[CustomPlot]#

This function must be overridden in the custom plot module so that HyperStudy can create an instance of the correct class.

Example - Implementation of getPlotClass#

def getPlotClass():
    return MyCustomPlotClass

Returns:: The class of the custom plot.
Return type:: Type[custom_plot.CustomPlot]
Raises:: NotImplementedError – If the function is not overridden in the custom plot module.

isDarkTheme() → bool#

Check if HyperStudy is currently using a dark theme. This can be used to synchronize the themes of the plot libraries with the HyperStudy theme.

Returns:: True if the current theme is dark, False otherwise.