Skip to main content

Rich Function View

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import BrowserWindow from '@site/src/components/browser-window';

RichFunctionView is an advanced UI editor to create a complex full-featured interface for your script.

It has all the features of the basic scripting. In addition, it allows you to:

Package dependency

Ensure that the Compute2 and WebComponents packages are installed

Enabling RichFunctionView UI editor​

To enable RichFunctionView, add editor: Compute2:RichFunctionViewEditor tag to your following code as it is shown:

rich-function-demo
Your script header
#editor: Compute2:RichFunctionViewEditor
Your script header
//editor: Compute2:RichFunctionViewEditor
Ensure computations are correct

Features of the RichFunctionView affect GUI only and do not affect computations. Use the RichFunctionView only when you are sure that the script works as expected.

Enhance inputs and outputs​

Visualize input data​

You can add viewers for input dataframes to review input data before starting computations, same way as for output viewers.

input-viewers
Your script header
//input: dataframe test { viewer: Line chart | Grid }
https://public.datagrok.ai/scripts
//name: Viewer properties demo
//language: javascript
//sample: demog.csv
//input: dataframe test { viewer: Line chart | Grid }
//output: dataframe test2
//editor: Compute2:RichFunctionViewEditor
test2 = test.clone();

You can specify input viewer's properties to control their appearance. Viewer's properties are listed in the braces right after the viewer's name. A full list of the viewer's properties may be found by right-clicking on it and selecting the Properties... (dev tools) menu item.

Some options could be set directly in a chart annotaion via Grid(prop: val) syntax, however for many options a js viewer object must be used. To obtain js properties object a Dev Tools platform package must be installed. Right click on the chart, then To Script, then To JavaScript. The second argument is the properties object. For the purpose of directly using this object there is a viewersHook annotation. It must be a js function full name. Since viewer hook is synchronous, viewersHook function must just return another js function, which accepts the following arguments:

  1. ioName: string - name of the input or output
  2. type: string - viewer type
  3. viewer: DG.Viewer - viewer js object
  4. meta?: any - optional io metadata, available only in workflows.
function MyScriptViewersHookMaker() {
  return (ioName: string, type: string, viewer: DG.Viewer) => {
    viewer.setOptions(...)
  }
}

RichFunctionView supports the dockSpawnConfig option to control the viewer's width. By default, any viewer occupies all available space. Inside dockSpawnConfig there must be a json map with a viewer tab name and the following config.

interface DockSpawnConfigItem {
  'dock-spawn-dock-type'?: 'left' | 'right' | 'up' | 'down',
  'dock-spawn-dock-to'?: string,
  'dock-spawn-dock-ratio'?: number,
}

Viewer tab name is this context should match exactly (including spaces) the viewer name rendered in the app, for example a line chart for output named Trajectory will be Trajectory / Line chart. dock-spawn-dock-to is also using this naming convention.

viewers-block
Your script header
//input: dataframe demog { viewer: Line chart | Filters }
https://public.datagrok.ai/scripts
//name: Viewer block option demo
//language: javascript
//input: dataframe demog { viewer: Line chart | Filters }
//output: dataframe test2
//editor: Compute2:RichFunctionViewEditor
test2 = demog.clone();
 ### Group scalar outputs

You can use the category keyword to group scalar output parameters. In the case of output parameters, the category tag specifies the output tab used to show the output parameter values. The following code generates UI with three output tabs:

output-categories

tip

The view includes 4 tabs in total since there is a separate tab for input dataframe viewers.
Your script header
//output: dataframe tempOnTime4 { viewer: Line chart }
//output: dataframe tempOnTime5 { viewer: Line chart }
//output: double IC3 { category: Tab #3}
//output: double IC4 { category: Tab #3}
https://public.datagrok.ai/scripts
//name: Grouping outputs
//language: javascript
//input: dataframe test { viewer: Line chart }
//input: double S1 = 50 { caption: S1 }
//output: dataframe tempOnTime4 { viewer: Line chart }
//output: double IC1 { category: Experimental data }
//output: dataframe tempOnTime5 { viewer: Line chart }
//output: double IC2 { category: Simulation data }
//output: double IC3 { category: Tab #3 }
//output: double IC4 { category: Tab #3 }
//editor: Compute2:RichFunctionViewEditor

tempOnTime4 = test;
tempOnTime5 = test;

IC1 = 10;
IC2 = 20;
IC3 = test.rowCount * 2;
IC4 = test.rowCount;

Automatic script rerun​

You can run scripts automatically on UI opening and/or on any input change. This feature is useful for fast prototyping. We recommend using it only on fast Javascript scripts only to avoid repeatable runs of computational-heavy code.

The automatic function calls are not saved, so to save results to the run history you should press the Save button manually.

run-on-input
Your script header
//meta.runOnInput: true
https://public.datagrok.ai/scripts
//name: Data stats
//language: javascript
//tags: demo
//input: dataframe inputDf {caption: Input dataframe; viewer: Grid(); category: Input data}
//output: dataframe outputDf {caption: Output dataframe; viewer: Line chart | Scatter plot | Statistics; category: Stats}
//editor: Compute2:RichFunctionViewEditor
//meta.runOnInput: true

outputDf = inputDf.clone();

Provide custom docs and export data​

Add the readme​

You can add a customized readme file to your script. The linked Markdown file will be available by clicking icon on the ribbon panel. The readme file will appear inside the panel on the right side.

rfv-help

Following code will search for the help file in your Datagrok's Home folder.

Your script header (w/ personal file)
//meta.help: readme.md

The following code will search for the help file in the particular package (e.g., Compute). See the details about packages in the convert script to a package function section

Your script header (w/ package file)
//meta.help: Compute/readme.md
https://public.datagrok.ai/scripts
//name: Data stats
//language: javascript
//tags: demo
//input: dataframe inputDf {caption: Input dataframe; viewer: Grid(); category: Input data}
//output: dataframe outputDf {caption: Output dataframe; viewer: Line chart | Scatter plot | Statistics; category: Stats}
//editor: Compute2:RichFunctionViewEditor
//meta.runOnInput: true

outputDf = inputDf.clone();

Export results​

You can use the one-click export feature to save the entire script run to a local file. To generate the export file, Select Export icon on the top panel. Automatic export saves all input and output values with their captions, units, and even viewers' screenshots.

This feature is available for all scripts using the RichFunctionView. To disable it, add the meta.features tag to the script header.

export-demo
Your script header
//meta.features: {"export": false}

Customize export​

You can customize export using the following annotation:

//meta.customExports: [{"name": "pdf", "function": "MyPackage:MyPDFExport"}]

The export function will receive the following arguments:

  • funcCall: DG.FuncCall, current call.
  • startDownload: bool, true if the function should start a file download or just return results.
  • isOutputOutdated: bool, true if the function output is outdated.
  • validationState: Record<string, ValidationResult>, available only if run inside a workflows.
  • consistencyState: Record<string, ConsistencyInfo>, available only if run inside a workflows.

Review and compare historical script runs​

Save and access run history​

When enabled (by default), the server saves each script run. The saved script run includes both the input and output values of the run. To review the history of runs, click on the History button on the top panel.

The history panel appears on the right side. To load the run into the UI, click on the corresponding card. The historical runs are immutable. Thus, if you load a historical run, change input values, and then rerun it, the platform will create a new historical run.

history

To disable history, add the following line to your code:

Your script header
//meta.features: {"history": false}

Compare historical runs​

You may compare historical runs using history panel. Select the historical runs of the interest and click icon to open the comparison view.

Datagrok provides defauls set of viewers to compare all kinds of the output data.

tip

Click on the column header with table data (e.g. Temp. vs time) to see convenient comparison chart.

comparsion-view

call-compare

Model parameters optimization​

With RichFunctionView you can use the powerful built-in optimization functions.

Sensitivity analysis​

Sensitivity analysis automatically runs the computation multiple times with varying inputs, and analyzes the relationship between inputs and outputs.

sens-analysis
Your script header
//meta.features: {"sens-analysis": true}
https://public.datagrok.ai/scripts
//name: Object cooling
//description: Uses Newton's law of cooling to simulate object cooling process. Default values are for cube of boiling water in air.
//language: javascript
//tags: simulation, demo
//input: double ambTemp = 22 {caption: Ambient temperature; units: C; category: Environment }
//input: double initTemp = 100 {caption: Initial temperature; units: C; category: Environment }
//input: double desiredTemp = 30 {caption: Desired temperature; units: C; category: Environment }
//input: double area = 0.06 {caption: Surface area; units: m²; category: Object properties}
//input: double heatCap = 4200 {caption: Heat capacity; units: J/C; category: Object properties }
//input: double heatTransferCoeff = 8.3 {caption: Heat transfer coefficient; units: W/(m² * C); category: Object properties}
//input: int simTime = 21600 {caption: Simulation time; units: sec; category: Simulation }
//output: dataframe simulation {caption: Temp. vs time; category: Output; viewer: Line chart | Grid}
//output: double timeToCool {caption: Time to cool; units: sec.; category: Output}
//output: double coolingFactor {caption: Cooling factor; units: 1 / sec.; category: Calculations}
//output: double tempDiff {caption: Temperature difference; units: C; category: Calculations}
//editor: Compute2:RichFunctionViewEditor
//meta.features: {"sens-analysis": true}

timeToCool = undefined;

const tempDiff = initTemp - ambTemp;
const coolingFactor = heatTransferCoeff * area / heatCap;

const timeStamps = new Float32Array(simTime).map((_, idx) => idx);
const simulatedTemp = timeStamps.map((timeStamp) => {
  const currentTemp = ambTemp + (tempDiff * (Math.E ** -(coolingFactor * timeStamp)));

  if (!timeToCool && currentTemp < desiredTemp) {
    timeToCool = timeStamp;
  }

  return currentTemp;
});

simulation = DG.DataFrame.fromColumns([
  DG.Column.fromFloat32Array('Time', timeStamps),
  DG.Column.fromFloat32Array('Temperature', simulatedTemp),
]);

Parameters optimization​

The parameters optimization solves an inverse problem to the sensitivity analysis: finding the input conditions that lead to a specified output of the model. It computes inputs minimizing deviation measured by loss function.

High-intensity computation

Both Sensitivity analysis and Parameter optimization trigger many simultaneous runs of the model. We recommend using these features on fast Javascript and WebAssembly scripts to avoid repeatable running of heavy server-side code.