Skip to content
×

Uploading tabular data

Upload file

Allows clients to upload files to be analyzed.

Request:

POST /api/public/v1/file/:fileId/upload
[file]

The fileId is an alpha-numeric identifier provided by the client. Reusing the fileId will overwrite the uploaded file. The fileId must be specified in subsequent requests to create a dataset from the raw uploaded file. The file to upload is provided directly as the body of the request.

Response:

{ status: "success" }

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/file/my42/upload \
       "Authorization: Bearer $(cat ~/.jadtoken)" \
       < ~/data/data42.csv
{
    "status": "success"
}

Create dataset

Allows clients to create a dataset from an uploaded CSV file.

Request:

POST /api/public/v1/file/:fileId/createDataset
{
    fileSizeInBytes: number,
    separator: string,
    hasSamplesInRows: boolean,
    hasFeatureHeaders: boolean,
    hasSampleHeaders: boolean,
    name: string,
    description?: string,
    projectId: string
}

The fileId is an identifier, provided by the client when the file was uploaded. It is assumed that the file is in some CSV-style format. The fileSizeInBytes must match the actual size of the uploaded file and serves as a rudimentary check of upload completeness. The separator string specifies the characters used to separate values in the file. The boolean hasSamplesInRows must be true iff rows of the uploaded file correspond to samples (and columns therefore to features). The booleans hasFeatureHeaders and hasSampleHeaders specify whether the first row or column contains headers rather than data. The name and optional description are used to name and describe the created dataset. The projectId identifies the project to which the dataset should be attached. The user must have write permissions to this project.

Constraints: name must have at least 3 and at most 60 characters and must be unique within the target project. description can be at most 255 characters.

Response:

{ payload: { taskId: string }, status: "success" }

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/file/my42/createDataset \
       "Authorization: Bearer $(cat ~/.jadtoken)" \
       fileSizeInBytes:=406237 \
       separator=, \
       hasSamplesInRows:=true \
       hasFeatureHeaders:=true \
       hasSampleHeaders:=true \
       name=Data42 \
       description="Cohorte 42, full" \
       projectId=16
{
    "payload": {
        "taskId": "28",
    },
    "status": "success"
}

Change feature types

Allows clients to create an alternative versions of a specified dataset using different feature types.

Request:

POST /api/public/v1/dataset/:datasetId/changeFeatureTypes
{
    newName: string,
    changes: { matcher: object, newType: string }[]
}

The datasetId identifies the source dataset. It must belong to a project to which the user has read and write permissions. The new dataset will be attached to that same project.

The newName string is used to name the new dataset. It must have at least 3 and at most 60 characters and must be unique within the target project.

Each element of the changes array matches some features of the source dataset as specified by the matcher field. The types of those features in the new dataset will be changed to the type given by newType whose value must be one of numerical, categorical, timeToEvent, event, or identifier. If some feature is matched by multiple matchers, the last matching entry in the changes array determines its new type.

Feature matchers

The following feature matchers are supported:

By name

{ matcher: { "byName": string[] }, newType: string }

The byName field provides the exact names of the features to match.

By index

{ matcher: { "byIndex": number[] }, newType: string }

The byIndex field provides the 0-based column indices of the features to match.

By current type

{ matcher: { "byCurrentType": string }, newType: string }

The byCurrentType field provides the current type of the features to match. It must be one of numerical, categorical, timeToEvent, event, or identifier.

By deduced type

{ matcher: { "byDeducedType": string }, newType: string }

The byDeducedType field provides the "deduced" type of the features to match. It must be either categorical or identifier. Features have "deduced" types in cases where feature data did not provide sufficient clarity about the intended type, and so JADBio deduced a type on a best-effort basis.

Response:

{ payload: { taskId: string }, status: "success" }

The taskId can be used to query about the status of the dataset transformation task which is performed asynchronously by the server.

Example

$ http --body https://jadapi.jadbio.com/api/public/v1/dataset/57/changeFeatureTypes \
       "Authorization: Bearer $(cat ~/.jadtoken)" \
       newName=Data43 \
       changes:='[{ "matcher": { "byName": ["Patient ID"] }, "newType": "identifier" }]'
{
    "payload": {
        "taskId": "28",
    },
    "status": "success"
}

Get task status

Returns the execution status of an asynchronous task running on the server.

Request:

GET /api/public/v1/task/:taskId/status

The taskId is the identity of the task.

Response:

{
    payload: {
        taskId: string,
        state: string,
        datasetId?: string,
        datasetIds?: string[]
    },
    status: "success"
}

The taskId field is the same as in the request URL. The state field will have one of the values pending, running, finished, or failed, reflecting the progress of the task. The datasetIds field will be present and non-empty iff the task is finished. It then provides the identities of the datasets created by the task. As a convenience for tasks that create a single dataset, the datasetId field will be present iff the datasetIds is a singleton, and will then provide its sole entry.

Example: Running

$ http --body https://jadapi.jadbio.com/api/public/v1/task/28/status \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "state": "running",
        "taskId": "28"
    },
    "status": "success"
}

Example: Finished

$ http --body https://jadapi.jadbio.com/api/public/v1/task/28/status \
       "Authorization: Bearer $(cat ~/.jadtoken)"
{
    "payload": {
        "datasetId": "57",
        "datasetIds": ["57"],
        "state": "finished",
        "taskId": "28"
    },
    "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.