Skip to main content

Working With the Task Distributional Output

Sampling from distributions​

Samples from uncertainty-tracking (UT) C0 or C0 Pro core runs​

The Signaloid Cloud Compute Engine API provides the /samples endpoint which expects as input a distribution encoded in the form of an Uncertainty Hexadecimal (“Ux”) string and returns random samples from this input distribution. This guide describes how you can get the Ux string values from the output (either stdout or stderr) of uncertainty-tracking (UT) tasks. The /samples endpoint also accepts the query parameter count to instruct it how many samples to generate.

The code snippet below shows how to generate 10 samples from the distribution of the variable sigmaCMpa as calculated either using a source code task or a repository task.

  // Helper function for fetching variable samples

  async function extractUxStringValues(taskOutput: string) {
    const regex = /([-+]?(?:\d+\.\d*|\.\d+)(?:[eE][-+]?\d+)?)(Ux[0-9a-fA-F]{40,})/g;
    return [...taskOutput.matchAll(regex)].map((m) => ({ value: m[1], uxString: m[2] }));
  }

  async function getSamplesFromUxString(uxString: string) {
    try {
      // get task data from API
      const sampleRequestResponse = await signaloidClient.get(`/samples`, {
        params: { count: 10 },
        data: {
          UxValue: uxString
        }
      });
      if (sampleRequestResponse.data) {
        console.log(`Samples from the variable "sigmaCMpa" (Alloy strength): `, sampleRequestResponse.data);
      }
    } catch (error) {
      console.log("Error:", error);
    }
  }

  async function parseOutputAndGetSamplesFromUxString() {
    if (taskStdout) {
      const uxStringsExtracted = await extractUxStringValues(taskStdout);
      const uxString = uxStringsExtracted[uxStringsExtracted.length - 1].uxString;

      if (uxString) {
        console.log(`Generating samples from the distribution of the variable "sigmaCMpa" (Alloy strength) with uxString: ${uxString}`);
        await getSamplesFromUxString(uxString);
      }
    } else {
      // wait for the outputs to be available
      setTimeout(async () => {
        // Note: this function should ideally be called inside `getTaskOutputs` after setting `taskStdout`.
        await parseOutputAndGetSamplesFromUxString();
      }, 1000);
    }
  }

  await parseOutputAndGetSamplesFromUxString();

The response from this endpoint will have the following shape:

{
    "Samples": [
        1479.8029446132969, 266.390706351501, 858.8775223090213, 546.4088466714376, 645.0190538880073,
        321.2449635555817, 701.89858850263, 675.9114708254975, 663.4408244950512, 1538.206118918603
    ],
    "Count": 10
}

Please refer to the sample generation endpoint API reference for more details.

Samples from C0 or C0 Pro Reference core runs​

For downloading the samples generated during the execution of applications on Reference cores, the Signaloid Cloud Compute Engine API provides the /tasks/{TaskID}/values/{ValueID}/samples endpoint. The endpoint URL contains the task ID (TaskID) and value ID (ValueID) of the expression that was traced. This guide describes how you can get the ValueID from the output (either stdout or stderr) of a Reference core task. The endpoint also accepts the query parameter count to instruct it how many samples to download. The endpoint returns up to 10,000 samples. To allow you to download more than 10,000 samples, if they exist, the endpoint also returns a ContinuationToken that you can add as the query parameter continuationToken to download a subsequent batch of samples.

The code snippet below shows how to generate 10 samples from the distribution of the variable sigmaCMpa as calculated either using a source code or a repository Reference core task. The task of the examples was executed on the default C0-Reference core which results in 32 samples. The code asks for a first batch of ten samples and then using the ContinuationToken it asks for a second batch of 10 samples.

  // Helper function for fetching variable samples
  async function extractValueIDTags(taskOutput: string) {
    const regex = /([-+]?(?:\d+\.\d*|\.\d+)(?:[eE][-+]?\d+)?)<ValueID>(.*?)<\/ValueID>/g;
    return [...taskOutput.matchAll(regex)].map((m) => ({ value: m[1], valueID: m[2] }));
  }

  async function getSamplesFromVariable(taskID: string, valueID: string) {
    try {
      // get task data from API
      const sampleRequestResponse = await signaloidClient.get(`/tasks/${taskID}/values/${valueID}/samples`, {
        params: { count: 10 },
      });
      if (sampleRequestResponse.data) {
        console.log(`Samples from the variable "sigmaCMpa" (Alloy strength): `, sampleRequestResponse.data);
      }
    } catch (error) {
      console.log("Error :>> ", error); // [TODO]: handle errors
    }
  }

  async function parseOutputAndGetSamples() {
    if (taskStdout) {
      const values = await extractValueIDTags(taskStdout);
      const sigmaCMpa_valueID = values[values.length - 1].valueID;

      if (sigmaCMpa_valueID) {
        console.log(
          `Generating samples from the distribution of the variable "sigmaCMpa" (Alloy strength) with valueID: ${sigmaCMpa_valueID}`
        );
        await getSamplesFromVariable(taskID, sigmaCMpa_valueID);
      }
    } else {
      // wait for the outputs to be available
      setTimeout(async () => {
        // Note: this function should ideally be called inside `getTaskOutputs` after setting `taskStdout`.
        await parseOutputAndGetSamples();
      }, 1000);
    }
  }

  await parseOutputAndGetSamples();

The response from this endpoint will have the following shape:

{
    "Samples": [
        446.8395834203027, 563.2602152805459, 447.5357763646873, 1254.257413026913, 713.1036552505653,
        851.148622921381, 1102.751946844017, 818.0114347199466, 766.5801430096062, 551.714077743751
    ],
    "Count": 10,
    "ContinuationToken": "eyJ2ZXJzaW9uIjogMCwgImxhc3RfYnl0ZV9yZWFkIjogMTEwNCwgInRvdGFsX3NhbXBsZXMiOiAzMn0="
}

Please refer to the sample generation endpoint API reference for more details.

Plotting distributions​

Distributional plots from uncertainty-tracking (UT) C0 or C0 Pro core runs​

The Signaloid Cloud Compute Engine API provides the /plot which takes as input (payload) a distribution encoded in the form of an Uncertainty Hexadecimal (“Ux”) string and generates a plot of the probability density function of its input distribution. This guide describes how you get the Ux string values from the output (either stdout or stderr) of uncertainty-tracking (UT) tasks. The following code snippets show how to generate a plot of the distributional value of sigmaCMpa using the Signaloid API.

const plotRequestResponse = await signaloidClient.post(`/plot`, { payload: uxString });

The plot response will have the following shape:

{
    "plotID": "879bcae6-d6d9-4e2f-9550-43fb84615d30", // ID of the plot
    "presignedURL": "https://.... " // presigned URL to download the plot
}

The presignedURL field of the response object will contain a presigned URL to an image of the plot. You can use this URL to download the plot and display it in your application.

Figure 1. The plot shows how the uncertainties in the input variables have affected the uncertainty in the output variable sigmaCMpa of an uncertainty-tracking UT core task.

Distributional plots from Reference C0 or C0 Pro core runs​

The Signaloid Cloud Compute Engine API provides the /tasks/{TaskID}/values/{ValueID}/plot endpoint that generates a plot of the probability density function of your variables and returns a URL to it. The endpoint for Reference core runs expects the task ID and value ID as path parameters taskID and valueID, respectively. The following code snippets show how to generate a plot of the distributional value of sigmaCMpa using the Signaloid API.

const plotRequestResponse = await signaloidClient.post(`/tasks/${taskID}/values/${valueID}/plot`);

The plot response will have the following shape:

{
    "plotID": "879bcae6-d6d9-4e2f-9550-43fb84615d30", // ID of the plot
    "presignedURL": "https://.... " // presigned URL to download the plot
}

The presignedURL field of the response object will contain a presigned URL to an image of the plot. You can use this URL to download the plot and display it in your application.

Figure 1. The plot shows how the uncertainties in the input variables have affected the uncertainty in the output variable sigmaCMpa of a Reference core task.