{"__v":2,"_id":"56e36cf4f7d7a71700234792","category":{"__v":8,"_id":"54e68328154f8e0d0007b55c","pages":["54e68e63a43fe13500db387a","54e68e98bdcbdc21000d55e6","54e6ca051415460d009fc118","54ecf59b172d6b2b003b3178","54ecf790172d6b2b003b317a","54eec2f35bf74a0d00ef4063","56d10611376b040b005b3135","56e36cf4f7d7a71700234792"],"project":"5476bf0f817e8d080031f988","version":"5476bf10817e8d080031f98b","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-02-20T00:43:20.640Z","from_sync":false,"order":3,"slug":"design-rules-limitations","title":"Developing on Transcriptic"},"parentDoc":null,"project":"5476bf0f817e8d080031f988","user":"568ed50cbeb2700d00471802","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":"2016-03-12T01:12:20.120Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Today we are going to instruct a completely automated robotic cloud lab to grab a genetically modified strain of bacteria from a library of common reagents, inoculate some bacterial growth media and finally watch how that culture grows over 8 hours by seeing how the bacteria scatter 600nm light.\n\nLet's get started.\n\nAfter you sign up for a [Transcriptic](https://transcriptic.com) account you need to install some dependencies, we'll be working with Python today so `pip` is your friend.\n\nFirst let's install the [Transcriptic CLI tool](https://github.com/transcriptic/transcriptic).\n\n```bash\npip install transcriptic\n```\n\nNext we'll be writing Autoprotocol the open standard for experimental specification so we need a [tool](https://github.com/autoprotocol/autoprotocol-python) to help us do that.\n\n```bash\npip install autoprotocol\n```\n\nOK we're all set.\n\nLet's run the Transcriptic CLI.\n\n```\n> transcriptic\n\nUsage: transcriptic [OPTIONS] COMMAND [ARGS]...\n\n  A command line tool for working with Transcriptic.\n\nOptions:\n  --apiroot TEXT\n  --config TEXT            Specify a configuration file.\n  -o, --organization TEXT\n  --help                   Show this message and exit.\n\nCommands:\n  analyze         Analyze a block of Autoprotocol JSON.\n  build-release   Compress the contents of the current...\n  compile         Compile a protocol by passing it a config...\n  create-package  Create a new empty protocol package\n  create-project  Create a new empty project.\n  delete-package  Delete an existing protocol package\n  delete-project  Delete an existing project.\n  format          Check Autoprotocol format of manifest.json.\n  init            Initialize a directory with a manifest.json...\n  login           Authenticate to your Transcriptic account.\n  packages        List packages in your organization.\n  preview         Preview the Autoprotocol output of protocol...\n  projects        List the projects in your organization\n  protocols       List protocols within your manifest.\n  resources       Search catalog of provisionable resources\n  submit          Submit your run to the project specified.\n  summarize       Summarize Autoprotocol as a list of plain...\n  upload-release  Upload a release archive to a package.\n```\n\nFirst we need to login to our Transcriptic account and specify our organization.\n\n```\n> transcriptic login\n\nEmail: example:::at:::example.com\nPassword:\nYou belong to 3 organizations:\n  Sanger Lab (sanger-lab)\n  Franklin Lab (franklin_lab)\n  Swift on Pharma (swiftpharma)\nWhich would you like to login as [sanger-lab]? swiftpharma\nLogged in as example@example.com (swiftpharma)\n```\n\nGreat we're logged in, now we can start writing our protocols. Let's create a file to contain our commands to produce the Autoprotocol description of a growth curve. You could also do this interactively in a Python REPL.\n\n```bash\n> touch growth_protocol.py\n> atom growth_protocol.py\n```\n**Note: in the above example I am using the text editor [Atom](https://atom.io), but please feel free to use your text editor of choice and use the appropriate command.**\n\nFirst we'll add the import statements, [autoprotocol](https://github.com/autoprotocol/autoprotocol-python) is needed to provide the functions to generate Autoprotocol JSON. And the JSON package is required for some utility methods to handle parsing JSON.\n\n```py\n\"\"\"\ngrowth_protocol.py\n\nThis script produces autoprotocol to execute a growth curve on Transcriptic\n\"\"\"\nfrom autoprotocol import *\nimport json\n\n```\n\nNext let's instantiate a protocol object that all of our instructions are attached to.\n\n```py\np = Protocol()\n```\n\nNow we are going to begin defining the references. References describe containers used in the protocol such as plates and tubes. We are just going to describe 2 containers 1 for the bacteria and one for the plate that will be used in the plate reader to follow along the growth.\n\nA reference takes 5 arguments, `name`, `id`, `cont_type`, `storage` and `discard`. `id` is required if referencing a container that already exists, if instantiating a new container an id will automatically be assigned by Transcriptic upon run submission. `cont_type` is the type of container, below we are specifying a flat bottomed 96 well plate and a 1.5 mL microcentrifuge tube. `storage` is the temperature at which you require the sample to be stored when not directly in use. Below the plat will be stored at 4C whenever it is not being used, the tube however will be discarded at the end of the run as `discard` is set to `True`.\n\n```py\ngrowth_plate = p.ref(\"growth_plate\", id=None, cont_type=\"96-flat\", storage=\"cold_4\", discard=None)\n\nbacteria = p.ref(\"bacteria_tube\", id=None, cont_type=\"micro-1.5\", storage=None, discard=True)\n```\n\nNow that we have defined our containers we now want to fill them up. First of all we want to get some _E. coli_ from the Transcriptic common reagent library. This can be done with the `provision` instruction and the `resource_id` for the material we need. Resource IDs can be found in the [catalogue](https://secure.transcriptic.com/_commercial/kits).\n\n```py\n\ndh5a = \"rs16pbj944fnny\"\np.provision(dh5a, bacteria.well(0), \"15:microliter\")\n```\n\nNow let's fill the first column of that empty 96 well plate with some growth media. LB-broth should do the job nicely. The code below will `dispense` 175µL of LB-broth into each well in the first column.\n\n```py\np.dispense(growth_plate, \"lb-broth-noAB\", [{\"column\": 0, \"volume\": \"175:microliter\"}])\n```\n\nNow let's innoculate 4 of the 8 wells with _E .coli_ using `transfer`.\n\n```py\ntest_wells = growth_plate.wells_from(0, 4, columnwise = True)\nfor dest in test_wells:\n  p.transfer(bacteria.well(0), dest, \"2:microliter\")\n```\n\nIn a interactive python session you can see what the `test_wells` `WellGroup` looks like. Note that wells are 0 indexed and increment row wise.\n\n```py\n>>> test_wells\nWellGroup([\n  Well(Container(growth_plate), 0, None),\n  Well(Container(growth_plate), 12, None),\n  Well(Container(growth_plate), 24, None),\n  Well(Container(growth_plate), 36, None)\n  ])\n```\n\nThat's the innoculation taken care of no let's create a loop that will `incubate` the culture for 30 minutes then take an `absorbance` measurement at 600nm.\n\n```py\n# Set total growth time of growth curve\ntotal_growth_time = Unit(8, \"hour\")\n# Set the number of OD600 measurements taken over the time course.\nnumber_of_measurements = 16\n\nfor i in xrange(0, number_of_measurements):\n  p.cover(growth_plate) # put a lid on the plate\n  p.incubate(growth_plate, \"warm_37\", duration=total_growth_time/number_of_measurements, shaking=True, co2=0)\n  p.uncover(growth_plate) # take lid off of plate\n  p.absorbance(growth_plate, measurement_wells, wavelength=\"600:nanometer\", dataref=\"od600_%s\" % i)\n```\n\nNow with all of these in a single python file we need to get some JSON that can be sent to the Transcriptic API.\n\nFor this we can use:\n\n```py\n# Dump the Autoprotocol JSON.\nmy_experiment = json.dumps(p.as_dict(), indent=2)\nprint(my_experiment)\n```\n\nNow from the command line we can run the python file which will print the JSON object to `stdout`. The `stdout` can be piped to the Transcriptic CLI.\n\nLet's see how much this protocol run will cost with `transcriptic analyze`\n\n```\npython growth_protocol.py | transcriptic analyze\n✓ Protocol analyzed\n  67 instructions\n  2 containers\n  Total Cost: $25.59\n  Workcell Time: $18.25\n  Reagents & Consumables: $7.34\n```\n\nLet's find the project we want to submit to:\n\n```\ntranscriptic projects\n\n                                   PROJECTS:\n\n              PROJECT NAME              |               PROJECT ID\n--------------------------------------------------------------------------------\nPCR                                     |             p18qua34567db\n--------------------------------------------------------------------------------\nDirected Evolution                      |             p18qrn9745vfz\n--------------------------------------------------------------------------------\nI'll come up with a name later          |             p18s63543jm9t3\n--------------------------------------------------------------------------------\nBad Blood... work up                    |             p18qupn345v99\n--------------------------------------------------------------------------------\nRed... Fluorescent protein cloning      |             p18qrjd345u89\n--------------------------------------------------------------------------------\n```\n\n```\npython growth_protocol.py | transcriptic submit -p p18qrjd345u89\n\nRun created: https://secure.transcriptic.com/swiftpharma/p18qrjd345u89/runs/r18sc542345\n```\n\nAnd that is the run submitted and the robots will execute it.\n\nAfter the run completes the data can be downloaded from the web app as a CSV or via the API. I will cover data analysis in another post.\n\nIf you have any questions head to the [forum](https://forum.transcriptic.com) and for further reading check out the rest of the Transcriptic support site at [developers.transcriptic.com](https://developers.transcriptic.com)","excerpt":"","slug":"guide-programming-transcriptic-for-the-first-time","type":"basic","title":"Guide: programming Transcriptic for the first time"}

Guide: programming Transcriptic for the first time


Today we are going to instruct a completely automated robotic cloud lab to grab a genetically modified strain of bacteria from a library of common reagents, inoculate some bacterial growth media and finally watch how that culture grows over 8 hours by seeing how the bacteria scatter 600nm light. Let's get started. After you sign up for a [Transcriptic](https://transcriptic.com) account you need to install some dependencies, we'll be working with Python today so `pip` is your friend. First let's install the [Transcriptic CLI tool](https://github.com/transcriptic/transcriptic). ```bash pip install transcriptic ``` Next we'll be writing Autoprotocol the open standard for experimental specification so we need a [tool](https://github.com/autoprotocol/autoprotocol-python) to help us do that. ```bash pip install autoprotocol ``` OK we're all set. Let's run the Transcriptic CLI. ``` > transcriptic Usage: transcriptic [OPTIONS] COMMAND [ARGS]... A command line tool for working with Transcriptic. Options: --apiroot TEXT --config TEXT Specify a configuration file. -o, --organization TEXT --help Show this message and exit. Commands: analyze Analyze a block of Autoprotocol JSON. build-release Compress the contents of the current... compile Compile a protocol by passing it a config... create-package Create a new empty protocol package create-project Create a new empty project. delete-package Delete an existing protocol package delete-project Delete an existing project. format Check Autoprotocol format of manifest.json. init Initialize a directory with a manifest.json... login Authenticate to your Transcriptic account. packages List packages in your organization. preview Preview the Autoprotocol output of protocol... projects List the projects in your organization protocols List protocols within your manifest. resources Search catalog of provisionable resources submit Submit your run to the project specified. summarize Summarize Autoprotocol as a list of plain... upload-release Upload a release archive to a package. ``` First we need to login to our Transcriptic account and specify our organization. ``` > transcriptic login Email: example@example.com Password: You belong to 3 organizations: Sanger Lab (sanger-lab) Franklin Lab (franklin_lab) Swift on Pharma (swiftpharma) Which would you like to login as [sanger-lab]? swiftpharma Logged in as example@example.com (swiftpharma) ``` Great we're logged in, now we can start writing our protocols. Let's create a file to contain our commands to produce the Autoprotocol description of a growth curve. You could also do this interactively in a Python REPL. ```bash > touch growth_protocol.py > atom growth_protocol.py ``` **Note: in the above example I am using the text editor [Atom](https://atom.io), but please feel free to use your text editor of choice and use the appropriate command.** First we'll add the import statements, [autoprotocol](https://github.com/autoprotocol/autoprotocol-python) is needed to provide the functions to generate Autoprotocol JSON. And the JSON package is required for some utility methods to handle parsing JSON. ```py """ growth_protocol.py This script produces autoprotocol to execute a growth curve on Transcriptic """ from autoprotocol import * import json ``` Next let's instantiate a protocol object that all of our instructions are attached to. ```py p = Protocol() ``` Now we are going to begin defining the references. References describe containers used in the protocol such as plates and tubes. We are just going to describe 2 containers 1 for the bacteria and one for the plate that will be used in the plate reader to follow along the growth. A reference takes 5 arguments, `name`, `id`, `cont_type`, `storage` and `discard`. `id` is required if referencing a container that already exists, if instantiating a new container an id will automatically be assigned by Transcriptic upon run submission. `cont_type` is the type of container, below we are specifying a flat bottomed 96 well plate and a 1.5 mL microcentrifuge tube. `storage` is the temperature at which you require the sample to be stored when not directly in use. Below the plat will be stored at 4C whenever it is not being used, the tube however will be discarded at the end of the run as `discard` is set to `True`. ```py growth_plate = p.ref("growth_plate", id=None, cont_type="96-flat", storage="cold_4", discard=None) bacteria = p.ref("bacteria_tube", id=None, cont_type="micro-1.5", storage=None, discard=True) ``` Now that we have defined our containers we now want to fill them up. First of all we want to get some _E. coli_ from the Transcriptic common reagent library. This can be done with the `provision` instruction and the `resource_id` for the material we need. Resource IDs can be found in the [catalogue](https://secure.transcriptic.com/_commercial/kits). ```py dh5a = "rs16pbj944fnny" p.provision(dh5a, bacteria.well(0), "15:microliter") ``` Now let's fill the first column of that empty 96 well plate with some growth media. LB-broth should do the job nicely. The code below will `dispense` 175µL of LB-broth into each well in the first column. ```py p.dispense(growth_plate, "lb-broth-noAB", [{"column": 0, "volume": "175:microliter"}]) ``` Now let's innoculate 4 of the 8 wells with _E .coli_ using `transfer`. ```py test_wells = growth_plate.wells_from(0, 4, columnwise = True) for dest in test_wells: p.transfer(bacteria.well(0), dest, "2:microliter") ``` In a interactive python session you can see what the `test_wells` `WellGroup` looks like. Note that wells are 0 indexed and increment row wise. ```py >>> test_wells WellGroup([ Well(Container(growth_plate), 0, None), Well(Container(growth_plate), 12, None), Well(Container(growth_plate), 24, None), Well(Container(growth_plate), 36, None) ]) ``` That's the innoculation taken care of no let's create a loop that will `incubate` the culture for 30 minutes then take an `absorbance` measurement at 600nm. ```py # Set total growth time of growth curve total_growth_time = Unit(8, "hour") # Set the number of OD600 measurements taken over the time course. number_of_measurements = 16 for i in xrange(0, number_of_measurements): p.cover(growth_plate) # put a lid on the plate p.incubate(growth_plate, "warm_37", duration=total_growth_time/number_of_measurements, shaking=True, co2=0) p.uncover(growth_plate) # take lid off of plate p.absorbance(growth_plate, measurement_wells, wavelength="600:nanometer", dataref="od600_%s" % i) ``` Now with all of these in a single python file we need to get some JSON that can be sent to the Transcriptic API. For this we can use: ```py # Dump the Autoprotocol JSON. my_experiment = json.dumps(p.as_dict(), indent=2) print(my_experiment) ``` Now from the command line we can run the python file which will print the JSON object to `stdout`. The `stdout` can be piped to the Transcriptic CLI. Let's see how much this protocol run will cost with `transcriptic analyze` ``` python growth_protocol.py | transcriptic analyze ✓ Protocol analyzed 67 instructions 2 containers Total Cost: $25.59 Workcell Time: $18.25 Reagents & Consumables: $7.34 ``` Let's find the project we want to submit to: ``` transcriptic projects PROJECTS: PROJECT NAME | PROJECT ID -------------------------------------------------------------------------------- PCR | p18qua34567db -------------------------------------------------------------------------------- Directed Evolution | p18qrn9745vfz -------------------------------------------------------------------------------- I'll come up with a name later | p18s63543jm9t3 -------------------------------------------------------------------------------- Bad Blood... work up | p18qupn345v99 -------------------------------------------------------------------------------- Red... Fluorescent protein cloning | p18qrjd345u89 -------------------------------------------------------------------------------- ``` ``` python growth_protocol.py | transcriptic submit -p p18qrjd345u89 Run created: https://secure.transcriptic.com/swiftpharma/p18qrjd345u89/runs/r18sc542345 ``` And that is the run submitted and the robots will execute it. After the run completes the data can be downloaded from the web app as a CSV or via the API. I will cover data analysis in another post. If you have any questions head to the [forum](https://forum.transcriptic.com) and for further reading check out the rest of the Transcriptic support site at [developers.transcriptic.com](https://developers.transcriptic.com)