Client

The Grand Challenge API client.

__call__

__call__(
    method="GET",
    url="",
    path="",
    params=None,
    json=None,
    extra_headers=None,
    files=None,
    data=None,
    follow_redirects=False,
) -> Any

Make an HTTP request to the API.

Parameters:

• method (str, default: 'GET' ) –

  HTTP method to use, by default "GET".

• url (str, default: '' ) –

  Full URL to request. If provided, path is ignored.

• path (str, default: '' ) –

  Path relative to base_url. Ignored if url is provided.

• params (dict, default: None ) –

  Query parameters to include in the request.

• json (dict, default: None ) –

  JSON data to send in the request body.

• extra_headers (dict, default: None ) –

  Additional headers to include in the request.

• files (dict, default: None ) –

  Files to upload with the request.

• data (dict, default: None ) –

  Form data to send in the request body.

• follow_redirects (bool, default: False ) –

  Whether to follow HTTP redirects, by default False.

Returns:

• Any ( Any ) –

  JSON response data if Content-Type is application/json,

• Any –

  otherwise the raw response object.

Raises:

• HTTPStatusError –

  If the HTTP request fails with a non-2xx status code.

__init__

__init__(
    token: str = "",
    base_url: str = "https://grand-challenge.org/api/v1/",
    verify: bool = True,
    timeout: float = 60.0,
    retry_strategy: Optional[
        Callable[[], BaseRetryStrategy]
    ] = None,
)

Parameters:

• token (str, default: '' ) –

  Authorization token for API access. If not provided, will be read from GRAND_CHALLENGE_AUTHORIZATION environment variable.

• base_url (str, default: 'https://grand-challenge.org/api/v1/' ) –

  Base URL for the API, by default "https://grand-challenge.org/api/v1/".

• verify (bool, default: True ) –

  Whether to verify SSL certificates, by default True.

• timeout (float, default: 60.0 ) –

  Request timeout in seconds, by default 60.0.

• retry_strategy (callable, default: None ) –

  Factory function that returns a retry strategy instance. If None, uses SelectiveBackoffStrategy with default parameters.

add_cases_to_archive

add_cases_to_archive(
    *,
    archive: Union[str, Archive],
    archive_items: list[SocketValueSetDescription]
) -> list[str]

This function takes an archive slug or model and a list of archive item descriptions and creates the archive item to be used on the platform.

Re-using existing images

Existing images on Grand Challenge can be re-used by either passing an API url, or a socket value (archive item):

image = client.images.detail(pk="ad5...")
ai = client.archive_items.detail(pk="f5...")
socket_value = ai.values[0]

archive_items = [
    {
        "slug_0": image.api_url,
        "slug_1": socket_value,
        "slug_2": socket_value.image,
    }
]

One can also provide a same-socket socket value:

ai = client.archive_items.detail(pk="f5...")
archive_items = [
    {
        "slug_0": ai.values[0],
        "slug_1": ai.values[1],
        "slug_2": "some_local_file",
    },
]

Parameters:

• archive (Union[str, Archive]) –

  slug for the archive (e.g. "i-am-an-archive"). You can find this readily in the URL you use to visit the archive page: https://grand-challenge.org/archives/i-am-an-archive/

• archive_items (list[SocketValueSetDescription]) –

  The format for the descriptions of archive items are as follows:

  [
      {
          "slug_0": ["filepath_0", ...],
          "slug_1": "filepath_0",
          "slug_2": pathlib.Path("filepath_0"),
          ...
          "slug_n": {"json": "value"}
  
      },
      ...
  ]
  

  Where the file paths are local paths to the files making up a single image. For file-kind sockets the file path can only reference a single file. For json-kind sockets any value that is valid for the sockets can directly be passed, or a filepath to a file that contain the value can be provided.

Returns:

• list[str] –

  The pks of the newly created archive items.

add_cases_to_reader_study

add_cases_to_reader_study(
    *,
    reader_study: Union[str, ReaderStudy],
    display_sets: list[SocketValueSetDescription]
) -> list[str]

This function takes an reader-study slug or model and a list of display-set descriptions. It then creates the display-sets for the reader study.

Re-using existing images

Existing images on Grand Challenge can be re-used by either passing an API url, or a socket value (display set):

    image = client.images.detail(pk="ad5...")
    ds = client.reader_studies.display_sets.detail(pk="f5...")
    socket_value = ds.values[0]

    display_sets = [
        {
            "slug_0": image.api_url,
            "slug_1": socket_value,
            "slug_2": socket_value.image,
        }
    ]

One can also provide a same-socket socket value:

ds = client.reader_studies.display_sets.detail(pk="f5...")
display_sets = [
    {
        "slug_0": ds.values[0],
        "slug_1": ds.values[1],
        "slug_2": "some_local_file",
    },
]

Parameters:

• reader_study (Union[str, ReaderStudy]) –

  slug for the reader study (e.g. "i-am-a-reader-study"). You can find this readily in the URL you use to visit the reader-study page: https://grand-challenge.org/reader-studies/i-am-a-reader-study/

• display_sets (list[SocketValueSetDescription]) –

  The format for the descriptions of display sets are as follows:

  [
      {
          "slug_0": ["filepath_0", ...],
          "slug_1": "filepath_0",
          "slug_2": pathlib.Path("filepath_0"),
          ...
          "slug_n": {"json": "value"}
  
      },
      ...
  ]
  

  Where the file paths are local paths to the files making up a single image. For file-kind sockets the file path can only reference a single file. For json-kind sockets any value that is valid for the sockets can directly be passed, or a filepath to a file that contain the value can be provided.

Returns:

• list[str] –

  The pks of the newly created display sets.

run_external_job

run_external_job(
    *,
    algorithm: Union[str, Algorithm],
    inputs: SocketValueSetDescription
) -> gcapi.models.JobPost

Starts an algorithm job with the provided inputs.

Getting the interfaces of an algorithm

You can get the interfaces (i.e. all possible socket sets) of an algorithm by calling, and inspecting the .interface of the result of:

client.algorithms.detail(slug="corads-ai")

Re-using existing images

Existing images on Grand Challenge can be re-used by either passing an API url, or a socket value:

image = client.images.detail(pk="ad5...")
# Alternatively, you can also use:
ai = client.archive_items.detail(pk="f5...")
socket_value = ai.values[0]

archive_items = [
    {
        "slug_0": image.api_url,
        "slug_1": socket_value,
        "slug_2": socket_value.image.api_url,
    }
]

One can also provide a same-socket socket value:

ai = client.archive_items.detail(pk="f5...")
archive_items = [
    {
        "slug_0": ai.values[0],
        "slug_1": ai.values[1],
        "slug_2": "some_local_file",
    },
]

Parameters:

• algorithm (Union[str, Algorithm]) –

  You can find this in the url of the algorithm that you want to use. For instance, if you want to use the algorithm at: https://grand-challenge.org/algorithms/corads-ai/ the slug for this algorithm is "corads-ai".

  inputs (SocketValueSetDescription): For each input socket defined on the algorithm you need to provide a key-value pair, the key being the slug of the socket, the value being the value for the socket::

  {
      "slug_0": ["filepath_0", ...],
      "slug_1": "filepath_0",
      "slug_2": pathlib.Path("filepath_0"),
      ...
      "slug_n": {"json": "value"},
  }
  

  Where the file paths are local paths to the files making up a single image. For file-kind sockets the file path can only reference a single file. For json-kind sockets any value that is valid for the sockets can directly be passed, or a filepath to a file that contain the value can be provided.

Returns:

• JobPost –

  The created job

update_archive_item

update_archive_item(
    *,
    archive_item_pk: str,
    values: SocketValueSetDescription
) -> gcapi.models.ArchiveItemPost

This function updates an existing archive item with the provided values and returns the updated archive item.

You can use this function, for example, to add metadata to an archive item.

If you provide a value or file for an existing socket of the archive item, the old value will be overwritten by the new one, hence allowing you to update existing archive item values.

Example

First, retrieve the archive items from your archive:

archive = client.archives.detail(slug="...")
items = list(
    client.archive_items.iterate_all(params={"archive": archive.pk})
)

To then add, for example, a PDF report and a lung volume value to the first archive item , provide the socket slugs together with the respective value or file path as follows:

client.update_archive_item(
    archive_item_pk=items[0].id,
    values={
        "report": [...],
        "lung-volume": 1.9,
    },
)

Parameters:

• archive_item_pk (str) –

  The primary key of the archive item to update.

• values (SocketValueSetDescription) –

  The values to update the archive item with.

Returns:

• ArchiveItemPost –

  The updated archive item

update_display_set

update_display_set(
    *,
    display_set_pk: str,
    values: SocketValueSetDescription
) -> gcapi.models.DisplaySetPost

This function updates an existing display set with the provided values and returns the updated display set.

You can use this function, for example, to add metadata to a display set.

If you provide a value or file for an existing interface of the display set, the old value will be overwritten by the new one, hence allowing you to update existing display-set values.

Example

First, retrieve the display_set from your archive:

reader_study = client.reader_studies.detail(slug="...")
items = list(
    client.reader_studies.display_sets.iterate_all(
        params={"reader_study": reader_study.pk}
    )
)

To then add, for example, a PDF report and a lung volume value to the first display set , provide the interface slugs together with the respective value or file path as follows:

client.update_display_set(
    display_set_pk=items[0].id,
    values={
        "report": [...],
        "lung-volume": 1.9,
    },
)

Parameters:

• display_set_pk (str) –

  The primary key of the display set to update.

• values (SocketValueSetDescription) –

  The values to update the display set with.

Returns:

• DisplaySetPost –

  The updated display set