panoptes_client package

As a convenience, the following classes can be imported directly from the root of the panoptes_client package:

• Panoptes
• Classification
• Collection
• Project
• ProjectPreferences
• Subject
• SubjectSet
• User
• Workflow
• Caesar

For example:

from panoptes_client import Panoptes, Project

Panoptes.connect(username='example', password='example')

new_project = Project()
new_project.display_name = 'My new project'
new_project.description = 'A great new project!'
new_project.primary_language = 'en'
new_project.private = True
new_project.save()

panoptes_client.panoptes module

class panoptes_client.panoptes.LinkCollection(cls, slug, parent, linked_objects)

Bases: object

A collection of PanoptesObject of one class which are linked to a parent PanoptesObject.

Allows indexing, iteration, and membership testing:

project = Project(1234)

print(project.links.workflows[2].display_name)

for workflow in project.links.workflows:
    print(workflow.id)

if Workflow(5678) in project.links.workflows:
    print('Workflow found')

# Integers, strings, and PanoptesObjects are all OK
if 9012 not in project.links.workflows:
    print('Workflow not found')

add(objs)

Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObject instance, or a single object ID.

Examples:

organization.links.projects.add(1234)
organization.links.projects.add(Project(1234))
workflow.links.subject_sets.add([1,2,3,4])
workflow.links.subject_sets.add([Project(12), Project(34)])

remove(objs)

Removes the given objs from this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObject instance, or a single object ID.

Examples:

organization.links.projects.remove(1234)
organization.links.projects.remove(Project(1234))
workflow.links.subject_sets.remove([1,2,3,4])
workflow.links.subject_sets.remove([Project(12), Project(34)])

exception panoptes_client.panoptes.ObjectNotSavedException

Bases: Exception

Raised if an attempt is made to perform an operation on an unsaved PanoptesObject which requires the object to be saved first.

class panoptes_client.panoptes.Panoptes(endpoint=None, client_id=None, client_secret=None, redirect_url=None, username=None, password=None, login=None, admin=False)

Bases: object

The low-level Panoptes HTTP client class. Use this class to log into the API. In most cases you can just call Panoptes.connect() once and all subsequent API requests will be authenticated.

If you want to configure multiple clients, e.g. to perform operations as multiple users, you should initialise the client as a context manager, using the with statement instead of using Panoptes.connect(). In this example, we modify a project by authenticating as the project owner, then log in as a regular user to add a subject to a collection, then switch back to the project owner’s account to retire some subjects:

owner_client = Panoptes(username='example-project-owner', password='')

with owner_client:
    project = Project(1234)
    project.display_name = 'New name'
    project.save()

with Panoptes(username='example-user', password=''):
    Collection(1234).add(Subject(1234))

with owner_client:
    Workflow(1234).retire_subjects([1234, 5678, 9012])

Using the with statement in this way ensures it is clear which user will be used for each action.

classmethod connect(username=None, password=None, endpoint=None, admin=False)

Configures the Panoptes client for use.

Note that there is no need to call this unless you need to pass one or more of the below arguments. By default, the client will connect to the public Zooniverse.org API as an anonymous user.

All arguments are optional:

• username is your Zooniverse.org username.
• password is your Zooniverse.org password.
• endpoint is the HTTP API endpoint you’d like to connect to. Defaults to https://www.zooniverse.org. Should not include a trailing slash.
• admin is a boolean, switching on admin mode if True. Has no effect if the given username is not a Zooniverse.org administrator.

Examples:

Panoptes.connect(username='example', password='example')
Panoptes.connect(endpoint='https://panoptes.example.com')

exception panoptes_client.panoptes.PanoptesAPIException

Bases: Exception

Raised whenever the API returns an error. The exception will contain the raw error message from the API.

class panoptes_client.panoptes.PanoptesObject(raw={}, etag=None)

Bases: object

The base class of all Panoptes model classes. You should never need to create instances of this class, but the methods defined here are common to all the model subclasses.

`PanoptesObject`s support lazy loading of attributes, where data is loaded from the API only when it is first accessed. You can do this by passing an object ID to the contructor:

project = Project(1234)
print(project.display_name)

This will not make any HTTP requests until the print statement.

delete()

Deletes the object. Returns without doing anything if the object is new.

classmethod find(_id)

Returns the individual instance with the given ID, if it exists. Raises PanoptesAPIException if the object with that ID is not found.

reload()

Re-fetches the object from the API, discarding any local changes. Returns without doing anything if the object is new.

save()

Saves the object. If the object has not been saved before (i.e. it’s new), then a new object is created. Otherwise, any changes are submitted to the API.

classmethod where(**kwargs)

Returns a generator which yields instances matching the given query arguments.

For example, this would yield all Project:

Project.where()

And this would yield all launch approved Project:

Project.where(launch_approved=True)

exception panoptes_client.panoptes.ReadOnlyAttributeException

Bases: Exception

Raised if an attempt is made to modify an attribute of a PanoptesObject which the API does not allow to be modified.

panoptes_client.classification module

class panoptes_client.classification.Classification(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

classmethod where(scope=None, **kwargs)

Like PanoptesObject.where(), but also allows setting the query scope.

• scope can be any of the values given in the Classification Collection API documentation without the leading slash.

Examples:

my_classifications = Classification.where()
my_proj_123_classifications = Classification.where(project_id=123)

all_proj_123_classifications = Classification.where(
    scope='project',
    project_id=123,
)

panoptes_client.collection module

class panoptes_client.collection.Collection(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

add(subjects)

A wrapper around LinkCollection.add(). Equivalent to:

collection.links.add(subjects)

classmethod find(id='', slug=None)

Similar to PanoptesObject.find(), but allows lookup by slug as well as ID.

Examples:

collection_1234 = Collection.find(1234)
my_collection = Collection.find(slug="example/my-collection")

remove(subjects)

A wrapper around LinkCollection.remove(). Equivalent to:

collection.links.remove(subjects)

set_default_subject(subject)

Sets the subject’s location media URL as a link. It displays as the default subject on PFE.

• subject can be a single Subject instance or a single subject ID.

Examples:

collection.set_default_subject(1234)
collection.set_default_subject(Subject(1234))

subjects

A generator which yields each Subject in this collection.

panoptes_client.exportable module

class panoptes_client.exportable.Exportable

Bases: object

Abstract class containing methods for generating and downloading data exports.

describe_export(export_type)

Fetch metadata for an export.

• export_type is a string specifying which type of export to look up.

Returns a dict containing metadata for the export.

generate_export(export_type)

Start a new export.

• export_type is a string specifying which type of export to start.

Returns a dict containing metadata for the new export.

get_export(export_type, generate=False, wait=False, wait_timeout=None)

Downloads a data export over HTTP. Returns a Requests Response object containing the content of the export.

• export_type is a string specifying which type of export should be downloaded.
• generate is a boolean specifying whether to generate a new export and wait for it to be ready, or to just download the latest export.
• wait is a boolean specifying whether to wait for an in-progress export to finish, if there is one. Has no effect if generate is True.
• wait_timeout is the number of seconds to wait if wait is True. Has no effect if wait is False or if generate is True.

The returned Response object has two additional attributes as a convenience for working with the CSV content; csv_reader and csv_dictreader, which are wrappers for csv.reader() and csv.DictReader respectively. These wrappers take care of correctly decoding the export content for the CSV parser.

Example:

classification_export = Project(1234).get_export('classifications')
for row in classification_export.csv_reader():
    print(row)

classification_export = Project(1234).get_export('classifications')
for row in classification_export.csv_dictreader():
    print(row)

wait_export(export_type, timeout=None)

Blocks until an in-progress export is ready.

• export_type is a string specifying which type of export to wait for.
• timeout is the maximum number of seconds to wait.

If timeout is given and the export is not ready by the time limit, PanoptesAPIException is raised.

panoptes_client.project module

class panoptes_client.project.Project(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_attached_image(src, content_type='image/png', external_link=True, metadata={})

add_subject_sets(subject_sets)

Links the given subject sets to this project. New subject sets are created as copies of the given sets.

• subject_sets can be a list of SubjectSet instances, a list of subject set IDs, a single SubjectSet instance, or a single subject set ID.

Examples:

project.add_subject_sets(1234)
project.add_subject_sets([1,2,3,4])
project.add_subject_sets(SubjectSet(1234))
project.add_subject_sets([SubjectSet(12), SubjectSet(34)])

add_workflows(workflows)

Links the given workflows to this project. New workflows are created as copies of the given workflows.

• workflows can be a list of Workflow instances, a list of workflow IDs, a single Workflow instance, or a single workflow ID.

Examples:

project.add_workflows(1234)
project.add_workflows([1,2,3,4])
project.add_workflows(Workflow(1234))
project.add_workflows([Workflow(12), Workflow(34)])

attached_images

avatar

A dict containing metadata about the project’s avatar.

collaborators(*roles)

Returns a list of User who are collaborators on this project.

Zero or more role arguments can be passed as strings to narrow down the results. If any roles are given, users who possess at least one of the given roles are returned.

Examples:

all_collabs = project.collaborators()
moderators = project.collaborators("moderators")
moderators_and_translators = project.collaborators(
    "moderators",
    "translators",
)

copy(new_subject_set_name=None)

Copy this project to a new project that will be owned by the currently authenticated user.

A new_subject_set_name string argument can be passed which will be used to name a new SubjectSet for the copied project. This is useful for having an upload target straight after cloning.

Examples:

project.copy()
project.copy("My new subject set for uploading")

classmethod find(id='', slug=None)

Similar to PanoptesObject.find(), but allows lookup by slug as well as ID.

Examples:

project_1234 = Project.find(1234)
galaxy_zoo = Project.find(slug="zooniverse/galaxy-zoo")

save()

Adds project configuration to the list of savable attributes if it has changed.

set_raw(raw, etag=None, loaded=True)

class panoptes_client.project.ProjectLinkCollection(cls, slug, parent, linked_objects)

Bases: panoptes_client.panoptes.LinkCollection

add(objs)

Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObject instance, or a single object ID.

Examples:

organization.links.projects.add(1234)
organization.links.projects.add(Project(1234))
workflow.links.subject_sets.add([1,2,3,4])
workflow.links.subject_sets.add([Project(12), Project(34)])

panoptes_client.project_preferences module

class panoptes_client.project_preferences.ProjectPreferences(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

Contains the settings for a User on a Project.

classmethod find(id='', user=None, project=None)

Like PanoptesObject.find() but can also query by user and project.

• user and project can be either a User and Project instance respectively, or they can be given as IDs. If either argument is given, the other is also required.

classmethod save_settings(project=None, user=None, settings=None)

Save settings for a user without first fetching their preferences.

• user and project can be either a User and Project instance respectively, or they can be given as IDs. If either argument is given, the other is also required.
• settings is a dict containing the settings to be saved.

panoptes_client.subject module

class panoptes_client.subject.Subject(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

add_location(location)

Add a media location to this subject.

• location can be an open file object, a path to a local file, or a dict containing MIME types and URLs for remote media.

Examples:

subject.add_location(my_file)
subject.add_location('/data/image.jpg')
subject.add_location({'image/png': 'https://example.com/image.png'})

async_save_result

Retrieves the result of this subject’s asynchronous save.

• Returns True if the subject was saved successfully.
• Raises concurrent.futures.CancelledError if the save was cancelled.
• If the save failed, raises the relevant exception.
• Returns False if the subject hasn’t finished saving or if the subject has not been queued for asynchronous save.

classmethod async_saves()

Returns a context manager to allow asynchronously creating subjects. Using this context manager will create a pool of threads which will create multiple subjects at once and upload any local files simultaneously.

The recommended way to use this is with the with statement:

with Subject.async_saves():
    local_files = [...]
    for filename in local_files:
        s = Subject()
        s.links.project = 1234
        s.add_location(filename)
        s.save()

Alternatively, you can manually shut down the thread pool:

pool = Subject.async_saves()
local_files = [...]
try:
    for filename in local_files:
        s = Subject()
        s.links.project = 1234
        s.add_location(filename)
        s.save()
finally:
    pool.shutdown()

save(client=None)

Like PanoptesObject.save(), but also uploads any local files which have previosly been added to the subject with add_location(). Automatically retries uploads on error.

If multiple local files are to be uploaded, several files will be uploaded simultaneously to save time.

set_raw(raw, etag=None, loaded=True)

subject_workflow_status(workflow_id)

Returns SubjectWorkflowStatus of Subject in Workflow

Example:

subject.subject_workflow_status(4321)

exception panoptes_client.subject.UnknownMediaException

Bases: Exception

panoptes_client.subject_set module

class panoptes_client.subject_set.SubjectSet(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add(subjects)

A wrapper around LinkCollection.add(). Equivalent to:

subject_set.links.add(subjects)

remove(subjects)

A wrapper around LinkCollection.remove(). Equivalent to:

subject_set.links.remove(subjects)

set_raw(raw, etag=None, loaded=True)

subject_workflow_statuses(workflow_id)

A generator which yields SubjectWorkflowStatus objects for subjects in this subject set and for the supplied workflow id.

Examples:

for status in subject_set.subject_workflow_statuses(1234):
    print(status.retirement_reason)

subjects

A generator which yields Subject objects which are in this subject set.

Examples:

for subject in subject_set.subjects:
    print(subject.id)

class panoptes_client.subject_set.SubjectSetLinkCollection(cls, slug, parent, linked_objects)

Bases: panoptes_client.panoptes.LinkCollection

add(objs)

Adds the given objs to this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObject instance, or a single object ID.

Examples:

organization.links.projects.add(1234)
organization.links.projects.add(Project(1234))
workflow.links.subject_sets.add([1,2,3,4])
workflow.links.subject_sets.add([Project(12), Project(34)])

remove(objs)

Removes the given objs from this LinkCollection.

• objs can be a list of PanoptesObject instances, a list of object IDs, a single PanoptesObject instance, or a single object ID.

Examples:

organization.links.projects.remove(1234)
organization.links.projects.remove(Project(1234))
workflow.links.subject_sets.remove([1,2,3,4])
workflow.links.subject_sets.remove([Project(12), Project(34)])

panoptes_client.user module

class panoptes_client.user.User(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

avatar

A dict containing metadata about the user’s avatar.

classmethod where(**kwargs)

Returns a generator which yields instances matching the given query arguments.

For example, this would yield all Project:

Project.where()

And this would yield all launch approved Project:

Project.where(launch_approved=True)

panoptes_client.workflow module

class panoptes_client.workflow.Workflow(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject, panoptes_client.exportable.Exportable

add_alice_extractors(alice_task_key='T0', question_task_key='T1', question_extractor_if_missing='ignore', other_question_extractor_attrib=None, other_alice_extractor_attrib=None)

Adds ALICE Extractors (two extractors: Question and External).

• QuestionExtractor getting created will have a key of complete
• question_task_key - Task ID that reflects placement of: “Have all the volunteer-made underline marks turned grey?” step. Defaults to T1
• ExternalExtractor getting created will have a key of alice
• alice_task_key - Task ID that reflects placement of Transcription Task step (Defaults to T0)

Examples:

workflow.add_alice_extractors()

add_alice_reducers(alice_min_views=5, low_consensus_threshold=3)

Adds ALICE Reducers for given workflow (three reducers: External, Stats, Count).

• alice_min_views - This is the threshold number of classifications in order to “gray-out” a transcribed line. Default is 5.
• low_consensus_threshold - This is the threshold number of classifications in agreement for good consensus. Default is 3

add_alice_rules_and_effects(question_retirement_limit=3, count_retirement_limit=30)

Adds subject rules and corresponding effects for ALICE configuration of the given workflow. Two subject rules are created that will trigger retirement: a Question rule and a Count rule. A total of 4 subject rule effects should get created. There should be 2 effects related to the Question Rule condition (one to send to ALICE and the other to retire subject). There should also be 2 effects related to the Count Rule condition (one to send to alice and the other to retire subject)

• question_retirement_limit - Question subject rule created will trigger retirement when the answer to: “is this complete” question reaches this threshhold limit (defaults to 3)
• count_retirement_limit - Count Subject Rule created will trigger retirement when the classification count reaches this limit (defaults to 30)

add_caesar_extractor(extractor_type, extractor_key, task_key='T0', extractor_other_attributes=None)

Adds a Caesar extractor for given workflow. Will return extractor as a dict with ‘id’ if successful.

• extractor_type can be one of the following:

  ‘blank’, ‘external’, ‘question’, ‘survey’, ‘who’, ‘pluck_field’, or ‘shape’

• extractor_key is the unique key that you want to give to the extractor.

  The key will be used to track this specific reducer within Caesar.

Examples:

workflow.add_caesar_extractor('question', 'complete', 'T0', {'if_missing': ignore })

add_caesar_reducer(reducer_type, key, other_reducer_attributes=None)

Adds a Caesar reducer for given workflow. Will return reducer as dict with ‘id’ if successful.

• reducer_type can be one of the following:

  ‘consensus’, ‘count’, ‘placeholder’, ‘external’, ‘first_extract’, ‘stats’, ‘unique_count’, ‘rectangle’, ‘sqs’

• key is a unique name for your reducer. This key will be used to track this specific reducer within Caesar.

Examples:

workflow.add_caesar_reducer('count', 'count', {'filters' : {'extractor_keys': ['complete']}})

add_caesar_rule(condition_string, rule_type)

Adds a Caesar rule for given workflow. Will return rule as a dict with ‘id’ if successful.

• condition_string is a string that represents a single operation (sometimes nested).

  The general syntax is like if you’d write Lisp in json. It is a stringified array with the first item being a string identifying the operator. See https://zooniverse.github.io/caesar/#rules for examples of condition strings

• rule_type can either be ‘subject’ or ‘user’

Examples:

workflow.add_caesar_rule('["gte", ["lookup", "complete.0", 0], ["const", 3]]', 'subject')

add_caesar_rule_effect(rule_type, rule_id, action, effect_config=None)

Adds a Caesar effect for workflow and given the workflow rule with id rule_id. Method will return effect as a dict with ‘id’ if successful.

• rule_type can either be ‘subject’ or ‘user’
• rule_id is the id of the subject rule or user rule that the effect should run

• action can be one of the following:

  • (actions for subject rules) - ‘retire_subject’, ‘add_subject_to_set’, ‘add_to_collection’, ‘external’
  • (actions for user rules) - ‘promote_user’

Examples:

workflow.add_caesar_rule_effect('subject', subject_rule['id'], 'retire_subject',
                        {'reason': 'classification_count'})

add_subject_sets(subject_sets)

A wrapper around LinkCollection.add(). Equivalent to:

workflow.links.subject_sets.add(subject_sets)

caesar_effects(rule_type, rule_id)

Returns a list of Caesar workflow effects as dicts for the workflow rule with id rule_id.

• rule_type can either be ‘subject’ or ‘user’; if ‘subject’ will return effects of subject rules with id rule_id, if ‘user’ will return will return effects of user rules with id rule_id

Examples:

workflow.caesar_effects('subject', 123)
workflow.caesar_effects('user', 321)

caesar_extractors()

Returns a list of extractors as dicts from Caesar for particular workflow.

Examples:

workflow.caesar_extractors()

caesar_reducers()

Returns a list of reducers as dicts from Caesar for particular workflow.

Examples:

workflow.caesar_reducers()

caesar_rules(rule_type)

Returns a list of Caesar workflow rules as dicts.

• rule_type can either be ‘subject’ or ‘user’; if ‘subject’ will return subject rules, if ‘user’ will return user rules

Examples:

workflow.caesar_rules('subject')
workflow.caesar_rules('user')

caesar_subject_extracts(subject_id)

Returns a list of subject extracts as a dict from Caesar for a given subject.

Examples:

workflow.caesar_subject_extracts(1234)

s = Subject(1234)
workflow.caesar_subject_extracts(s.id)

caesar_subject_reductions(subject_id, reducer_key='')

Returns a list of subject reductions as dicts from Caesar for a given subject. Defaults to return all subject reductions for a given subject.

• reducer_key If given, will filter and return reductions for the reducer with that reducer_key.

Examples:

workflow.caesar_subject_reductions(1234)
workflow.caesar_subject_reductions(1234,'points')

configure_for_alice()

Configures workflow for ALICE/TOVE.

• This method will add workflow to Caesar
• This method will create Caesar Extractors needed for ALICE with defaults.
• This method will also create Caesar Reducers needed for ALICE with defaults. (In particular, minimum_views = 5, and low_consensus_threshold = 3)
• And this method will also create Caesar Subject Rules and Effects needed for ALICE with defaults. (In particular, Question-based retirement’s retirement limit is 3 and Count-based retirement default is 30.)

import_caesar_data_extracts(csv_source)

Imports machine-learnt data as extracts into Caesar.

• csv_source must be a publicly accessible csv at the time of import. Eg. csv can be hosted via an AWS S3 Bucket, Azure Blob Storage, or Panoptes media item. See this csv as an example. csv_source’s csv must have header/titles/rows of the following:
  • extractor_key (key corresponding to the extractor in Caesar)
  • subject_id
  • data (the machine learnt data for the corresponding subject)

Example:

workflow.import_caesar_data_extracts('https://panoptes-uploads-staging.zooniverse.org/project_attached_image/f1ab241f-2896-4efc-a1bc-3baaff64d783.csv')

remove_subject_sets(subject_sets)

A wrapper around LinkCollection.remove(). Equivalent to:

workflow.links.subject_sets.remove(subject_sets)

retire_subjects(subjects, reason='other')

Retires subjects in this workflow.

• subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.
• reason gives the reason the Subject has been retired. Defaults to other.

Examples:

workflow.retire_subjects(1234)
workflow.retire_subjects([1,2,3,4])
workflow.retire_subjects(Subject(1234))
workflow.retire_subjects([Subject(12), Subject(34)])

save()

Adds workflow configuration, retirement, and tasks dicts to the list of savable attributes if it has changed.

save_to_caesar(public_extracts=False, public_reductions=False)

Adds/updates selected Workflow to Caesar. Returns workflow as a dict from Caesar if created.

• public_extracts set to True to Enable Public Extracts, Defaults to False
• public_reductions set to True to Enable Public Reductions. Defaults to False

Examples:

workflow.save_to_caesar()
workflow.save_to_caesar(public_extracts=True, public_reductions=True)

set_raw(raw, etag=None, loaded=True)

subject_workflow_status(subject_id)

Returns SubjectWorkflowStatus of the current workflow given subject_id

Example:

workflow.subject_workflow_status(1234)

subject_workflow_statuses(subject_set_id)

A generator which yields SubjectWorkflowStatus objects for subjects in the subject set of the given workflow

Examples:

for status in workflow.subject_workflow_statuses(1234):
    print(status.retirement_reason)

unretire_subjects(subjects)

Un-retires subjects in this workflow by subjects.

• subjects can be a list of Subject instances, a list of subject IDs, a single Subject instance, or a single subject ID.

unretire_subjects_by_subject_set(subject_sets)

Un-retires subjects in this workflow by subject_sets.

• subjects_sets can be a list of SubjectSet instances, a list of subject_set IDs, a single SubjectSet instance, or a single subject_set ID.

versions

A generator which yields all WorkflowVersion instances for this workflow.

panoptes_client.workflow_version module

class panoptes_client.workflow_version.WorkflowVersion(raw={}, etag=None)

Bases: panoptes_client.panoptes.PanoptesObject

classmethod find(_id, workflow)

Like PanoptesObject.find() but also allows lookup by workflow.

• workflow must be a Workflow instance.

save()

Not implemented for this class. It is not possible to modify workflow versions once they are created.

workflow

The Workflow to which this version refers.

panoptes_client.caesar module

class panoptes_client.caesar.Caesar(endpoint='https://caesar.zooniverse.org', redirect_url='https://caesar.zooniverse.org/auth/zooniverse/callback')

Bases: object

The low-level Caesar HTTP client class. Use this class to interact with the Caesar API. User credentials are shared with Panoptes, so log in via Panoptes.connect() before use.

create_workflow_extractor(workflow_id, extractor_key, extractor_type, task_key='T0', other_extractor_attributes=None)

Adds a Caesar extractor for workflow with id workflow_id. Will return extractor as a dict with ‘id’ if success.

• extractor_type can be one of the following: ‘blank’, ‘external’, ‘question’, ‘survey’, ‘who’, ‘pluck_field’, or ‘shape’
• extractor_key is the unique key that you want to give to the extractor. The key will be used to track this specific reducer within Caesar.

Examples:

Caesar().create_workflow_extractor(12, 'question', 'complete', 'T0', {'if_missing': ignore })

create_workflow_reducer(workflow_id, reducer_type, key, other_reducer_attributes=None)

Adds a Caesar reducer for given workflow. Will return reducer as dict with ‘id’ if successful.

• reducer_type can be one of the following: ‘consensus’, ‘count’, ‘placeholder’, ‘external’, ‘first_extract’, ‘stats’, ‘unique_count’, ‘rectangle’, ‘sqs’
• key is a unique name for your reducer. This key will be used to track this specific reducer within Caesar.

Examples:

Caesar().create_workflow_reducer(1234, 'count', 'count', {'filters' : {'extractor_keys': ['complete']}})

create_workflow_rule(workflow_id, rule_type, condition_string='[]')

Adds a Caesar rule for given workflow. Will return rule as a dict with ‘id’ if successful.

• condition_string is a string that represents a single operation (sometimes nested). The general syntax is like if you’d write Lisp in json. It is a stringified array with the first item being a string identifying the operator. See for examples of condition strings https://zooniverse.github.io/caesar/#rules
• rule_type can either be ‘subject’ or ‘user’

Examples:

caesar = Caesar()
workflow = Workflow(1234)
caesar.create_workflow_rule(workflow.id, 'subject','["gte", ["lookup", "complete.0", 0], ["const", 3]]')

create_workflow_rule_effect(workflow_id, rule_type, rule_id, action, config=None)

Adds a Caesar effect for workflow with id workflow_id and rule with id rule_id. Method will return effect as a dict with ‘id’ if successful.

• rule_type can either be ‘subject’ or ‘user’
• rule_id is the id of the subject rule or user rule that the effect should run
• action can be one of the following: - (actions for subject rules) - ‘retire_subject’, ‘add_subject_to_set’, ‘add_to_collection’, ‘external’ - (actions for user rules) - ‘promote_user’

Examples:

retirement_config = {'reason': 'classification_count'}
Caesar().create_workflow_rule_effect(1, 'subject', subject_rule['id'], 'retire_subject', retirement_config)

get_extracts_by_workflow_and_subject(workflow_id, subject_id)

Returns a list of extracts as dicts from Caesar for workflow with provided workflow_id

get_reductions_by_workflow_and_subject(workflow_id, subject_id)

Returns a list of all subject reductions as dicts from Caesar given the ids of the workflow and subject.

get_workflow(workflow_id)

Returns workflow object if exists in Caesar

get_workflow_extractors(workflow_id)

Returns a list of extractors as dicts from Caesar for workflow with provided workflow_id

get_workflow_reducers(workflow_id)

Returns a list of reducers as dicts from Caesar for workflow with provided workflow_id

import_data_extracts(workflow_id, csv_source)

Imports machine-learnt data extracts into Caesar.

• csv_source must be a publicly accessible csv at the time of import. Eg. csv can be hosted via an AWS S3 Bucket, Azure Blob Storage, or Panoptes media item. See this csv as an example. csv_source’s csv must have header/titles/rows of the following:

  • extractor_key (key corresponding to the extractor in Caesar)
  • subject_id
  • data (the machine learnt data for the corresponding subject). This entry should be JSON.

  Example:

  caesar = Caesar(endpoint='https://caesar-staging.zooniverse.org')
  caesar.import_data_extracts(1234, 'https://panoptes-uploads-staging.zooniverse.org/project_attached_image/f1ab241f-2896-4efc-a1bc-3baaff64d783.csv')
  

save_workflow(workflow_id, public_extracts=False, public_reductions=False)

Adds/updates workflow with provided workflow_id to Caesar. Checks to see if workflow exists in Caesar, if not then creates workflow and returns workflow as a dict from Caesar if created. If workflow is already in Caesar, will update the Caesar workflow.

Examples:

Caesar().save_workflow(123, public_extracts=True, public_reductions=True)