Page Comparison

NOTE: The Competition services are still under development and are not yet available on Synapse.

Overview

The Competition Evaluation API is designed to support open-access Synapse data analysis and modeling challenges. This framework provides tools for administrators to create new competitions evaluations in Synapse and manage the users and data objects associated with a competition. A competition an evaluation. An evaluation owner can control access to competition evaluation resources and registration, as well as track user participation and evaluate submitted models. This API will support user-facing interfaces to monitor competitions evaluations including activity notifications and on-demand scoring and leaderboarding.

Data Models

Synapse Competitions Evaluations are constructed around three primary objects: Competition, Participant, Evaluation and Submission. These objects are defined by eponymous JSON schema files in the Synapse Repository Services. CompetitionThe UMLet file used to generate the following image is available here.

Image Added

Evaluation
Object representing a Synapse CompetitionEvaluation

ID - unique ID for the CompetitionEvaluation
eTag - optimistic concurrency flag; changes with each update
ownerID - user principal ID of the owner of the CompetitionEvaluation
name
description
contentSource - ID of the data source (e.g. entity) for the Competition Evaluation (string)
status - enum describing the state of the CompetitionEvaluation, one of: PLANNED, OPEN, CLOSED, COMPLETED

Participant
Immutable object to represent a single user participating in a Competition. Competitions can have many users, and users can participate in many Competitions.

ownerID - user ID of the Participant
competitionID
createdOn - join date

Submission
Immutable object to represent an entity submission to a CompetitionEvaluation. A participant can create many Submissions for a given CompetitionEvaluation.

ID - unique ID for the Submission
name
ownerID - user principal ID of the Submission owner
competitionIDevaluationID
entityID - ID of the submitted entity
version - specific entity version
createdOn - submission date
submitterAlias - the alias for the user or team creating the submission

SubmissionStatus
Object to track the status and score of a specific Submission. This object is generated at the time of submission, and can be modified by Competition Evaluation administrators.

submissionID
eTag - optimistic concurrency flag; changes with each update
status - enum describing the state of the Submission, one of: OPEN, CLOSED, SCORED, INVALID
score - numerical score for this Submission (long)

REST API

...

double between 0 and 1)
report - String describing this Submission and/or its scoring. May contain additional scoring information, error logs, etc.
annotations - Annotations object containing user-defined key-value annotations. Note: The contents of the annotations are mirrored to a second set of tables optimized for querying, as discussed here.

SubmissionBundle
Bundle object containing a Submission and its accompanying SubmissionStatus.

SubmissionStatusBatch

Used to upload a collection of Submission updates at once.

REST API

Evaluation

URL	HTTP Type	Description	Request Parameters
/competitionevaluation	POST	Create a new Competition Evaluation	userId (String)
/competitionevaluation/{competitionIdevaluationId}	GET	Get a Competition	Evaluation
/competitionevaluation/{competitionIdevaluationId}	PUT	Update a CompetitionEvaluation	userId (String)
/competitionevaluation/{competitionIdevaluationId}	DELETE	Delete a CompetitionuserId (String)Evaluation
/competitionevaluation	GET	Batch Get Competitions Evaluations (Paginated) Optional request parameters: limit (long) , offset (long)
/competitionevaluation/count	GET	Get the number of Competitions Evaluations
/competitionevaluation/name/{name}	GET	Find a Competition Evaluation by name

Participant

URL	HTTP Type	Description	Request Parameters
/competition/{competitionId}/participant	POST	Join as a Participant in a Competition	userId (String)
/competition/{competitionId}/participant/{userId}	POST	Add another user as a Participant in a Competition. Requires admin rights on the Competition.	userId (String)
/competition/{competitionId}/participant/{userId}	GET	Get a Participant
/competition/{competitionId}/participant/{userId}	DELETE	Delete a Participant	userId (String)
/competition/{competitionId}/participant/	GET	Batch get Participants for a given Competition (Paginated)
/competition/{competitionId}/participant/count	GET	Get the number of Participants in a given Competition

Note that the name must be URL-encoded
/evaluation/available	GET	Get the paginated list of Evaluations which the user has joined as a participant. Optional request parameters: limit (long), offset (long), status (OPEN,CLOSED,...)

Submission

Request ParametersuserId (String

URL	HTTP Type	Description
/competitionevaluation/submission?etag=<etag>	POST	Create a new Submission . (and corresponding SubmissionStatus object)	. Requires the current etag of the Entity in the Submission. Required request parameter: etag (string)
/competitionevaluation/submission/{submissionId}	GET	Get a Submission	Requires ownership of the Submission, or admin rights on the Evaluation.
/competitionevaluation/submission/{submissionId}/status	GET	Get the status of a Submission
/competitionevaluation/submission/{submissionId}/status	PUT	Update the status of a Submission. Requires admin rights on the CompetitionEvaluation	userId (String)
/competitionevaluation/submission/{submissionId}	DELETE	Delete a Submission. Requires admin rights on the Competition.	userId (String)	/competition/{compId}/submissionEvaluation.
/evaluation/{evaluationId}/submission/ /evaluation/{evaluationId}/submission/bundle/	GET	Batch get my Submissions/SubmissionBundles for a given Evaluation. Results are paginated. Returns only Submissions owned by the requesting user. Optional request parameters: limit (long), offset (long)
/evaluation/{evaluationId}/submission/all /evaluation/{evaluationId}/submission/status/all /evaluation/{evaluationId}/submission/bundle/all	GET	Batch get Submissions/SubmissionStatuses/SubmissionBundles for a given Competition (Paginated)Evaluation. Results are paginated. Requires admin rights on the CompetitionEvaluation. Can be filtered by status enum. userId SubmissionStatusEnum. Optional request parameters: status (String) SubmissionStatusEnum , limit ( String long) (optional , offset (long)
/evaluation/submission/{submissionId}/file/{fileHandleId}	GET	Get a temporary pre-signed URL to a File contained within a specified Submission. Requires admin rights on the Evaluation. Optional request parameter: redirect (Boolean)
/competitionevaluation/{compIdevaluationId}/submission/count	GET	Get the number of Submissions for a given Competition		Evaluation.

Access Restrictions

Access Restrictions and approvals may be applied to Evaluations. For details on the API see: Data Access Control

cURL Examples

Evaluation

Create an Evaluation

Code Block

curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
    "status":"PLANNED",
    "description":"description",
    "name":"my first evaluation",
    "contentSource":"contentSource"
}' https://repo-staging.prod.sagebase.org/repo/v1/evaluation

Get an Evaluation

Code Block
curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json 'https://repo-staging.prod.sagebase.org/repo/v1/evaluation/1588317'

Update an Evaluation

Code Block

curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
    "id":"1588317",
    "createdOn":"2013-01-16T16:30:56.727Z",
    "etag":"eed22bca-d88e-4b4a-8b1a-35dca7b7b8db",
    "status":"OPEN",
    "description":"description",
    "ownerId":"1588313",
    "name":"my first evaluation",
    "contentSource":"contentSource"
}' https://repo-staging.prod.sagebase.org/repo/v1/evaluation/1588317

Delete an Evaluation

Code Block
curl -i -k -H sessionToken:okxkSRyl3v0iIf0eutQfXA00 -H Accept:application/json -X DELETE 'https://repo-staging.prod.sagebase.org/repo/v1/evaluation/1588317'

Participant

Create a Participant

Code Block

curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
    "ownerId":"123456"
}' https://repo-staging.prod.sagebase.org/repo/v1/evaluation/987654/participant

Delete a Participant

Code Block
curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -X DELETE 'https://repo-staging.prod.sagebase.org/repo/v1/evaluation/1588317/participant/1588313'

Submission

Create a Submission

Code Block

curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -d '{
    "evaluationId":"1588317",
    "entityId":"1588315",
    "versionNumber":"1",
    "name":"some-name"
}' https://repo-staging.prod.sagebase.org/repo/v1/evaluation/submission

Update a SubmissionStatus

Code Block

curl -i -k -H sessionToken:xxxxxxxxxxxxxxxx -H Accept:application/json -H Content-Type:application/json -X PUT -d '{
    "id":"1589914",
    "modifiedOn":"2013-01-18T21:43:18.897Z",
    "etag":"13c88b1a-662c-4dd6-bb56-3976566516f7",
    "status":"SCORED",
    "score":0.42
}' https://repo-staging.prod.sagebase.org/repo/v1/evaluation/submission/1589914/status

Delete a Submission

Code Block
curl -i -k -H sessionToken:dPF2TqGUq121PR36AwJhXw00 -H Accept:application/json -X DELETE 'https://repo-staging.prod.sagebase.org/repo/v1/evaluation/submission/1589912'

Example Workflow

The following is a proposed workflow for interacting with the Competition Evaluation Services. Please note that some components are still under development.

User Perspective

Find a Synapse CompetitionEvaluation
Sign up as a Participant
Download relevant Synapse Entities referenced in CompetitionEvaluation
Submit a Synapse entity to the CompetitionEvaluation
Track status of personal Submissions and view global competition Evaluation status/leaderboard
Earn achievements for participation / success

Owner/Admin Perspective

Create a Synapse CompetitionEvaluation
1. Fill in details, attach relevant Synapse entities
2. Specify access requirements
3. Specify open/close dates
Listen for Submissions (using messaging service)
1. Download unscored Submissions
2. Perform scoring
3. Push scores back to each SubmissionStatus
Track user participation and publish competition Evaluation status/leaderboard
Award achievements for user participation / success

Planned

...

Improvements

The following Competition Services features are planned but not yet implemented.

Banned user lists
Banned users should be prohibited from participating in one or more CompetitionsEvaluations, and any Submissions by a banned user should be isolated from the general populations of Submissions.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
serverId ba6fb084-9827-3160-8067-8ac7470f78b2
key PLFM-1646
Customizable Amazon Simple Notification Services messaging tools
Competition Evaluation administrators should have tools to configure a selective Amazon instance to listen for messages pertaining to Competitions Evaluations which they own. These messages should be sent to a queue dedicated to CompetitionsEvaluations.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
serverId ba6fb084-9827-3160-8067-8ac7470f78b2
key PLFM-1647
Immutable copies of the submitted Entities
Once an Entity is submitted to a CompetitionEvaluation, a static copy of that Entity should become the property of the Competition Evaluation administration.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
serverId ba6fb084-9827-3160-8067-8ac7470f78b2
key PLFM-1648
Administrator lists for CompetitionsEvaluations
Competitions Evaluations should support administration by multiple users (rather than just the Competition Evaluation owner). These admin lists should function as a lightweight ACL of sorts.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
keyserverId PLFMba6fb084-1649
Multi-author Submissions
Competitions should support team Submissions, where more than one Synapse user claims authorship of a given Submission.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
key PLFM-1650
Pagination support for fetching Participants and Submissions
Currently the API supports fetching all Participants or all Submissions for a given Competition. To support high-volume Competitions, pagination shoudl be supported on these requests.
Jira Legacy
server JIRA (sagebionetworks.jira.com)
9827-3160-8067-8ac7470f78b2
key PLFM-16511649

Versions Compared

Old Version 18

New Version Current

Key

Table of Contents

Overview

Data Models

REST API

REST API

Access Restrictions

cURL Examples

Evaluation

Participant

Submission

Example Workflow

Planned

Improvements