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, 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: (
        Callable[[], BaseRetryStrategy] | None
    ) = None,
    max_concurrent_downloads: int = 10,
)

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.
verify (bool, default: True ) –

Whether to verify SSL certificates.
timeout (float, default: 60.0 ) –

Request timeout in seconds.
retry_strategy (Callable[[], BaseRetryStrategy] | None, default: None ) –

Factory function that returns a retry strategy instance. If None, uses SelectiveBackoffStrategy with default parameters.
max_concurrent_downloads (int, default: 10 ) –

Maximum number of concurrent downloads allowed.

add_case_to_archive ¤

add_case_to_archive(
    *, archive_slug: str, values: list[SocketValueSpec]
) -> gcapi.models.ArchiveItemPost

This function takes an archive slug and a list of socket value specs. It then creates a single archive item for the archive.

Example

from gcapi import SocketValueSpec

client.add_case_to_archive(
    archive_slug="i-am-an-archive",
    values=[
        SocketValueSpec(socket_slug="report", file="report.pdf"),
        SocketValueSpec(socket_slug="lung-volume", value=1.9),
    ],
)

Re-using existing images

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

from gcapi import SocketValueSpec

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

values = [
    SocketValueSpec(socket_slug="slug-0", existing_image_api_url=image.api_url),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=socket_value),
    SocketValueSpec(socket_slug="slug-2", existing_image_api_url=socket_value.image),
]

Re-using existing socket values

Existing socket values from other archive items can be re-used by passing a socket value. The sockets must be the same.

For instance:

from gcapi import SocketValueSpec

ai = client.archive_items.detail(pk="f5...")
values = [
    SocketValueSpec(socket_slug="slug-0", existing_socket_value=ai.values[0]),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=ai.values[1]),
    SocketValueSpec(socket_slug="slug-2", file="some_local_file"),
]

Parameters:

archive_slug (str) –

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/
values (list[SocketValueSpec]) –

A list of socket value specifications. Each specification defines a socket slug and exactly one source (value, file, files, existing_image_api_url, or existing_socket_value).

Returns:

ArchiveItemPost –

The new archive item (post) object. Note that not all values will be immediately available until the background processing has completed.

add_case_to_reader_study ¤

add_case_to_reader_study(
    *, reader_study_slug: str, values: list[SocketValueSpec]
) -> gcapi.models.DisplaySetPost

This function takes a reader-study slug and a list of socket value specs. It then creates a single display set for the reader study.

Example

from gcapi import SocketValueSpec

client.add_case_to_reader_study(
    reader_study_slug="i-am-a-reader-study",
    values=[
        SocketValueSpec(socket_slug="report", file="report.pdf"),
        SocketValueSpec(socket_slug="lung-volume", value=1.9),
    ],
)

Re-using existing images

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

from gcapi import SocketValueSpec


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

values = [
    SocketValueSpec(socket_slug="slug-0", existing_image_api_url=image.api_url),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=socket_value),
    SocketValueSpec(socket_slug="slug-2", existing_image_api_url=socket_value.image),
]

Re-using existing socket values

Existing socket values from other display sets can be re-used by passing a socket value. The sockets must be the same.

For instance:

from gcapi import SocketValueSpec


ds = client.reader_studies.display_sets.detail(pk="f5...")
values = [
    SocketValueSpec(socket_slug="slug-0", existing_socket_value=ds.values[0]),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=ds.values[1]),
]

Parameters:

reader_study_slug (str) –

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/
values (list[SocketValueSpec]) –

A list of socket value specifications. Each specification defines a socket slug and exactly one source (value, file, files, existing_image_api_url, or existing_socket_value).

Returns:

DisplaySetPost –

The newly created display set (post) object. Note that not all values will be immediately available until the background processing has completed.

add_cases_to_archive ¤

add_cases_to_archive(*_, **__) -> Any

Failure

Use add_case_to_archive instead. This method will be removed in a future version.

add_cases_to_reader_study ¤

add_cases_to_reader_study(*_, **__) -> Any

Failure

Use add_case_to_reader_study instead. This method will be removed in a future version.

download_socket_value ¤

download_socket_value(
    value: HyperlinkedComponentInterfaceValue,
    *,
    output_directory: Path
)

Download a socket value to the specified output directory.

Uses the socket's relative path to determine the filename. The relative path is fixed and unique per socket, so downloading multiple different values will not overwrite each other.

In addition, if the file to be downloaded already exists in the output directory, a FileExistsError is raised to prevent overwriting existing files.

Parameters:

value (HyperlinkedComponentInterfaceValue) –

The socket value to download.
output_directory (Path) –

The directory to download the value into.

run_external_job ¤

run_external_job(*_, **__) -> Any

Failure

Use start_algorithm_job instead. This method will be removed in a future version.

start_algorithm_job ¤

start_algorithm_job(
    *, algorithm_slug: str, inputs: list[SocketValueSpec]
) -> 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 an existing socket value:

from gcapi import SocketValueSpec

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

inputs = [
    SocketValueSpec(socket_slug="slug-0", existing_image_api_url=image.api_url),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=socket_value),
    SocketValueSpec(socket_slug="slug-2", existing_image_api_url=socket_value.image),
]

Re-using existing socket values

Existing socket values from other display sets can be re-used by passing a socket value. The sockets must be the same.

For instance:

from gcapi import SocketValueSpec

ds = client.reader_studies.display_sets.detail(pk="f5...")
inputs = [
    SocketValueSpec(socket_slug="slug-0", existing_socket_value=ds.values[0]),
    SocketValueSpec(socket_slug="slug-1", existing_socket_value=ds.values[1]),
]

Parameters:

algorithm_slug (str) –

Slug for the algorithm (e.g. "corads-ai"). You can find this readily in the URL you use to visit the algorithm page: https://grand-challenge.org/algorithms/corads-ai/
inputs (list[SocketValueSpec]) –

A list of socket value specifications. Each specification defines a socket slug and exactly one source (value, file, files, existing_image_api_url, or existing_socket_value).

Returns:

JobPost –

The newly created Job (post) object. Note that not all inputs will be immediately available until the background processing has completed.

update_archive_item ¤

update_archive_item(
    *, archive_item_pk: str, values: list[SocketValueSpec]
) -> gcapi.models.ArchiveItemPost

This function patches an existing archive item with the provided values.

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:

from gcapi import SocketValueSpec

client.update_archive_item(
    archive_item_pk=items[0].pk,
    values=[
        SocketValueSpec(socket_slug="report", file="report.pdf"),
        SocketValueSpec(socket_slug="lung-volume", value=1.9),
    ],
)

Parameters:

archive_item_pk (str) –

The primary key of the archive item to update.
values (list[SocketValueSpec]) –

A list of socket value specifications. Each specification defines a socket slug and exactly one source (value, file, files, existing_image_api_url, or existing_socket_value).

Returns:

ArchiveItemPost –

The updated archive item (post) object. Note that not all values will be immediately available until the background processing has completed.

update_display_set ¤

update_display_set(
    *, display_set_pk: str, values: list[SocketValueSpec]
) -> gcapi.models.DisplaySetPost

This function patches an existing display set with the provided values.

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

If you provide a value or file for an existing socket 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 sets from your reader study:

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 socket slugs together with the respective value or file path as follows:

from gcapi import SocketValueSpec

client.update_display_set(
    display_set_pk=items[0].pk,
    values=[
        SocketValueSpec(socket_slug="report", file="report.pdf"),
        SocketValueSpec(socket_slug="lung-volume", value=1.9),
    ],
)

Parameters:

display_set_pk (str) –

The primary key of the display set to update.
values (list[SocketValueSpec]) –

A list of socket value specifications. Each specification defines a socket slug and exactly one source (value, file, files, existing_image_api_url, or existing_socket_value).

Returns:

DisplaySetPost –

The updated display item (post) object. Note that not all values will be immediately available until the background processing has completed.

Client

__call__ ¤

__init__ ¤

add_case_to_archive ¤

add_case_to_reader_study ¤

add_cases_to_archive ¤

add_cases_to_reader_study ¤

download_socket_value ¤

run_external_job ¤

start_algorithm_job ¤

update_archive_item ¤

update_display_set ¤

call ¤

init ¤