Skip to content
×

Get statements

Analysis

Get analysis

Returns an analysis.

Request:

GET /api/public/v1/analysis/:analysisId

The analysisId identifies the analysis which must belong to a project to which the user must have read access.

Response:

{
    payload: {
        analysisId: string,
        projectId: string,
        parameters: object,
        state: string
    },
    status: "success"
}

The analysisId is the same as in the request. The projectId identifies the project to which the analysis belongs. The parameters object has the same fields as specified when each analysis was created, including the dataset identifier and optional values. The state field will have one of the values pending, running, finished, or failed, reflecting the overall execution progress of each analysis task.

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/analysis/79 \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "parameters": {
            "coreCount": 6,
            "datasetId": "57",
            "featureSelection": "mostRelevant",
            "maxSignatureSize": 25,
            "maxVisualizedSignatureCount": 5,
            "modelsConsidered": "all",
            "name": "Classify Alzheimer diagnosis",
            "outcome": { "classification": "Diagnosis" },
            "thoroughness": "typical"
        },
        "projectId": "16",
        "state": "finished",
    },
    "status": "success"
}

Get analyses

Returns a sublist of all analyses in a project.

Request:

GET /api/public/v1/analyses/all/:projectId/:offset/:count

The projectId identifies the project to which the user must have read permissions. Analyses form an ordered list from which the request extracts the sublist starting at offset and containing at most count elements. The list uses zero-based indexing, meaning the first element is at offset 0.

Constraints: Both offset and count must be non-negative integers and count can be at most 100.

Response:

{
    payload: {
        projectId: string,
        offset: number,
        totalCount: number,
        data: {
            analysisId: string,
            projectId: string,
            parameters: object,
            state: string
        }[]
    },
    status: "success"
}

The projectId and offset are the parameters given in the request. The totalCount is the total number of analyses available in the project. The data array contains the analyses requested. The length of data will be the smaller of count and totalCount − offset. If the latter value is negative, the length will be zero. The analysisId identifies each analysis returned. The parameters object has the same fields as specified when each analysis was created, including the dataset identifier and optional values. The state field will have one of the values pending, running, finished, or failed, reflecting the overall execution progress of each analysis task.

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/analyses/all/16/0/10 \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "data": [{
            "analysisId": "79",
            "parameters": {
                "coreCount": 6,
                "datasetId": "57",
                "featureSelection": "mostRelevant",
                "maxSignatureSize": 25,
                "maxVisualizedSignatureCount": 5,
                "modelsConsidered": "all",
                "name": "Classify Alzheimer diagnosis",
                "outcome": { "classification": "Diagnosis" },
                "thoroughness": "typical"
            },
            "projectId": "16",
            "state": "running",
        }, {
            "analysisId": "80",
            "parameters": {
                "coreCount": 12,
                "datasetId": "58",
                "featureSelection": "mostRelevant",
                "maxSignatureSize": 25,
                "maxVisualizedSignatureCount": 5,
                "modelsConsidered": "all",
                "name": "Alzheimer survival II",
                "outcome": { "survival": { event: "Deceased", timeToEvent: "Time" } },
                "thoroughness": "preliminary"
            },
            "projectId": "16",
            "state": "finished",
        }],
        "offset": 0,
        "projectId: "16",
        "totalCount": 2
    },
    "status": "success"
}

Get analysis status

Returns the execution status of an analysis.

Request:

GET /api/public/v1/analysis/:analysisId/status

The analysisId identifies the analysis. It must belong to a project to which the user has read permissions.

Response:

{
    payload: {
        analysisId: string,
        projectId: string,
        parameters: object,
        state: string,
        startTime?: timestamp,
        executionTimeInSeconds?: number,
        progress?: number,
    },
    status: "success"
}

The analysisId field is the same as in the request URL. The projectId identifies the project to which the analysis belongs. The nested parameters object has the same fields as specified when the analysis was created, including the dataset identifier and optional values. The state field will have one of the values pending, running, finished, or failed, reflecting the overall execution progress of the analysis task. The startTime field will be present when state is running or finished. It may be present when state is failed, depending on how the analysis failed. When present, it indicates the UTC/Zulu time a which the analysis started, specified as an ISO 8601 date and time string. The executionTimeInSeconds will be present when state is running or finished. It may be present when state is failed provided startTime is present. When present, it indicates the analysis execution time in seconds. The progress field will be present iff the analysis is running and then indicates the analysis completion ratio as a number between 0.0 and 1.0.

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/analysis/79/status \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "executionTimeInSeconds": 80,
        "parameters": {
            "coreCount": 6,
            "datasetId": "57",
            "featureSelection": "mostRelevant",
            "maxSignatureSize": 25,
            "maxVisualizedSignatureCount": 5,
            "modelsConsidered": "all",
            "name": "Classify Alzheimer diagnosis",
            "outcome": {
                "classification": "Diagnosis"
            },
            "thoroughness": "typical"
        },
        "progress": 0.92,
        "projectId: "16",
        "startTime": "2020-03-31T22:07:46Z",
        "state": "running",
    },
    "status": "success"
}

Get analysis results

Returns the result of a finished analysis.

Request:

GET /api/public/v1/analysis/:analysisId/result

The analysisId identifies the analysis. It must belong to a project to which the user has read permissions.

Response:

{
    payload: {
        analysisId: string,
        parameters: object,
        mlEngine: string,
        startTime: timestamp,
        executionTimeInSeconds: number,
        models: {
            modelKey1?: model1,
            modelKey2?: model2,
        },
    },
    status: "success"
}

The analysisId field is the same as in the request URL. The nested parameters object has the same fields as specified when the analysis was created, including the identity of the dataset and optional values. The mlEngine string identifies the AutoML analysis engine that produced the result, including version number. The startTime is the UTC/Zulu time at which the analysis task started, specified as an ISO 8601 date and time string, and executionTimeInSeconds is how long it took in seconds. The nested models object provides details of the best analysis configurations found. It contains at least one nested model object; the field key indicates the identifier of that model: e.g. best or interpretable.

The model datatype has the following form:

{
    preprocessing: string,
    featureSelection: string,
    model: string,
    signatures: string[][],
    performance: {
        metricKey1?: number,
    }
}

The preprocessing string is a short, human-readable description of the preprocessing steps applied. The featureSelection string is a short, human-readable description of the feature-selection algorithm used. The model string is a short, human-readable description of the statistical model found. The signatures array contains the best signatures identified by the featureSelection algorithm. The first array contains the reference signature while the rest (if any) refer to equivalent signatures. The performance object, contains the current model's performance on the evaluation metrics.

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/analysis/79/result \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "analysisId": "79",
        "executionTimeInSeconds": 83,
        "mlEngine": "jadbio-1.0.67",
        "models": {
            "best": {
                "featureSelection": "Statistically Equivalent Signature (SES) algorithm with hyper-parameters: maxK = 3, and alpha = 0.05",
                "model": "Support Vector Machines (SVM) of type C-SVC with Polynomial Kernel and hyper-parameters: cost = 10.0, gamma = 0.1, degree = 3",
                "preprocessing": "Constant Removal, Mean Imputation, Mode Imputation, Standardization",
                "signatures": [["feature5", "feature4"]],
                "performance": {
                    "Area Under the ROC Curve": 0.9979193891504624,
            },
        },
            "interpretable": {
                "featureSelection": "Statistically Equivalent Signature (SES) algorithm with hyper-parameters: maxK = 3, and alpha = 0.05",
                "model": "Ridge Logistic Regression with penalty hyper-parameter lambda = 0.1",
                "preprocessing": "Constant Removal, Mean Imputation, Mode Imputation, Standardization",
                "signatures": [["feature5", "feature4"]],
                "performance": {
                    "Area Under the ROC Curve": 0.951428730938,
                },
        },
        "parameters": {
            "coreCount": 6,
            "datasetId": "57",
            "featureSelection": "mostRelevant",
            "maxSignatureSize": 25,
            "maxVisualizedSignatureCount": 5,
            "modelsConsidered": "all",
            "name": "Classify Alzheimer diagnosis",
            "outcome": {
                "classification": "Diagnosis"
            },
            "thoroughness": "typical",
        },
        "startTime": "2020-03-31T22:07:46Z"
    },
    "status": "success"
}

Example: Unknown analysis

$ http --body https://jadapi.jadbio.com/api/public/v1/analysis/unknown/result \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "code": "notFound-120-2-1",
    "message": "Analysis 'unknown' not found",
    "status": "error"
}

Example: Unfinished analysis

$ http --body https://jadapi.jadbio.com/api/public/v1/analysis/unfinished/result \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "code": "notFound-120-2-3",
    "message": "Analysis 'unfinished' has no result",
    "status": "error"
}

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.

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).

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.