An executable (applet or app) defines application logic that is to be run in the DNAnexus Platform’s Execution Environment. In order to facilitate parallel processing, an executable may define multiple functions (or entry points) that can invoke each other; a running job can use new_dxjob() to invoke any function defined in the same executable, creating a new job that runs that function on a different machine (possibly even launching multiple such jobs in parallel).
To create an executable from scratch, we encourage you to use the command-line tools dx-app-wizard and dx build rather than using the API or bindings directly. The following handlers for applets, apps, and jobs are most useful for running preexisting executables and monitoring their resulting jobs.
Workflows created from the website UI can also be run using the DXWorkflow workflow handler.
Applets are data objects that store application logic, including specifications for executing it, and (optionally) input and output signatures. They can be run by calling the DXApplet.run() method.
Methods in DXExecutable are used by DXApp, DXApplet, and DXWorkflow
| Parameters: |
|
|---|---|
| Returns: | Object handler of the newly created job |
| Return type: |
Creates a new job that executes the function “main” of this executable with the given input executable_input.
Bases: dxpy.bindings.DXDataObject, dxpy.bindings.dxapplet.DXExecutable
Remote applet object handler.
The applet’s run specification (a dict indicating, among other things, how the code of the applet is to be interpreted). See the API docs for Run Specification for more information.
String containing the version of the DNAnexus API that the applet should run against.
The applet’s access requirements hash (a dict indicating any nonstandard permissions, such as requiring access to the internet, that are needed by the applet). See the API docs for Access Requirements for more information.
String containing the (human-readable) title of the app
String containing a short, one-line summary of the applet’s purpose
String of free-form text (Markdown syntax is supported) containing a description of the applet. The description is presented to users to help them understand the purpose of the app and how to invoke it.
String of free-form text (Markdown syntax is supported) containing information about the internals or implementation details of the applet, suitable for developers or advanced users.
| Parameters: |
|
|---|
Note
It is highly recommended that the higher-level module dxpy.app_builder or (preferably) its frontend dx build be used instead for applet creation.
Creates an applet with the given parameters. See the API documentation for the /applet/new method for more info. The applet is not run until run() is called.
| Returns: | Full specification of the remote applet object |
|---|---|
| Return type: | dict |
Returns the contents of the applet. The result includes the key-value pairs as specified in the API documentation for the /applet-xxxx/get method.
Creates a new job that executes the function “main” of this applet with the given input applet_input.
See dxpy.bindings.dxapplet.DXExecutable.run() for the available args.
Apps allow for application logic to be distributed to users in the system, and they allow for analyses to be run in a reproducible and composable way.
Apps extend the functionality of applets to require input/output specifications as well as to allow for versioning, collaborative development, and policies for billing and data access. Similarly to applets, apps can be run by calling their run() method.
Unlike applets, apps are not data objects and do not live in projects. Instead, they share a single global namespace. An app may have multiple different versions (e.g. “1.0.0”, “1.0.1”, etc.) associated with a single name (which is of the form “app-APPNAME”). A particular version of an app may be identified in two ways, either by specifying a combination of its name and a version (or a tag), or by specifying its unique identifier.
Each app has a list of developers, which are the users that are authorized to publish new versions of an app; perform administrative tasks, such as assigning categories, and attaching new tags to versions of the app; and add or remove other developers. When the first version of an app with a given name is created, the creating user initially becomes the sole developer of the app.
Bases: dxpy.bindings.DXObject, dxpy.bindings.dxapplet.DXExecutable
Remote app object handler.
| Parameters: |
|
|---|---|
| Raises: | DXError if dxid and some other input are both given or if neither dxid nor name are given |
Discards the currently stored ID and associates the handler with the requested parameters. Note that if dxid is given, the other fields should not be given, and if name is given, alias has default value “default”.
| Returns: | Object ID of associated app |
|---|---|
| Return type: | string |
Returns the object ID of the app that the handler is currently associated with.
| Parameters: |
|
|---|
Note
It is highly recommended that the higher-level module dxpy.app_builder or (preferably) its frontend dx build –create-app be used instead for app creation.
Creates an app with the given parameters by using the specified applet or app as a base and overriding its attributes. See the API documentation for the /app/new method for more info.
Exactly one of initializeFrom and applet must be provided.
The app is only available to its developers until publish() is called, and is not run until run() is called.
| Parameters: | fields (dict) – Hash where the keys are field names that should be returned, and values should be set to True (default is that all fields are returned) |
|---|---|
| Returns: | Description of the remote app object |
| Return type: | dict |
Returns a dict with a description of the app. The result includes the key-value pairs as specified in the API documentation for the /app-xxxx/describe method.
| Parameters: |
|
|---|
Updates the parameters of an existing app. See the API documentation for the /app/update method for more info.
The current user must be a developer of the app.
| Parameters: | tags (array) – Tags to add to the app |
|---|
Adds the specified application name tags (aliases) to this app.
The current user must be a developer of the app.
Deprecated since version 0.72.0: Use add_tags() instead.
| Parameters: | tags (array) – Tags to remove from the app |
|---|
Removes the specified application name tags (aliases) from this app, so that it is no longer addressable by those aliases.
The current user must be a developer of the app.
Deprecated since version 0.72.0: Use remove_tags() instead.
| Returns: | Full specification of the remote app object |
|---|---|
| Return type: | dict |
Returns the contents of the app. The result includes the key-value pairs as specified in the API documentation for the /app-xxxx/get method.
Publishes the app, so all users can find it on the platform.
The current user must be a developer of the app.
Removes this app object from the platform.
The current user must be a developer of the app.
Creates a new job that executes the function “main” of this app with the given input app_input.
See dxpy.bindings.dxapplet.DXExecutable.run() for the available args.
For DXApp.run(), see run().
Workflows are data objects which contain metadata for a set of jobs to be run together. They can be run by calling the DXWorkflow.run() method.
| Parameters: |
|
|---|---|
| Return type: |
Additional optional parameters not listed: all those under dxpy.bindings.DXDataObject.new(), except details.
Creates a new remote workflow object with project set to project and returns the appropriate handler.
Example:
r = dxpy.new_dxworkflow(title=”My Workflow”, description=”This workflow contains...”)
Note that this function is shorthand for:
dxworkflow = DXWorkflow()
dxworkflow.new(**kwargs)
Bases: dxpy.bindings.DXDataObject, dxpy.bindings.dxapplet.DXExecutable
Remote workflow object handler. This class is used for the workflow class data objects which produce an analysis when run.
| Parameters: |
|
|---|---|
| Returns: | ID of the added stage |
| Return type: | string |
| Raises: | DXError if executable is not an expected type DXAPIError for errors thrown from the API call |
Adds the specified executable as a new stage in the workflow.
| Parameters: | stage (int or string) – A number for the stage index (for the nth stage, starting from 0), or a string of the stage index, name, or ID |
|---|---|
| Returns: | Hash of stage descriptor in workflow |
| Parameters: |
|
|---|---|
| Returns: | Stage ID that was removed |
| Return type: | string |
Removes the specified stage from the workflow
| Parameters: |
|
|---|
Removes the specified stage from the workflow
| Parameters: |
|
|---|
Make general metadata updates to the workflow
| Parameters: |
|
|---|
Removes the specified stage from the workflow
| Parameters: |
|
|---|---|
| Returns: | Object handler of the newly created analysis |
| Return type: |
Run the associated workflow. See dxpy.bindings.dxapplet.DXExecutable.run() for additional args.
When providing input for the workflow, keys should be of one of the following forms:
Jobs are DNAnexus entities that capture an instantiation of a running app or applet. They can be created from either dxpy.bindings.dxapplet.DXApplet.run() or dxpy.bindings.dxapp.DXApp.run() if running an applet or app, or via new_dxjob() or DXJob.new() in the case of an existing job creating a subjob.
| Parameters: |
|
|---|---|
| Return type: |
Creates and enqueues a new job that will execute a particular function (from the same app or applet as the one the current job is running). Returns the DXJob handle for the job.
Note that this function is shorthand for:
dxjob = DXJob()
dxjob.new(fn_input, fn_name, **kwargs)
Note
This method is intended for calls made from within already-executing jobs or apps. If it is called from outside of an Execution Environment, an exception will be thrown. To create new jobs from outside the Execution Environment, use dxpy.bindings.dxapplet.DXApplet.run() or dxpy.bindings.dxapp.DXApp.run().
Note
If the environment variable DX_JOB_ID is not set, this method assmes that it is running within the debug harness, executes the job in place, and provides a debug job handler object that does not have a corresponding remote API job object.
Bases: dxpy.bindings.DXObject
Remote job object handler.
| Parameters: |
|
|---|
Creates and enqueues a new job that will execute a particular function (from the same app or applet as the one the current job is running).
Note
This method is intended for calls made from within already-executing jobs or apps. If it is called from outside of an Execution Environment, an exception will be thrown. To create new jobs from outside the Execution Environment, use dxpy.bindings.dxapplet.DXApplet.run() or dxpy.bindings.dxapp.DXApp.run().
| Parameters: | dxid (string) – New job ID to be associated with the handler (localjob IDs also accepted for local runs) |
|---|
Discards the currently stored ID and associates the handler with dxid
| Parameters: |
|
|---|---|
| Returns: | Description of the job |
| Return type: | dict |
Returns a hash with key-value pairs containing information about the job, including its state and (optionally) its inputs and outputs, as described in the API documentation for the /job-xxxx/describe method.
| Parameters: | tags (list of strings) – Tags to add to the job |
|---|
Adds each of the specified tags to the job. Takes no action for tags that are already listed for the job.
| Parameters: | tags (list of strings) – Tags to remove from the job |
|---|
Removes each of the specified tags from the job. Takes no action for tags that the job does not currently have.
| Parameters: | properties (dict) – Property names and values given as key-value pairs of strings |
|---|
Given key-value pairs in properties for property names and values, the properties are set on the job for the given property names. Any property with a value of None indicates the property will be deleted.
Note
Any existing properties not mentioned in properties are not modified by this method.
| Parameters: |
|
|---|---|
| Raises: | DXError if the timeout is reached before the job has finished running, or dxpy.exceptions.DXJobFailureError if the job fails |
Waits until the job has finished running.
| Parameters: |
|
|---|
Returns a dict containing a valid job-based object reference to refer to an output of this job. This can be used directly in place of a DNAnexus link when used as a job output value. For example, after creating a subjob, the following app snippet uses a reference to the new job’s output as part of its own output:
mysubjob = dxpy.new_dxjob({}, "my_function")
return { "myfileoutput": mysubjob.get_output_ref("output_field_name"),
"myotherfileoutput": mysubjob.get_output_ref("output_array",
index=1),
"filename": mysubjob.get_output_ref("output_field_name",
metadata="name") }
Analyses are DNAnexus entities that capture an instantiation of a running workflow. They can be created from dxpy.bindings.dxworkflow.DXWorkflow.run() or from an existing analysis ID.
Bases: dxpy.bindings.DXObject
Remote analysis object handler.
| Parameters: | fields (dict) – dict where the keys are field names that should be returned, and values should be set to True (by default, all fields are returned) |
|---|---|
| Returns: | Description of the analysis |
| Return type: | dict |
Returns a hash with key-value pairs containing information about the analysis
| Parameters: | tags (list of strings) – Tags to add to the analysis |
|---|
Adds each of the specified tags to the analysis. Takes no action for tags that are already listed for the analysis.
| Parameters: | tags (list of strings) – Tags to remove from the analysis |
|---|
Removes each of the specified tags from the analysis. Takes no action for tags that the analysis does not currently have.
| Parameters: | properties (dict) – Property names and values given as key-value pairs of strings |
|---|
Given key-value pairs in properties for property names and values, the properties are set on the analysis for the given property names. Any property with a value of None indicates the property will be deleted.
Note
Any existing properties not mentioned in properties are not modified by this method.
| Parameters: |
|
|---|---|
| Raises: | DXError if the timeout is reached before the analysis has finished running, or DXJobFailureError if some job in the analysis has failed |
Waits until the analysis has finished running.
| Parameters: |
|
|---|
Returns a dict containing a valid reference to an output of this analysis.