PLR Plate Quadrant Definition Standardization (#410)

Co-authored-by: Rick Wierenga <[email protected]>

Author: BioCam

.gitignore

@@ -10,4 +10,5 @@ pyhamilton/LAY-BACKUP
 *.log
 build/lib
 
-myenv
+myenv
+env/*

docs/conf.py

@@ -84,6 +84,7 @@
 html_extra_path = ["resources/library/img"]
 
 html_theme_options = {
+  "show_nav_level": 4,
   "use_edit_page_button": True,
   "navbar_start": ["navbar-logo"],
   "navbar_center": ["navbar-nav"],

docs/resources/carrier/carrier.rst

@@ -0,0 +1,26 @@
+Carrier
+================
+
+A **carrier** is a component of the deck layout that holds labware such as plates, tip racks, tubes, or troughs/reservoirs. Carriers serve as modular, standardized platforms that allow for flexible deck configurations, ensuring that labware is positioned accurately.
+
+Each carrier type is optimized for specific resource types (like plates, tip racks, etc.), allowing for efficient sample handling and workflow customization.
+The :class:`~pylabrobot.resources.carrier.Carrier` class provides a base structure from which specialized carrier types inherit, ensuring modularity and flexibility in system configurations.
+
+-----
+
+Subclasses of `Carrier`
+-----------------------
+
+.. toctree::
+   :maxdepth: 4
+
+   plate-carrier/plate_carriers
+   mfx-carrier/mfx_carriers
+
+-----
+
+Carrier Types
+-------------
+
+- **Plate Carriers**: These carriers hold standard microplates and deep-well plates, ensuring proper alignment for automated pipetting and handling.
+- **MFX Carriers**: A specific type of carrier designed for flexible reconfiguration of that carrier layout by removably screwing "MFX Modules" onto the MFX Carrier of choice.

docs/resources/mfx.ipynb docs/resources/carrier/mfx-carrier/mfx_carriers.ipynb

@@ -1,64 +1,95 @@
 # Resource Library
 
-The PLR Resource Library (PLR-RL) is the world's biggest and most accurate centralized collection of labware. If you cannot find something, please contribute what you are looking for!
+The PyLabRobot Resource Library (PLR-RL) is PyLabRobot's open-source, crowd-sourced collection of labware.
+Laboratories across the world use an almost infinite number of different resources/labware.
+We believe the way to most efficient capture the largest portion of this resource superset is via crowd-sourcing, and peer-reviewing new entries.
+If you cannot find something, please contribute what you are looking for!
+
+----
 
 ```{toctree}
 :maxdepth: 1
 
 introduction
 custom-resources
+plr-rl-naming-conventions
 ```
 
+----
+
 ## `Resource` subclasses
 
 In PLR every physical object is a subclass of the `Resource` superclass (except for `Tip`).
 Each subclass adds unique methods or attributes to represent its unique physical specifications and behavior.
 
-Some standard `Resource` subclasses in the inheritance tree are:
-
-```
-Resource
-├── Carrier
-│   ├── TipCarrier
-│   ├── PlateCarrier
-│   ├── MFXCarrier
-│   ├── ShakerCarrier
-│   └── TubeCarrier
-├── Container
-│   ├── Well
-│   ├── PetriDish
-│   ├── Tube
-│   └── Trough
-├── ItemizedResource
-│   ├── Plate
-│   ├── TipRack
-│   └── TubeRack
-├── Lid
-└── PlateAdapter
-```
-
-See more detailed documentatino below (WIP).
+PLR's `Resource` subclasses in the inheritance tree are:
+<style>
+  .tree {
+    border: 3px solid black;      /* Thick border around the entire table */
+    border-collapse: collapse;    /* Ensures borders don’t double */
+    background-color: #FAF3DD;    /* Light background */
+    margin-left: 5px;             /* A bit of left margin */
+  }
+
+  .tree td {
+    font-family: "Fira Code", monospace;  /* Code-like font */
+    font-size: 15px;                     /* Matches code cell output */
+    font-weight: bold;                   /* Make all text bold */
+    line-height: 1.2;                    /* Slightly tighten vertical spacing */
+    padding: 0 10px;                   /* Padding around each line */
+    border: none;                        /* Remove inner borders */
+    white-space: pre;                    /* Preserve spacing exactly */
+  }
+</style>
+
+<table class="tree">
+  <tr><td><a href="introduction.html">Resource</a></td></tr>
+
+  <!-- Carrier subtree -->
+  <tr><td>├── <a href="carrier/carrier.html">Carrier</a></td></tr>
+  <tr><td>│   ├── <a href="carrier/plate-carrier/plate_carriers.html">PlateCarrier</a></td></tr>
+  <tr><td>│   ├── TipCarrier</td></tr>
+  <tr><td>│   ├── <a href="carrier/mfx-carrier/mfx_carriers.html">MFXCarrier</a></td></tr>
+  <tr><td>│   ├── TroughCarrier</td></tr>
+  <tr><td>│   └── TubeCarrier</td></tr>
+
+  <!-- Container subtree -->
+  <tr><td>├── Container</td></tr>
+  <tr><td>│   ├── Well</td></tr>
+  <tr><td>│   ├── PetriDish</td></tr>
+  <tr><td>│   ├── Tube</td></tr>
+  <tr><td>│   └── Trough</td></tr>
+
+  <!-- ItemizedResource subtree -->
+  <tr><td>├── <a href="itemized-resource/itemized-resource.html">ItemizedResource</a></td></tr>
+  <tr><td>│   ├── <a href="itemized-resource/plate/plate.html">Plate</a></td></tr>
+  <tr><td>│   ├── TipRack</td></tr>
+  <tr><td>│   └── TubeRack</td></tr>
+
+  <!-- ResourceHolder subtree -->
+  <tr><td>├── ResourceHolder</td></tr>
+  <tr><td>│   └── PlateHolder</td></tr>
+
+  <!-- Others -->
+  <tr><td>├── Lid</td></tr>
+  <tr><td>├── PlateAdapter</td></tr>
+  <tr><td>└── ResourceStack</td></tr>
+</table>
+
+----
 
 ```{toctree}
-:caption: Resource subclasses
+:maxdepth: 3
+:caption: Resource subclass explanations
+:hidden:
 
+carrier/carrier
 containers
-itemized_resource
-plates
-plate_carriers
-mfx
+itemized-resource/itemized-resource
 ```
 
 ## Library
 
-### Plate Naming Standard
-
-PLR is not actively enforcing a specific plate naming standard but recommends the following:
-
-![PLR_plate_naming_standards](img/PLR_plate_naming_standards.png)
-
-This standard is similar to the [Opentrons API labware naming standard](https://ecatalog.corning.com/life-sciences/b2b/UK/en/Microplates/Assay-Microplates/96-Well-Microplates/Costar%C2%AE-Multiple-Well-Cell-Culture-Plates/p/3516) but 1) further sub-categorizes "wellplates" to facilitate communication with day-to-day users, and 2) adds information about the well-bottom geometry.
-
 ```{toctree}
 :caption: Library
 

docs/resources/plate_carriers.ipynb docs/resources/carrier/plate-carrier/plate_carriers.ipynb

@@ -0,0 +1,39 @@
+ItemizedResource
+================
+
+Resources that contain items in a grid are subclasses of :class:`pylabrobot.resources.itemized_resource.ItemizedResource`. This class provides convenient methods for accessing the child-resources, such as by integer or SBS "A1" style-notation, as well as for traversing items in an ``ItemizedResource``. Examples of subclasses of ``ItemizedResource`` are :class:`pylabrobot.resources.plate.Plate` and :class:`pylabrobot.resources.tip_rack.TipRack`.
+
+To instantiate an ``ItemizedResource``, it is convenient to use the ``pylabrobot.resources.utils.create_equally_spaced_2d`` method to quickly initialize a grid of child-resources in a grid. Here's an example of a simple ``ItemizedResource``:
+
+.. code-block:: python
+
+   from pylabrobot.resources import ItemizedResource
+   from pylabrobot.resources.utils import create_equally_spaced_2d
+   from pylabrobot.resources.well import Well, WellBottomType
+
+   plate = ItemizedResource(
+     name="plate",
+     size_x=127,
+     size_y=86,
+     size_z=10,
+     items=create_equally_spaced_2d(
+       Well,                            # the class of the items
+       num_items_x=12,
+       num_items_y=8,
+       dx=12,                           # distance between the left items and the left border in the x-axis
+       dy=12,                           # distance between the bottom items and the front border in the y-axis
+       dz=0,                            # distance between the items and the bottom border in the z-axis
+       item_dx=9,                       # distance between the items in the x-axis
+       item_dy=9,                       # distance between the items in the y-axis
+
+       bottom_type=WellBottomType.FLAT, # a custom keyword argument passed to the Well initializer
+     )
+   )
+
+Subclasseses of :class:`ItemizedResource`
+------------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   plate/plate

docs/resources/index.md

@@ -0,0 +1,9 @@
+# Tutorial: Plate Definition
+
+work in progress
+
+Aim: give a complete Notebook people can download an directly use to sequentially measure `dz` and `material_z_thickness` of a new `Plate` definition they want to generate.
+
+## YouTube tutorial
+
+<iframe width="720" height="405" src="https://www.youtube.com/embed/ViHgIhU476Q" title="YouTube video player" frameborder="0" allow="autoplay; encrypted-media; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>