{"__v":10,"_id":"5570b1829ea7860d008b272f","category":{"__v":10,"_id":"5477c47ef3736008009e9eb7","pages":["5477c4dbf3736008009e9eb9","5477c545f3736008009e9ebc","54d36f225616470d0013ccf9","54d372fa69578e0d0027311f","54d3e371514a230d0018195a","54d410f79873ad0d00b3793b","54d42ca39873ad0d00b37950","54e9099bf152c50d009b49b5","552c27bb7820b80d00aa4ede","5570b1829ea7860d008b272f"],"project":"5476bf0f817e8d080031f988","version":"5476bf10817e8d080031f98b","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-28T00:40:30.938Z","from_sync":false,"order":5,"slug":"packages","title":"Packages"},"parentDoc":null,"project":"5476bf0f817e8d080031f988","user":"54c096f492501c0d000b38a7","version":{"__v":17,"_id":"5476bf10817e8d080031f98b","project":"5476bf0f817e8d080031f988","createdAt":"2014-11-27T06:05:04.263Z","releaseDate":"2014-11-27T06:05:04.263Z","categories":["5476bf10817e8d080031f98c","5477c46cf3736008009e9eb5","5477c474f3736008009e9eb6","5477c47ef3736008009e9eb7","5477c48ff3736008009e9eb8","5477c4948deb230800808bf0","54e68328154f8e0d0007b55c","54e90194c8e0c00d007ac061","54eed2275bf74a0d00ef4076","54f7a7be0a3cbb0d00d666fb","559b0ebf7ae7f80d0096d871","55d697f9ae529e0d00d34f03","562d4dcc8c6e5a0d00d6ed1d","562e591c4376430d006f17e0","568f0e73bdb9260d00149d8c","5719542aac1e2e0e001834c6","57a14a8ed778850e0047e230"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-06-04T20:13:54.300Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Perhaps you want to tweak an existing protocol, build off other protocols, or create something entirely new. Whatever the reason, it's time to learn how to create a package for yourself. This guide will walk you through the process of writing a protocol to run on Transcriptic, from start to finish.\n\n### Autoprotocol\nFirst off, you'll need to understand a little about [Autoprotocol](http://www.autoprotocol.org). Autoprotocol instructions are the basic building blocks of protocols at Transcriptic. Autoprotocol is a specification for a JSON-formatted, biologically precise description of actions to be taken to perform a protocol.  Please read the spec at [autoprotocol.org](http://autoprotocol.org/specification/) to see what different instructions look like expressed as Autoprotocol. For this guide, it isn't necessary to know all the details, but you'll definitely want to refer to the Autoprotocol specification while writing your protocol.  \n\nThere are no decisions made in the course of executing a run. The instructions will be executed from start to finish, as quickly as possible, and it is up to you to submit another run, if further action is desired.\n\n### Generating Autoprotocol\nA protocol isn't always the exact same set of steps. Depending on the inputs, you may want to pipette different volumes, or heat at a different temperature. To respond to these varying conditions, we encode the decision making process in a programming language (in this case, Python). Your script will take in a set of parameters, and convert them into explicit, precise actions to be taken.\n\nYou'll also want to refer to the [About Autoprotocol and Related Tools](doc:autoprotocol) section of this documentation, but we'll do a brief overview here.  \n\n### To the code!\nWithout further ado, let's jump into the code. We're going to build a simple protocol that transfers an amount of dye you specify to a corresponding well you specify. We'll use the **[autoprotocol-python](https://github.com/autoprotocol/autoprotocol-python)** library for convenience.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"from autoprotocol.unit import Unit\\n\\ndef sample_protocol(protocol, params):\\n    dest_plate = params[\\\"destination_plate\\\"]\\n    wells_to_measure = []\\n\\n    for location in params[\\\"dye_locations\\\"]:\\n        protocol.transfer(params[\\\"dye\\\"],\\n                          dest_plate.well(location[\\\"well_index\\\"]),\\n                          location[\\\"volume\\\"])\\n        if location[\\\"volume\\\"] != Unit(100, \\\"microliter\\\"):\\n            protocol.transfer(params[\\\"water\\\"],\\n                              dest_plate.well(location[\\\"well_index\\\"]),\\n                              Unit(100,\\\"microliter\\\") - location[\\\"volume\\\"],\\n                              mix_after = True)\\n        wells_to_measure.append(location[\\\"well_index\\\"])\\n\\n    protocol.absorbance(dest_plate, wells_to_measure, \\\"475:nanometer\\\", \\\"test\\\")\\n\\n\\nif __name__ == '__main__':\\n    from autoprotocol.harness import run\\n    run(sample_protocol, \\\"SampleProtocol\\\")\\n\",\n      \"language\": \"python\",\n      \"name\": \"sample_protocol.py\"\n    }\n  ]\n}\n[/block]\nThis file defines a function, `sample_protocol()`, which takes two arguments. The first, `protocol`, is an instance of the [Protocol](http://autoprotocol-python.readthedocs.org/en/latest/autoprotocol.html#module-autoprotocol.protocol) class. It starts empty, and it's the job of the `sample_protocol` function to add instructions and refs to it.\n\nThe second argument, `params`, is a dictionary containing all of the parameters used within the protocol, entered by the user. The form of those inputs, as well as other metadata about the protocol, is defined in the `manifest.json` file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"format\\\": \\\"python\\\",\\n  \\\"license\\\": \\\"MIT\\\",\\n  \\\"protocols\\\": [\\n    {\\n      \\\"name\\\": \\\"SampleProtocol\\\",\\n      \\\"version\\\": \\\"1.0.0\\\",\\n      \\\"description\\\": \\\"Measure absorbance of various dilutions of OrangeG dye.\\\",\\n      \\\"command_string\\\": \\\"python sample_protocol.py\\\",\\n      \\\"inputs\\\": {\\n          \\\"dye\\\": \\\"aliquot\\\",\\n          \\\"water\\\": \\\"aliquot\\\",\\n          \\\"destination_plate\\\": \\\"container\\\",\\n          \\\"dye_locations\\\":{\\n            \\\"type\\\": \\\"group+\\\",\\n            \\\"description\\\": \\\"Each group represents a volume of dye to be placed in the specified well\\\",\\n            \\\"inputs\\\": {\\n              \\\"volume\\\": {\\n                \\\"type\\\": \\\"volume\\\",\\n                \\\"description\\\": \\\"Enter a volume up to 100 microliters\\\"\\n              },\\n              \\\"well_index\\\": {\\n                \\\"type\\\": \\\"string\\\",\\n                \\\"description\\\": \\\"Enter a numerical well index (between 0 and 95)\\\"\\n            }\\n          }\\n        }\\n      },\\n      \\\"preview\\\": {/* see code snippet below */}\\n    }\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"name\": \"manifest.json\"\n    }\n  ]\n}\n[/block]\nThe manifest defines metadata that is package-wide (the `\"format\"` and `\"license\"` fields), as well as a list of protocols contained in the package and metadata about each protocol.  Read more about the manifest file [here](doc:the-manifest).\n\nThe `\"inputs\"` dictionary in a `protocol`'s metadata defines what data a user must supply through the UI before executing the protocol. Each key in the dictionary is the name of an input, and the value is the type of input. See [Input types](doc:input-types) for details of the various input types available.  Each input is turned into its respective field type in the UI. \n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/G8LgYRaTBGBeIih3fCCw_Transcriptic.png\",\n        \"Transcriptic.png\",\n        \"946\",\n        \"520\",\n        \"#6a9edc\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThe `\"preview\"` section (omitted in the above example and optional in general) contains an example input set from which the `transcriptic preview` command will generate a preview of your protocol formatted in autoprotocol on the command-line. This should be representative of the expected input. We'll use this as our preview input set:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"preview\\\": {\\n   \\\"refs\\\": {\\n     \\\"OrangeG\\\":{\\n       \\\"type\\\": \\\"micro-1.5\\\",\\n       \\\"store\\\": \\\"cold_4\\\"\\n     },\\n     \\\"Water\\\": {\\n       \\\"type\\\": \\\"micro-1.5\\\",\\n       \\\"store\\\": \\\"cold_4\\\"\\n     },\\n     \\\"Test plate\\\": {\\n       \\\"type\\\": \\\"96-flat\\\",\\n       \\\"discard\\\": true\\n     }\\n   },\\n   \\\"parameters\\\":{\\n     \\\"dye\\\": \\\"OrangeG/0\\\",\\n     \\\"water\\\": \\\"Water/0\\\",\\n     \\\"destination_plate\\\": \\\"Test plate\\\",\\n     \\\"dye_locations\\\": [\\n       {\\\"volume\\\": \\\"10:microliter\\\", \\\"well_index\\\": 0},\\n       {\\\"volume\\\": \\\"20:microliter\\\", \\\"well_index\\\": 1},\\n       {\\\"volume\\\": \\\"30:microliter\\\", \\\"well_index\\\": 2},\\n       {\\\"volume\\\": \\\"40:microliter\\\", \\\"well_index\\\": 3},\\n       {\\\"volume\\\": \\\"100:microliter\\\", \\\"well_index\\\": 4}\\n     ]\\n   }\\n }\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nThe last thing we need before we can run this protocol is a `requirements.txt` file to import the autoprotocol-python library.  You can specify either the latest release, or if your script uses unreleased changes to the library, you can specify the latest commit's SHA from the repo:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# requirements.txt using the latest autoprotocol release \\nautoprotocol==2.0.5\",\n      \"language\": \"text\",\n      \"name\": \"requirements.txt\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# requirements.txt using a specific commit from a git repo\\n-e git://github.com/autoprotocol/autoprotocol-python.git:::at:::<commit SHA>#egg=autoprotocol\\n\",\n      \"language\": \"text\",\n      \"name\": \"requirements.txt\"\n    }\n  ]\n}\n[/block]\nTo try it out before we upload it, save the `manifest.json`, `requirements.txt` and `sample_protocol.py` files to a directory called `sample_protocol.py`. Install and login to the [transcriptic runner](https://github.com/transcriptic/runner) if you haven't already, then open your terminal and run:\n\n```\n$ pip install -r requirements.txt\n$ transcriptic preview SampleProtocol\n# ... autoprotocol! ...\n```\nThis will give you the autoprotocol output of your script using the parameters in the \"preview\" section of your `manifest.json` file (if applicable).\n\n## Packaging and uploading\nThe last step is to package all files into a `release.zip` file and upload it to Transcriptic.\n\n Zip up your `requirements.txt`, `manifest.json` and `sample_protocol.py` files from the command line:\n```\n$ zip release.zip requirements.txt manifest.json sample_protocol.py\n```\nor compress them as in the video below:\n[block:html]\n{\n  \"html\": \"<div>\\n  <video style=\\\"max-width: 100%\\\" controls>\\n    <source src=\\\"//static.transcriptic.com/screencasts/zip_archive.webm\\\" type=\\\"video/webm; codecs=vp8\\\">\\n    <source src=\\\"//static.transcriptic.com/screencasts/zip_archive.mp4\\\" type=\\\"video/mp4; codecs=avc1.64001f\\\">\\n  </video>\\n</div>\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"body\": \"`requirements.txt`, `manifest.json` and any code you're including in your package must exist at the top level of a zip, do NOT zip or compress a folder\"\n}\n[/block]\nNavigate to where it says your organization's name in the upper right corner, then click on \"Manage.\"  On the next screen click on the \"Packages\" tab and then click \"Create A New Package.\"  Enter a name and description for your package and upload your zipped archive. Finally, click on \"publish\" next to your release to make it available for all members of your organization. \n\nIf you have updated or added a script as part of a package, you may upload a new release by clicking the \"upload new\" button in the upper right corner of the screen when viewing a package.   Ensure that the \"version\" number for each protocol your `manifest.json` file is at least one patch version larger than any previous uploads.\n\nCongratulations! You just created your first package!\n\nClicking the \"Launch a Run\" button from any project will bring up the Protocol Browser, and protocols you've uploaded yourself will appear under the \"Organization\" link\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/Ci9rSPsRsmfgCUaDca8C_Transcriptic.png\",\n        \"Transcriptic.png\",\n        \"1154\",\n        \"607\",\n        \"#b48564\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"package-creation-quickstart","type":"basic","title":"Package Creation Quickstart"}

Package Creation Quickstart


Perhaps you want to tweak an existing protocol, build off other protocols, or create something entirely new. Whatever the reason, it's time to learn how to create a package for yourself. This guide will walk you through the process of writing a protocol to run on Transcriptic, from start to finish. ### Autoprotocol First off, you'll need to understand a little about [Autoprotocol](http://www.autoprotocol.org). Autoprotocol instructions are the basic building blocks of protocols at Transcriptic. Autoprotocol is a specification for a JSON-formatted, biologically precise description of actions to be taken to perform a protocol. Please read the spec at [autoprotocol.org](http://autoprotocol.org/specification/) to see what different instructions look like expressed as Autoprotocol. For this guide, it isn't necessary to know all the details, but you'll definitely want to refer to the Autoprotocol specification while writing your protocol. There are no decisions made in the course of executing a run. The instructions will be executed from start to finish, as quickly as possible, and it is up to you to submit another run, if further action is desired. ### Generating Autoprotocol A protocol isn't always the exact same set of steps. Depending on the inputs, you may want to pipette different volumes, or heat at a different temperature. To respond to these varying conditions, we encode the decision making process in a programming language (in this case, Python). Your script will take in a set of parameters, and convert them into explicit, precise actions to be taken. You'll also want to refer to the [About Autoprotocol and Related Tools](doc:autoprotocol) section of this documentation, but we'll do a brief overview here. ### To the code! Without further ado, let's jump into the code. We're going to build a simple protocol that transfers an amount of dye you specify to a corresponding well you specify. We'll use the **[autoprotocol-python](https://github.com/autoprotocol/autoprotocol-python)** library for convenience. [block:code] { "codes": [ { "code": "from autoprotocol.unit import Unit\n\ndef sample_protocol(protocol, params):\n dest_plate = params[\"destination_plate\"]\n wells_to_measure = []\n\n for location in params[\"dye_locations\"]:\n protocol.transfer(params[\"dye\"],\n dest_plate.well(location[\"well_index\"]),\n location[\"volume\"])\n if location[\"volume\"] != Unit(100, \"microliter\"):\n protocol.transfer(params[\"water\"],\n dest_plate.well(location[\"well_index\"]),\n Unit(100,\"microliter\") - location[\"volume\"],\n mix_after = True)\n wells_to_measure.append(location[\"well_index\"])\n\n protocol.absorbance(dest_plate, wells_to_measure, \"475:nanometer\", \"test\")\n\n\nif __name__ == '__main__':\n from autoprotocol.harness import run\n run(sample_protocol, \"SampleProtocol\")\n", "language": "python", "name": "sample_protocol.py" } ] } [/block] This file defines a function, `sample_protocol()`, which takes two arguments. The first, `protocol`, is an instance of the [Protocol](http://autoprotocol-python.readthedocs.org/en/latest/autoprotocol.html#module-autoprotocol.protocol) class. It starts empty, and it's the job of the `sample_protocol` function to add instructions and refs to it. The second argument, `params`, is a dictionary containing all of the parameters used within the protocol, entered by the user. The form of those inputs, as well as other metadata about the protocol, is defined in the `manifest.json` file: [block:code] { "codes": [ { "code": "{\n \"format\": \"python\",\n \"license\": \"MIT\",\n \"protocols\": [\n {\n \"name\": \"SampleProtocol\",\n \"version\": \"1.0.0\",\n \"description\": \"Measure absorbance of various dilutions of OrangeG dye.\",\n \"command_string\": \"python sample_protocol.py\",\n \"inputs\": {\n \"dye\": \"aliquot\",\n \"water\": \"aliquot\",\n \"destination_plate\": \"container\",\n \"dye_locations\":{\n \"type\": \"group+\",\n \"description\": \"Each group represents a volume of dye to be placed in the specified well\",\n \"inputs\": {\n \"volume\": {\n \"type\": \"volume\",\n \"description\": \"Enter a volume up to 100 microliters\"\n },\n \"well_index\": {\n \"type\": \"string\",\n \"description\": \"Enter a numerical well index (between 0 and 95)\"\n }\n }\n }\n },\n \"preview\": {/* see code snippet below */}\n }\n ]\n}", "language": "json", "name": "manifest.json" } ] } [/block] The manifest defines metadata that is package-wide (the `"format"` and `"license"` fields), as well as a list of protocols contained in the package and metadata about each protocol. Read more about the manifest file [here](doc:the-manifest). The `"inputs"` dictionary in a `protocol`'s metadata defines what data a user must supply through the UI before executing the protocol. Each key in the dictionary is the name of an input, and the value is the type of input. See [Input types](doc:input-types) for details of the various input types available. Each input is turned into its respective field type in the UI. [block:image] { "images": [ { "image": [ "https://files.readme.io/G8LgYRaTBGBeIih3fCCw_Transcriptic.png", "Transcriptic.png", "946", "520", "#6a9edc", "" ] } ] } [/block] The `"preview"` section (omitted in the above example and optional in general) contains an example input set from which the `transcriptic preview` command will generate a preview of your protocol formatted in autoprotocol on the command-line. This should be representative of the expected input. We'll use this as our preview input set: [block:code] { "codes": [ { "code": "\"preview\": {\n \"refs\": {\n \"OrangeG\":{\n \"type\": \"micro-1.5\",\n \"store\": \"cold_4\"\n },\n \"Water\": {\n \"type\": \"micro-1.5\",\n \"store\": \"cold_4\"\n },\n \"Test plate\": {\n \"type\": \"96-flat\",\n \"discard\": true\n }\n },\n \"parameters\":{\n \"dye\": \"OrangeG/0\",\n \"water\": \"Water/0\",\n \"destination_plate\": \"Test plate\",\n \"dye_locations\": [\n {\"volume\": \"10:microliter\", \"well_index\": 0},\n {\"volume\": \"20:microliter\", \"well_index\": 1},\n {\"volume\": \"30:microliter\", \"well_index\": 2},\n {\"volume\": \"40:microliter\", \"well_index\": 3},\n {\"volume\": \"100:microliter\", \"well_index\": 4}\n ]\n }\n }", "language": "json", "name": null } ] } [/block] The last thing we need before we can run this protocol is a `requirements.txt` file to import the autoprotocol-python library. You can specify either the latest release, or if your script uses unreleased changes to the library, you can specify the latest commit's SHA from the repo: [block:code] { "codes": [ { "code": "# requirements.txt using the latest autoprotocol release \nautoprotocol==2.0.5", "language": "text", "name": "requirements.txt" } ] } [/block] [block:code] { "codes": [ { "code": "# requirements.txt using a specific commit from a git repo\n-e git://github.com/autoprotocol/autoprotocol-python.git@<commit SHA>#egg=autoprotocol\n", "language": "text", "name": "requirements.txt" } ] } [/block] To try it out before we upload it, save the `manifest.json`, `requirements.txt` and `sample_protocol.py` files to a directory called `sample_protocol.py`. Install and login to the [transcriptic runner](https://github.com/transcriptic/runner) if you haven't already, then open your terminal and run: ``` $ pip install -r requirements.txt $ transcriptic preview SampleProtocol # ... autoprotocol! ... ``` This will give you the autoprotocol output of your script using the parameters in the "preview" section of your `manifest.json` file (if applicable). ## Packaging and uploading The last step is to package all files into a `release.zip` file and upload it to Transcriptic. Zip up your `requirements.txt`, `manifest.json` and `sample_protocol.py` files from the command line: ``` $ zip release.zip requirements.txt manifest.json sample_protocol.py ``` or compress them as in the video below: [block:html] { "html": "<div>\n <video style=\"max-width: 100%\" controls>\n <source src=\"//static.transcriptic.com/screencasts/zip_archive.webm\" type=\"video/webm; codecs=vp8\">\n <source src=\"//static.transcriptic.com/screencasts/zip_archive.mp4\" type=\"video/mp4; codecs=avc1.64001f\">\n </video>\n</div>" } [/block] [block:callout] { "type": "danger", "body": "`requirements.txt`, `manifest.json` and any code you're including in your package must exist at the top level of a zip, do NOT zip or compress a folder" } [/block] Navigate to where it says your organization's name in the upper right corner, then click on "Manage." On the next screen click on the "Packages" tab and then click "Create A New Package." Enter a name and description for your package and upload your zipped archive. Finally, click on "publish" next to your release to make it available for all members of your organization. If you have updated or added a script as part of a package, you may upload a new release by clicking the "upload new" button in the upper right corner of the screen when viewing a package. Ensure that the "version" number for each protocol your `manifest.json` file is at least one patch version larger than any previous uploads. Congratulations! You just created your first package! Clicking the "Launch a Run" button from any project will bring up the Protocol Browser, and protocols you've uploaded yourself will appear under the "Organization" link [block:image] { "images": [ { "image": [ "https://files.readme.io/Ci9rSPsRsmfgCUaDca8C_Transcriptic.png", "Transcriptic.png", "1154", "607", "#b48564", "" ] } ] } [/block]