{ "cells": [ { "cell_type": "markdown", "id": "assign-intro", "metadata": {}, "source": [ "# Assigning child resources\n", "\n", "Resources form a tree (see the {doc}`introduction`). You build the tree by assigning a child\n", "resource to a parent resource. This page shows the `assign_child_*` methods:\n", "\n", "- {meth}`~pylabrobot.resources.Resource.assign_child_resource` puts a child at a location that you\n", " give.\n", "- {meth}`~pylabrobot.resources.Resource.assign_child_by_anchor` computes the location from two\n", " anchor points, one on the parent and one on the child.\n", "- Some resources, such as resource holders, carriers and decks, compute the location for you." ] }, { "cell_type": "markdown", "id": "at-location", "metadata": {}, "source": [ "## At a location: `assign_child_resource`\n", "\n", "The location of a child is relative to the left front bottom corner of its parent. The x-axis goes\n", "from left to right, the y-axis from front to back, and the z-axis from bottom to top." ] }, { "cell_type": "code", "execution_count": null, "id": "at-location-code", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.resources import Coordinate, Resource\n", "\n", "parent = Resource(name=\"parent\", size_x=100, size_y=80, size_z=10)\n", "child = Resource(name=\"child\", size_x=20, size_y=10, size_z=5)\n", "\n", "parent.assign_child_resource(child, location=Coordinate(x=10, y=20, z=0))\n", "\n", "assert child.parent is parent\n", "assert child.location == Coordinate(x=10, y=20, z=0)" ] }, { "cell_type": "markdown", "id": "absolute", "metadata": {}, "source": [ "{meth}`~pylabrobot.resources.Resource.get_absolute_location` gives the location relative to the root\n", "of the tree. When you put the parent in a larger tree, the child goes with it:" ] }, { "cell_type": "code", "execution_count": null, "id": "absolute-code", "metadata": {}, "outputs": [], "source": [ "root = Resource(name=\"root\", size_x=500, size_y=300, size_z=0)\n", "root.assign_child_resource(parent, location=Coordinate(x=100, y=50, z=0))\n", "\n", "assert child.get_absolute_location() == Coordinate(x=110, y=70, z=0)" ] }, { "cell_type": "markdown", "id": "names", "metadata": {}, "source": [ "A name identifies a resource in its tree, so two resources in one tree cannot have the same name:" ] }, { "cell_type": "code", "execution_count": null, "id": "names-code", "metadata": {}, "outputs": [], "source": [ "duplicate = Resource(name=\"child\", size_x=5, size_y=5, size_z=5)\n", "\n", "try:\n", " parent.assign_child_resource(duplicate, location=Coordinate(x=0, y=0, z=0))\n", "except ValueError as error:\n", " print(error) # Resource with name 'child' already exists in the tree.\n", "else:\n", " raise AssertionError(\"expected a ValueError\")" ] }, { "cell_type": "markdown", "id": "unassign", "metadata": {}, "source": [ "{meth}`~pylabrobot.resources.Resource.unassign_child_resource` removes a child from its parent. The\n", "child then has no parent and no location:" ] }, { "cell_type": "code", "execution_count": null, "id": "unassign-code", "metadata": {}, "outputs": [], "source": [ "parent.unassign_child_resource(child)\n", "\n", "assert child.parent is None\n", "assert child.location is None" ] }, { "cell_type": "markdown", "id": "by-anchor", "metadata": {}, "source": [ "## By anchor points: `assign_child_by_anchor`\n", "\n", "An anchor is a point on a resource, given by one letter per axis:\n", "\n", "- x: `\"l\"` (left), `\"c\"` (center) or `\"r\"` (right);\n", "- y: `\"f\"` (front), `\"c\"` (center) or `\"b\"` (back);\n", "- z: `\"b\"` (bottom), `\"c\"` (center) or `\"t\"` (top).\n", "\n", "`get_anchor` and the tuple form also take the full words, such as `\"left\"`.\n", "{meth}`~pylabrobot.resources.Resource.get_anchor` gives the location of an anchor, relative to the\n", "left front bottom corner of the resource:" ] }, { "cell_type": "code", "execution_count": null, "id": "get-anchor-code", "metadata": {}, "outputs": [], "source": [ "assert parent.get_anchor(x=\"c\", y=\"c\", z=\"t\") == Coordinate(x=50, y=40, z=10)" ] }, { "cell_type": "markdown", "id": "by-anchor-explain", "metadata": {}, "source": [ "`assign_child_by_anchor` puts the child so that its `child_anchor` is at the `parent_anchor` of the\n", "parent. Then it calls `assign_child_resource` with that location. Both anchors are left front\n", "bottom (`\"lfb\"`) by default, which gives the location `(0, 0, 0)`.\n", "\n", "Each of the next cells unassigns the child at its end, so that the next cell can assign it again.\n", "\n", "To center the child on the parent, align the center of the bottom of both:" ] }, { "cell_type": "code", "execution_count": null, "id": "center-code", "metadata": {}, "outputs": [], "source": [ "parent.assign_child_by_anchor(child, parent_anchor=\"ccb\", child_anchor=\"ccb\")\n", "\n", "# (100 - 20) / 2 = 40 and (80 - 10) / 2 = 35\n", "assert child.location == Coordinate(x=40, y=35, z=0)\n", "parent.unassign_child_resource(child)" ] }, { "cell_type": "markdown", "id": "on-top", "metadata": {}, "source": [ "To put the child on top of the parent, align the top of the parent with the bottom of the child.\n", "The anchors can also be tuples:" ] }, { "cell_type": "code", "execution_count": null, "id": "on-top-code", "metadata": {}, "outputs": [], "source": [ "parent.assign_child_by_anchor(child, parent_anchor=(\"c\", \"c\", \"t\"), child_anchor=(\"c\", \"c\", \"b\"))\n", "assert child.location == Coordinate(x=40, y=35, z=10)\n", "parent.unassign_child_resource(child)\n", "\n", "# In the right back corner, on top\n", "parent.assign_child_by_anchor(child, parent_anchor=\"rbt\", child_anchor=\"rbb\")\n", "assert child.location == Coordinate(x=80, y=70, z=10)\n", "parent.unassign_child_resource(child)" ] }, { "cell_type": "markdown", "id": "subclasses", "metadata": {}, "source": [ "## Resources that compute the location\n", "\n", "Some resources know where their children go. For these, you do not give a location.\n", "\n", "A {class}`~pylabrobot.resources.ResourceHolder` puts its child at its `child_location`:" ] }, { "cell_type": "code", "execution_count": null, "id": "holder-code", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.resources import ResourceHolder, cor_96_wellplate_360uL_Fb\n", "\n", "holder = ResourceHolder(\n", " name=\"holder\", size_x=127.76, size_y=85.48, size_z=0, child_location=Coordinate(x=0, y=0, z=2)\n", ")\n", "plate = cor_96_wellplate_360uL_Fb(name=\"plate\")\n", "holder.assign_child_resource(plate)\n", "\n", "assert holder.resource is plate\n", "assert plate.location == Coordinate(x=0, y=0, z=2)" ] }, { "cell_type": "markdown", "id": "carrier", "metadata": {}, "source": [ "A {class}`~pylabrobot.resources.Carrier` has sites, and each site is a resource holder. Index the\n", "carrier to assign a resource to a site:" ] }, { "cell_type": "code", "execution_count": null, "id": "carrier-code", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.resources import hamilton_plate_carrier_L5_ac\n", "\n", "plate_carrier = hamilton_plate_carrier_L5_ac(name=\"plate_carrier\")\n", "plate_carrier[0] = cor_96_wellplate_360uL_Fb(name=\"plate_on_carrier\")\n", "\n", "assert plate_carrier[0].resource.name == \"plate_on_carrier\"\n", "assert plate_carrier[0].resource.parent is plate_carrier.sites[0]" ] }, { "cell_type": "markdown", "id": "decks", "metadata": {}, "source": [ "Decks have their own ways to place resources. A Hamilton deck takes a `track` and computes the\n", "location of the carrier from it:" ] }, { "cell_type": "code", "execution_count": null, "id": "hamilton-deck-code", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.resources import STARLetDeck\n", "\n", "star_deck = STARLetDeck()\n", "star_deck.assign_child_resource(plate_carrier, track=1)\n", "\n", "assert plate_carrier.parent is star_deck" ] }, { "cell_type": "markdown", "id": "ot-deck", "metadata": {}, "source": [ "An Opentrons deck has a resource holder for each slot. Use\n", "{meth}`~pylabrobot.resources.opentrons.deck.OTDeck.assign_child_at_slot` to put labware in a slot:" ] }, { "cell_type": "code", "execution_count": null, "id": "ot-deck-code", "metadata": {}, "outputs": [], "source": [ "from pylabrobot.resources import OTDeck\n", "\n", "ot_deck = OTDeck()\n", "ot_deck.assign_child_at_slot(cor_96_wellplate_360uL_Fb(name=\"plate_in_slot_1\"), 1)\n", "\n", "assert ot_deck.get_resource(\"plate_in_slot_1\").parent.name == \"ot2_deck_slot_1\"" ] }, { "cell_type": "markdown", "id": "api", "metadata": {}, "source": [ "See {class}`~pylabrobot.resources.Resource` for the API reference." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "name": "python" } }, "nbformat": 4, "nbformat_minor": 5 }