API Reference

Workshop

class datarobot_bp_workshop.workshop.Workshop(auto_initialize=True, project_id=None, enforce_rate_limit=True, user_blueprint_id=None)

The Workshop for building and modifying blueprints.

BlueprintGraph(final_task, name=None)

Provides a mechanism to declare a set of tasks in the form of a directed acyclic graph.

Parameters
final_task: Task

The task to use as the final task in a blueprint, which will be inspected to find all inputs.

name: str

Specify a name to use for the blueprint

Parameters
Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

CustomTask(custom_task_id, output_method=None, task_parameters=None, output_method_parameters=None, x_transformations=None, y_transformations=None, freeze=False, version=None)

Create a custom task, using a custom_task_id, and optionally a version.

Parameters

  • custom_task_id (str) –

  • task_parameters (Optional[List[datarobot.models.user_blueprints.models.ParamValuePair]]) –

  • output_method_parameters (Optional[List[datarobot.models.user_blueprints.models.ParamValuePair]]) –

  • x_transformations (Optional[List[datarobot.models.user_blueprints.models.ParamValuePair]]) –

  • y_transformations (Optional[List[datarobot.models.user_blueprints.models.ParamValuePair]]) –

  • freeze (bool) –

  • version (Optional[str]) –

Return type

datarobot_bp_workshop.workshop.Workshop.Task

Feature(feature_name)

Selects a feature from the project data.

Ensure to call set_project or reinitialize the Workshop with a project_id, before attempting to select a feature.

Parameters
feature_name: str

The feature to select from the project data.

Parameters

feature_name (str) –

Return type

datarobot_bp_workshop.task.Feature

FeatureSelection(*feature_names, exclude=False)

Selects a number of features from the project data of a specific data type.

Ensure to call set_project or reinitialize the Workshop with a project_id, before attempting to select a feature.

Parameters
feature_names: *Union[str, ColnameAndType]

Include features which match the list provided.

exclude: bool

Whether to exclude the list of provided features, instead of include.

Parameters

feature_names (Union[str, datarobot.models.user_blueprints.models.ColnameAndType]) –

Return type

datarobot_bp_workshop.task.FeatureSelection

Task(task_code, output_method=None, task_parameters=None, output_method_parameters=None, x_transformations=None, y_transformations=None, freeze=False)

Provides a mechanism to specify how to transform or provide predictions for input data.

Parameters

  • task_code (str) –

  • output_method (Optional[str]) –

  • task_parameters (Optional[Union[List[datarobot.models.user_blueprints.models.ParamValuePair], dict]]) –

  • output_method_parameters (Optional[Union[List[datarobot.models.user_blueprints.models.ParamValuePair], dict]]) –

  • x_transformations (Optional[Union[List[datarobot.models.user_blueprints.models.ParamValuePair], dict]]) –

  • y_transformations (Optional[Union[List[datarobot.models.user_blueprints.models.ParamValuePair], dict]]) –

  • freeze (bool) –

Return type

datarobot_bp_workshop.task.Task

add_to_repository(project_id, user_blueprint_id)

Add a user blueprint to a project’s repository

Parameters
project_id: str

the id of the project

user_blueprint_id: str

the id of the user blueprint

Returns
str or None

blueprint_id if the user blueprint was successfully added to the repository. None otherwise.

Parameters

  • project_id (str) –

  • user_blueprint_id (str) –

Return type

Optional[str]

blueprint_from_user_blueprint(user_blueprint, creator=None, last_modifier_name=None)

Create a BlueprintGraph from a UserBlueprint object

Parameters
user_blueprint: UserBlueprint
creator: str, Optional

The full name of the creator of the user blueprint, if available.

last_modifier_name: str, Optional

The full name of the last modifier of the user blueprint, if available.

Returns
BlueprintGraph
Parameters

  • user_blueprint (datarobot.models.user_blueprints.models.UserBlueprint) –

  • creator (Optional[str]) –

  • last_modifier_name (Optional[str]) –

Return type

datarobot_bp_workshop.workshop.Workshop.BlueprintGraph

clone(blueprint_id, project_id=None, name=None)

Clone a blueprint from a project and save it as a user blueprint.

Parameters

  • blueprint_id (str) –

  • project_id (Optional[str]) –

  • name (Optional[str]) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

create_custom_task(environment_id, name, target_type, description=None)

Create a custom task, which can then be updated using code via %%update_custom or via the DataRobot API.

Parameters
environment_id: str

ID of the environment to use to create the model

name: str

The name of the custom task

target_type: str

One of: (“Anomaly”, “Binary”, “Multiclass”, “Regression”, “Transform”)

description: Optional[str]

An optional description of the model

Returns
CustomTask
Parameters

  • environment_id (str) –

  • name (str) –

  • target_type (str) –

  • description (Optional[str]) –

delete(*user_blueprint_ids)

Delete user blueprints using ids.

Parameters

user_blueprint_ids (str) –

deserialize_blueprint(bp_json)

Create a BlueprintGraph from a list of dictionaries representing a BlueprintGraph.

Parameters

bp_json (List[Dict]) –

Return type

datarobot_bp_workshop.workshop.Workshop.BlueprintGraph

deserialize_task(task_json, original_id=None)

Create a Task from a dictionary representing Task.

Parameters

  • task_json (Dict[str, Union[dict, str, List[str], List[Dict]]]) –

  • original_id (Optional[str]) –

Return type

datarobot_bp_workshop.workshop.Workshop.Task

get(user_blueprint_id, creator=None, last_modifier_name=None)

Retrieve a user blueprint using an id.

Parameters
user_blueprint_id: str

The id of the User Blueprint

creator: str, Optional

The full name of the creator of the user blueprint, if available.

last_modifier_name: str, Optional

The full name of the last modifier of the user blueprint, if available.

Parameters

  • user_blueprint_id (str) –

  • creator (Optional[str]) –

  • last_modifier_name (Optional[str]) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

get_custom_task(custom_task_id)

Retrieve a custom task.

Parameters

custom_task_id (str) –

initialize(user_blueprint_id=None, clean=False)

Initialize the tasks in the Workshop. Useful when creating custom tasks mid-session or turning on new feature flags.

Note: Creating a new, or replacing the current, instance of Workshop will achieve the same.

Parameters

  • user_blueprint_id (Optional[str]) –

  • clean (bool) –

Return type

datarobot_bp_workshop.workshop_interface.WorkshopInterface

Allows linking or unlinking of a user blueprint from a project. Especially useful for unlinking a blueprint from a project you no longer have access to.

When a user blueprint is linked to a project, it will be able to validate and otherwise use project specific tasks, such as feature selection.

If a user blueprint is linked to a project, it is expected that it will only be used with that project, or clones of that project.

If a user blueprint is not linked to a project, it is expected that it should be able to be project-agnostic, that is, used with any project which shares the same target type as the user blueprint.

Parameters
user_blueprint_id: str

Id of the User Blueprint

project_id: str or None

Id of the project to link to (or None). If None is passed, unlink the user blueprint from the project

Parameters

  • user_blueprint_id (str) –

  • project_id (Optional[str]) –

list(offset=0, limit=10, search=None)

Retrieve a list of your personal user blueprints.

Parameters

  • offset (int) –

  • limit (int) –

  • search (Optional[str]) –

Return type

List[datarobot_bp_workshop.blueprint_graph.BlueprintGraph]

list_categories(categories=None, show_tasks=False, color=True, margin='')

List the categories of tasks, and optionally the tasks themselves.

Parameters

  • categories (Optional[List[str]]) –

  • show_tasks (bool) –

  • color (bool) –

  • margin (str) –

Return type

datarobot_bp_workshop.utils.HiddenList

refresh()

Refresh the tasks in the Workshop. Useful when creating custom tasks mid-session or turning on new feature flags.

Note: this is functionally identical to initialize.

Return type

datarobot_bp_workshop.workshop_interface.WorkshopInterface

search_blueprints(search=None, tag=None, offset=0, limit=100, show=False, as_list=False)

Search for blueprints by keyword

Parameters

  • search (Optional[str]) –

  • tag (Optional[Union[str, List[str]]]) –

  • offset (int) –

  • limit (int) –

  • show (bool) –

  • as_list (bool) –

Return type

List[datarobot_bp_workshop.blueprint_graph.BlueprintGraph]

search_tasks(term, ignore_case=True, fuzzy=True)

Search for tasks which match a given term, optionally ignoring case (default) or performing a fuzzy search (default).

Parameters

  • term (str) –

  • ignore_case (bool) –

  • fuzzy (bool) –

Return type

datarobot_bp_workshop.utils.PrettyList

set_project(project_id=None)

Set the current context of the Workshop to be within a specific project.

This will provide the ability to select specific columns from a project.

Parameters

project_id (Optional[str]) –

Return type

datarobot_bp_workshop.workshop_interface.WorkshopInterface

Blueprint Graph

class datarobot_bp_workshop.blueprint_graph.BlueprintGraph(workshop, final_task_or_tasks, name=None)

Provides a mechanism to declare a set of tasks in the form of a directed acyclic graph.

Should not be used directly. Use Workshop.Blueprint instead.

Parameters
workshop: WorkshopInterface

Reference to the workshop

final_task_or_tasks: Task or list(task)
Either:

  • the task to use as the final task in a blueprint, which will be inspected to find all inputs.

  • the list of tasks to be used in the BlueprintGraph

name: str or None

The name to give the Blueprint Graph, which will be used to label the UserBlueprint if saved to DataRobot.

add_to_repository(project_id=None, validate_parameters=True)

Add a user blueprint to a project’s repository

Parameters
project_id: str or None - required if Workshop not set to project

the id of the project

Returns
str or None

blueprint_id if the user blueprint was successfully added to the repository. None otherwise.

validate_parameters: bool

Ensure all parameters are valid (recommended)

Raises
datarobot.errors.ClientError

if the server responded with 4xx status

datarobot.errors.ServerError

if the server responded with 5xx status

Parameters

  • project_id (Optional[str]) –

  • validate_parameters (bool) –

Return type

Optional[str]

as_graphviz_string(graph_name=None, vertical=False)

Used to render the graphviz form of the blueprint.

Parameters
graph_name: string

Name to display in the graph

vertical: bool

Whether to display the graph top to bottom, rather than left to right

Return type

str

delete(quiet=False)

Delete the blueprint from DataRobot

Parameters
quiet: bool, Default=False

If True, will not print a success message upon successful deletion.

Raises
ValueError
classmethod deserialize(workshop, bp_json)

Generate a BlueprintGraph from the JSON representation.

Parameters

  • workshop (datarobot_bp_workshop.workshop_interface.WorkshopInterface) –

  • bp_json (List[Dict]) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

classmethod from_user_blueprint(workshop, user_blueprint, creator=None, last_modifier_name=None)

Create a BlueprintGraph from a UserBlueprint instance.

Parameters

  • workshop (datarobot_bp_workshop.workshop_interface.WorkshopInterface) –

  • user_blueprint (datarobot.models.user_blueprints.models.UserBlueprint) –

  • creator (Optional[str]) –

  • last_modifier_name (Optional[str]) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

classmethod from_user_blueprint_tasks(workshop, user_blueprint_tasks, hex_column_name_lookup=None)

Generate a BlueprintGraph from a list of UserBlueprintTask

Parameters

  • workshop (datarobot_bp_workshop.workshop_interface.WorkshopInterface) –

  • user_blueprint_tasks (List[datarobot.models.user_blueprints.models.UserBlueprintTask]) –

  • hex_column_name_lookup (Optional[List[datarobot.models.user_blueprints.models.UserBlueprintHexColumnNameLookupEntry]]) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

Allows linking or unlinking of a user blueprint from a project.

When a user blueprint is linked to a project, it will be able to validate and otherwise use project specific tasks, such as feature selection.

If a user blueprint is linked to a project, it is expected that it will only be used with that project, or clones of that project.

If a user blueprint is not linked to a project, it is expected that it should be able to be project-agnostic, that is, used with any project which shares the same target type as the user blueprint.

Parameters
project_id: str or None

If None is passed, unlink the user blueprint from the project

user_blueprint_id: str or None

If None is passed, fallback to self.user_blueprint, if also None, raise ValueError

Raises
ValueError
Parameters

  • project_id (Optional[str]) –

  • user_blueprint_id (Optional[str]) –

save(name=None, user_blueprint_id=None, save_as_new=False, validate_parameters=True, color=True)

Save a BlueprintGraph as a User Blueprint in DataRobot.

Returns
BlueprintGraph
Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

serialize(minify=True)

” Used to view Blueprint in the familiar blueprint dictionary format.

Returns
list(dict)

A list of dictionaries representing the tasks in the blueprint.

Return type

List[Dict]

share(usernames, role='CONSUMER')

Share a User Blueprint with a user or list of other users by username.

Parameters

  • usernames (Union[str, List[str]]) –

  • role (str) –

share_with_group(group_ids, role='CONSUMER')

Share a User Blueprint with a group or list of groups by id.

Parameters

  • group_ids (Union[str, List[str]]) –

  • role (str) –

share_with_org(org_ids, role='CONSUMER')

Share a User Blueprint with a group or list of organizations by id.

Parameters

  • org_ids (Union[str, List[str]]) –

  • role (str) –

show(vertical=False, as_image=True)

IPython specific drawing functionality.

Wraps as_image.

Parameters
vertical: bool (Default=False)

Whether to display the graph top to bottom, rather than left to right

as_image: bool (Default=True)

If enabled, will render as a PNG, otherwise will rely on IPython to display the Source directly. Rendering as a PNG is preferred as it will auto-resize to the size of the rendering space provided, while Source will overflow.

Return type

Optional[IPython.core.display.DisplayHandle]

to_source_code(to_stdout=False, blueprint_ref=None, workshop_ref=None, pretty_repr=True)

Convenience method for developers to help understand how to use the API.

Construct the Blueprint using deserialize, and output the source code which can be used to create it using this new functional method.

Parameters
to_stdout: bool (Default=False)

Whether the source code of the blueprint should be printed to stdout.

blueprint_ref: str (Default=None)

A variable to store the new BlueprintGraph instead of generating one

workshop_ref: str (Default=None)

A variable to use to refer to an existing instance of Workshop instead of creating a new one.

pretty_repr: bool (Default=True)

Whether to pretty-print the result of execution. Useful for easy copy-paste in a notebook environment. Note: Does not change the content / actual value of what is returned, just how it is displayed (i.e. repr method).

Returns
str

Executable source code to construct itself, in a functional manner. Useful as a tutorial, or large refactors.

Parameters

  • to_stdout (bool) –

  • blueprint_ref (Optional[str]) –

  • workshop_ref (Optional[str]) –

  • pretty_repr (bool) –

Return type

str

train(project_id=None, validate_parameters=True, *args, **kwargs)

Train it.

See datarobot.Project.train or datarobot.Project.train_datetime for parameters.

Parameters
project_id: str or None - required if Workshop not set to project

the id of the project to train the blueprint on

validate_parameters: bool

Ensure all parameters are valid (recommended)

Returns
BlueprintGraph

Returns self

Parameters

  • project_id (Optional[str]) –

  • validate_parameters (bool) –

Return type

datarobot_bp_workshop.blueprint_graph.BlueprintGraph

Task

class datarobot_bp_workshop.task.Task(workshop, task_code, output_method=None, task_parameters=None, output_method_parameters=None, x_transformations=None, y_transformations=None, freeze=False, original_id=None, custom_task_id=None, version=None, hex_column_name_lookup=None)

Provides a mechanism to specify how to transform or provide predictions for input data.

Should not be used directly. Use one of: Workshop.Task, Workshop.Tasks.*, Workshop.CustomTask, or Workshop.CustomTasks.* instead.

Parameters
workshop: WorkshopInterface

Reference to the workshop

task_code: string

Task Code

output_method: string

starting with member of TaskMethodShort and an optional set of arguments

task_parameters: TaskParameters

A class with allowed params as attributes.

output_method_parameters: List[ParamValuePair]

A list of parameters and values to the operation e.g. [ParamValuePair(param=’add_orig_colname’, value=True)]

x_transformations: List[ParamValuePair]

A list of ParamValuePair representing transformations to be applied to the input data, X.

y_transformations: List[ParamValuePair]

A list of ParamValuePair representing transformations to be applied to the input targets, Y.

freeze: boolean

Whether or not to freeze the vertex - i.e. hexes, model strings, and inputs are cached.

original_id: str

An id to associate with this task which will be used when serializing the task.

custom_task_id: str

An id representing the custom task content- only applicable if the task is “Custom”

version: str or None

An id representing the custom task version content- only applicable if the task is “Custom”

property description

The description of the task.

classmethod deserialize(workshop, task_dict, original_id=None)

Take in a dictionary specifying how the task should be constructed, and construct an instance of the Task.

Parameters

  • workshop (datarobot_bp_workshop.workshop_interface.WorkshopInterface) –

  • task_dict (Dict[str, Union[dict, str, List[str], List[Dict]]]) –

  • original_id (Optional[str]) –

Return type

datarobot_bp_workshop.task.Task

documentation(auto_open=False)

Return a link to the documentation of the task. Optionally automatically open it in a browser window.

Return type

str

classmethod from_user_blueprint_task(workshop, task_data, original_id=None, hex_column_name_lookup=None)

Instantiate a Task using UserBlueprintTaskData from a UserBlueprint.

Parameters

  • workshop (datarobot_bp_workshop.workshop_interface.WorkshopInterface) –

  • task_data (datarobot.models.user_blueprints.models.UserBlueprintTaskData) –

  • original_id (Optional[str]) –

  • hex_column_name_lookup (Optional[List[datarobot.models.user_blueprints.models.UserBlueprintHexColumnNameLookupEntry]]) –

Return type

datarobot_bp_workshop.task.Task

get_task_parameter_by_name(name)

Retrieve the value of a task parameter by it’s human-readable name.

Parameters

name (str) –

Return type

Optional[Any]

property input_names

Ordered representation of the input ids (things like ‘NUM’, ‘1’, or <hex>)

property inputs

A list of the inputs to the task.

property is_estimator

Whether or not the task can be used for prediction (stacked or otherwise).

property label

Build the human-friendly label to describe the task.

property original_or_task_id

If the task has an id associated with it manually, via original_id, return this id, otherwise return the generated self.task_id.

property output_method

The output method of the task.

property selected_features

If specific features are selected, return them.

serialize(map_ids=None, minify=True)

Convert the instance of the Task into the serialized form of a dictionary.

Parameters
Return type

Dict[str, Union[dict, str, List[str], List[Dict]]]

property task_code

The unique code representing the class. E.g. “ABC”.

property task_code_or_custom_task_code

Return the identifier of the task, either the task_code or the custom task id.

property task_id

Produces a hex which will be identical for two Task with the same inputs, task string, and task type.

property using_default_output_method

Return whether the task is using its default output method.

validate_task_parameters(color=True, only_output_errors=False, to_stdout=True)

Perform task validation to ensure all parameters and their values are valid.

Return type

List[datarobot.models.user_blueprints.models.UserBlueprintsValidateTaskParameter]

property versions

For Custom Tasks Only: The possible versions for a given task.

Visualize

class datarobot_bp_workshop.visualize.Visualize

Provides visualization functionality.

classmethod as_graphviz(graphviz_string, catch_exception=True)

Used to render the graph form of the blueprint using matplotlib.

Parameters

graphviz_string (str) –

Return type

graphviz.files.Source

classmethod as_image(graphviz_string, catch_exception=True)

Used to render the graph as an image.

Simply wrap in IPython.display.Image to display in a notebook, or write it to disk.

Parameters

graphviz_string (str) –

Return type

Optional[bytes]

classmethod format_nodes_to_draw(nodes_to_draw, node_to_task_lookup=None, vertex_context_lookup=None)

Given nodes to use to generate a GraphViz DiGraph string, format them such that they are styled as expected to look familiar to the DataRobot UI.

Return type

Dict[str, str]

classmethod handle_validation(node_to_draw, task_id=None, vertex_context_lookup=None)

Add validation to the components to be used to make a graphviz string.

Return type

None

classmethod show(graphviz_string, as_image=True)

Visualize a GraphViz string.

IPython specific drawing functionality.

Wraps as_image.

Parameters
graphviz_string: string

The GraphViz string to render

as_image: bool (Default=True)

If enabled, will render as a PNG, otherwise will rely on IPython to display the Source directly. Rendering as a PNG is preferred as it will auto-resize to the size of the rendering space provided, while Source will overflow.

Parameters

  • graphviz_string (str) –

  • as_image (bool) –

Return type

Union[IPython.core.display.DisplayHandle, None, graphviz.files.Source]

classmethod show_dr_blueprint(dr_blueprint)

Visualize a DataRobot Blueprint object.

Parameters

dr_blueprint (datarobot.models.blueprint.Blueprint) –

Return type

Optional[IPython.core.display.DisplayHandle]

classmethod simple_to_graphviz(nodes, edges, graph_name=None, vertical=False)

Get blueprint chart in graphviz DOT format.

Returns
unicode

String representation of chart in graphviz DOT language.

Return type

str

classmethod to_graphviz_string(nodes, edges, graph_name=None, node_to_task_lookup=None, vertex_context_lookup=None, vertical=False)

Generate a GraphViz DiGraph string from nodes and edges.

Return type

str