Skip to content
×

Plots

Get available plots

Retrieves the plot names of the computed plots for a given model in an analysis.

Request:

GET /api/public/v1/analysis/:analysisId/availablePlots?modelKey=string

The analysisId identifies the analysis. It must belong to a project to which the user has write permissions. The modelKey value must be a value present in the models object of the analysis' result.

Response:

{
    payload: {
        analysisId: string,
        modelKey: string,
        plots: string[],
    },
    status: "success"
}

The analysisId, modelKey are the same as in the request. The plots array contains the plot names that are available for the current modelKey.

Example

$ http --body POST https://jadapi.jadbio.com/api/public/v1/analysis/79/availablePlots \
       modelKey=best \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "modelKey": "best";
        "plots": ["Feature Importance", "Progressive Feature Importance"],
    },
    "status": "success"
}

Currently, the available plots are Feature Importance and Progressive Feature Importance. Note that more plots will be added in the future. Feature Importance is defined as the percentage drop in predictive performance when a feature is removed from the model. The Progressive Feature Importance reports the predictive performance that can be achieved by using only part of the features.

Get plot

Retrieves the raw values of a plot for a modelKey - analysis pair.

Request:

GET /api/public/v1/analysis/:analysisId/getPlot?modelKey=string&plotKey=string

The analysisId identifies the analysis. It must belong to a project to which the user has write permissions. The modelKey identifies the model whose results are to be retrieved. The modelKey value must be a value present in the models object of the analysis' result. The plotKey identifies the plot whose results are to be retrieved. The plotKey value must be a value present in the plots array of the Get available plots result.

Response:

{
    payload: {
        analysisId: string,
        modelKey: string,
        plot: {
            plotKey: object[],
        },
    },
    status: "success"
}

The analysisId, modelKey are the same as in the request. The plot object contains the raw values of the requested plot.

Helper Plot objects

The data for some plots are reported in a PlotObject format. This format is explained below.

"PlotObject":
{
    title: string,
    xaxis: string,
    yaxis: string,
    legend?: { string: string },
    points: {
        sampleID?: string,
        x: number,
        y: number,
        categoryID?: string
        threshold?: number
    }[]
}

Contents of a PlotObject. The title defines the plotObject title. The xaxis contains a label for the x-axis. The yaxis contains a label for the y-axis. When legend is present, it maps specific points.categoryID values, to a title. The points array contains the x and y coordinates of each point in the scatter plot. In the case that each point refers to a single dataset sample the sampleID contains the name of that sample. Furthermore, when categoryIDis present, it will contain the id of the group of the sample (i.e. in classification analysis, it indicates the true label of the sample). threshold contains the threshold used to create the point in the case of threshold dependent plot (such as ROC plot)

Plot objects

"Feature Importance":
    {
        name: string,
        value: number,
        cis: [number, number],
    }[]

Defined as the percentage drop in predictive performance when a feature is removed from the model. name indicates the name of the feature that was removed (all other features are used). value is the ratio of performance drop when aforementioned feature was removed. cis contains the 95% confidence interval (lower, upper)

"Progressive Feature Importance":
    {
        name: string[],
        value: number,
        cis: [number, number],
    }[]

Reports the predictive performance that can be achieved by using only part of the features. The features are added one at the time, starting from the most important and ending with the complete signature. name indicates the name of the features that were used for the current estimation. value is the percentage of the full model performance that can be achieved by only using the features contained in the name variable. cis contains the 95% confidence interval (lower, upper).

"Residuals":
{
    residuals: PlotObject,
    actualVSPredicted: PlotObject
}

Available in Regression analyses. Returns two PlotObjects The target residuals vs the predictions under the key residuals and the actual target values vs the predictions under the key actualVSPredicted. The PlotObject is defined below.

"PCA":
PlotObject

For the PCA plot, we plot each sample against the two most significant principal components from the dataset variables that participate in the model's signature. The PCA plot data are directly reported in a PlotObject.

"UMAP":
PlotObject

Uniform Manifold Approximation and Projection (UMAP) attempts to learn the high-dimensional manifold on which the original data lays, and then maps it down to two dimensions. UMAP plots provides a visual aid for assessing relationships among samples. For the UMAP plot, we plot each sample against the axis returned from the umap function using the variables that participate in the model's signature. The UMAP plot data are directly reported in a PlotObject.

"ROC":
PlotObject[]

The ROC curve visualizes the performance of a binary classifier. In a ROC curve the true positive rate (Sensitivity) is plotted against the false positive rate (1-Specificity) for different cut-off points (threshold). The current plot data consists for an array of PlotObjects containing the per-class ROC curve points using the one-vs-all strategy.

"Precision-Recall Curve":
PlotObject[]

The Precision-Recall Curve visualizes the performance of a binary classifier. In a Precision-Recall curve the Precision is plotted against the Recall for different cut-off points (threshold). The current plot data consists for an array of PlotObjects containing the per-class Precision-Recall Curve curve points using the one-vs-all strategy.

"Probabilities":
PlotObject[]

The Probabilities plot contrasts the cross-validated predicted probability of belonging to a specific class against the actual class of the samples. Well-performing models are expected to provide predictions that are close to 1 for the actual class and close to 0 for all other classes. The current plot data consists for an array of PlotObjects containing the per-class Probabilities plot points using the one-vs-all strategy.

"Kaplan Meier":
PlotObject[]

The Kaplan Meier (KM) curve indicates the probability of surviving (that is, not experiencing any event) at least up to a specific point in time. Different groups of samples can have different KM curves, indicating a higher or lower risk associated with belonging to a specific group: the steeper the curve, the higher the risk. JADBio separates samples in groups according to quantiles of mortality scores, and then computes the KM curves by using the time-to-event and event information. The current plot data consists for an array of PlotObjects containing the Kaplan-Meier plot for a varying amount of groups. E.g. The first plot contains the data for the Kaplan-Meier for 2 groups, the second for 3 groups, etc.

Example

$ http --body POST https://jadapi.jadbio.com/api/public/v1/analysis/79/getPlot \
       modelKey=best \
       plotKey='Feature Importance' \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "modelKey": "best",
        "plot": {
            "Feature Importance": [
                {
                    "name": "feature5",
                    "value": 0.0053404539385848585,
                    "cis": [0.0, 0.017277777777777836],
                },
                {
                    "name": "feature4",
                    "value": 0.0053404539385848585,
                    "cis": [0.0, 0.017341756472191352],
                }
            ]
        }
    },
    "status": "success"
}

Get plots

Retrieves the raw values of all the available plots for a modelKey - analysis pair.

Request:

GET /api/public/v1/analysis/:analysisId/getPlots?modelKey=string

The analysisId identifies the analysis. It must belong to a project to which the user has write permissions. The modelKey identifies model whose results are to be retrieve. The modelKey value must be a value present in the models object of the analysis' result.

Response:

{
    payload: {
        analysisId: string,
        modelKey: string,
        plots: {
            plotKey?: {
                name: object,
                value: number,
                cis: [number, number],
            }[],
        }[],
    },
    status: "success"
}

The analysisId, modelKey are the same as in the request. The plots array contains the raw values of plot objects per plotKey present in the request.

Example

$ http --body POST https://jadapi.jadbio.com/api/public/v1/analysis/79/getPlots \
       modelKey=best \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "modelKey": "best",
        "plots": [
            {
                "Feature Importance": [
                    {
                        "name": "feature5",
                        "value": 0.0053404539385848585,
                        "cis": [0.0, 0.017277777777777836],
                    },
                    {
                        "name": "feature4",
                        "value": 0.0053404539385848585,
                        "cis": [0.0, 0.017341756472191352],
                    }
                ]
            },
            {
                "Progressive Feature Importance": [
                    {
                        "name": ["variable5"],
                        "value": 0.9946595460614152,
                        "cis": [1.0, 0.9826582435278086],
                    },
                    {
                        "name": ["feature5", "feature4"],
                        "value": 1.0,
                        "cis": [1.0, 1.0],
                    }
                ]
            }
        ]
    },
    "status": "success"
}


Note of appreciation to JADBio users

We constantly make changes in the software and do our best to update these materials, but you may notice some differences. We welcome your feedback on how to make this more useful for you and requests for future tutorials.