### Install Autoprotocol from source

Source: https://autoprotocol-python.readthedocs.io/en/latest/index.html

Clone the repository and install the library from source to access the latest features.

```bash
git clone https://github.com/autoprotocol/autoprotocol-python
cd autoprotocol-python
python setup.py install
```

--------------------------------

### Protocol Execution Example

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example of sealing and incubating a sample, then printing the protocol as a dictionary.

```APIDOC
## Protocol Execution Example

### Description
This example demonstrates sealing and incubating a sample using the Autoprotocol Python library, followed by converting the protocol to a dictionary format for output.

### Method
`p.seal(sample_ref_2)`
`p.incubate(sample_ref_2, "warm_37", "20:minute")`
`print json.dumps(p.as_dict(), indent=2)`

### Autoprotocol Output
```json
{
  "refs": {
    "sample_plate_2": {
      "id": "ct1cxae33lkj",
      "store": {
        "where": "ambient"
      }
    }
  },
  "instructions": [
    {
      "object": "sample_plate_2",
      "op": "seal"
    },
    {
      "duration": "20:minute",
      "where": "warm_37",
      "object": "sample_plate_2",
      "shaking": false,
      "op": "incubate"
    }
  ]
}
```

### Returns
- `dict`: A dictionary containing 'refs' and 'instructions', and optionally 'time_constraints' and 'outs'.

### Raises
- `RuntimeError`: If either the 'refs' or 'instructions' attribute is empty.
```

--------------------------------

### Install Dependencies and Pre-commit Hooks

Source: https://autoprotocol-python.readthedocs.io/en/latest/contributing.html

Install project dependencies and set up pre-commit hooks for linting and formatting. This is recommended after activating a virtual environment.

```bash
pip install -e '.[test, docs]'
pre-commit install

```

--------------------------------

### Install Autoprotocol via pip

Source: https://autoprotocol-python.readthedocs.io/en/latest/index.html

Install the latest stable release of the library using pip.

```bash
pip install autoprotocol
```

--------------------------------

### Example of Gradient Thermocycling Temperature

Source: https://autoprotocol-python.readthedocs.io/en/latest/builders.html

Example demonstrating how to specify a temperature gradient for a thermocycle step using a dictionary with 'top' and 'bottom' keys.

```python
temperature = {“top”: “50:celsius”, “bottom”: “45:celsius”}
```

--------------------------------

### Perform Fluorescence Measurement

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of initializing a protocol, defining a plate, and executing a fluorescence read.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.fluorescence(sample_plate, sample_plate.wells_from(0,12),
               excitation="587:nanometer", emission="610:nanometer",
               dataref="test_reading")
```

--------------------------------

### Thermocycle Example Usage

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Provides an example of how to define a thermocycle protocol with multiple stages, including initial denaturation, cycles with specific temperatures and durations, and final cooling. Lid temperature is also specified.

```python
from instruction import Thermocycle

```

--------------------------------

### Dispense Full Plate Usage

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example of initializing a plate reference and dispensing a reagent to all wells.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.dispense_full_plate(sample_plate,
                      "water",
                      "100:microliter")
```

--------------------------------

### GET /protocol/as_dict

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Returns the entire protocol as a dictionary containing refs and instructions.

```APIDOC
## GET /protocol/as_dict

### Description
Returns the entire protocol as a dictionary with keys “refs” and “instructions” and optionally “time_constraints” and “outs”.

### Response
#### Success Response (200)
- **refs** (dict) - The refified contents of the Protocol refs attribute.
- **instructions** (list) - The refified contents of the Protocol instructions attribute.

### Response Example
{
  "refs": {
    "sample_plate_2": {
      "id": "ct1cxae33lkj",
      "store": {
        "where": "ambient"
      }
    }
  },
  "instructions": [
    {
      "object": "sample_plate_2",
      "op": "seal"
    },
    {
      "duration": "20:minute",
      "where": "warm_37",
      "object": "sample_plate_2",
      "shaking": false,
      "op": "incubate"
    }
  ]
}
```

--------------------------------

### Illumina Sequencing Usage

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of configuring an Illumina sequencing run using the Protocol object.

```python
p = Protocol()
sample_wells = p.ref(
    "test_plate", None, "96-pcr", discard=True).wells_from(0, 8)

p.illuminaseq(
    "PE",
    [
        {"object": sample_wells[0], "library_concentration": 1.0},
        {"object": sample_wells[1], "library_concentration": 5.32},
        {"object": sample_wells[2], "library_concentration": 54},
        {"object": sample_wells[3], "library_concentration": 20},
        {"object": sample_wells[4], "library_concentration": 23},
        {"object": sample_wells[5], "library_concentration": 23},
        {"object": sample_wells[6], "library_concentration": 21},
        {"object": sample_wells[7], "library_concentration": 62}
    ],
    "hiseq", "rapid", 'none', 250, "my_illumina")
```

--------------------------------

### Perform Sanger Sequencing

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of initializing a protocol, referencing a plate, and executing a sangerseq instruction.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.sangerseq(sample_plate,
            sample_plate.wells_from(0,5).indices(),
            "seq_data_022415")
```

--------------------------------

### Define an Image instruction in JSON

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example of an Autoprotocol JSON structure for an image instruction.

```json
{
  "refs": {
    "Sample": {
      "new": "micro-1.5",
      "discard": true
    }
  },
  "instructions": [
    {
      "magnification": 1.0,
      "backlighting": false,
      "mode": "top",
      "dataref": "image_1",
      "object": "Sample",
      "num_images": 3,
      "op": "image",
      "exposure": {
        "iso": 4
      }
    }
  ]
}
```

--------------------------------

### Discard Container Example

Source: https://autoprotocol-python.readthedocs.io/en/latest/container.html

Demonstrates how to discard a container, marking it for disposal. This action also sets the storage condition to None.

```python
p = Protocol()
container = p.ref("new_container", cont_type="96-pcr",
                  storage="cold_20")
p.incubate(c, "warm_37", "30:minute")
container.discard()
```

--------------------------------

### Dispense Reagents to Columns

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of using the dispense instruction with column builders to distribute reagents.

```python
from autoprotocol.liquid_handle.liquid_handle_builders import *
from autoprotocol.instructions import Dispense
from autoprotocol import Protocol

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.dispense(sample_plate,
           "water",
           Dispense.builders.columns(
               [Dispense.builders.column(0, "10:uL"),
                Dispense.builders.column(1, "20:uL"),
                Dispense.builders.column(2, "30:uL"),
                Dispense.builders.column(3, "40:uL"),
                Dispense.builders.column(4, "50:uL")
               ])
           )

p.dispense(
    sample_plate,
    "water",
```

--------------------------------

### Capture Image Instruction Usage

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example usage for capturing an image of a container using the image instruction.

```python
p = Protocol()

                    sample = p.ref("Sample", None, "micro-1.5", discard=True)
                    p.image(sample, "top", "image_1", num_images=3,
                            backlighting=False, exposure={"iso": 4},
                            magnification=1.0)
```

--------------------------------

### Manifest JSON Structure

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/harness.html

Example of the expected format for a manifest.json file used to define protocol metadata and preview parameters.

```json
{
  "format": "python",
  "license": "MIT",
  "description": "This is a protocol.",
  "protocols": [
    {
      "name": "SampleProtocol",
      "version": 1.0.0,
      "command_string": "python sample_protocol.py",
      "preview": {
        "refs":{},
        "parameters": {},
        "inputs": {},
        "dependencies": []
      }
    }
  ]
}
```

--------------------------------

### Pipette instruction example

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

This JSON snippet defines a 'pipette' operation, specifying the volume, source, and destination for a liquid transfer.

```json
{
                  "groups": [
                    {
                      "transfer": [
                        {
                          "volume": "50.0:microliter",
                          "to": "my_plate/15",
                          "from": "my_plate/0"
                        }
                      ]
                    }
                  ],
                  "op": "pipette"
                }
```

--------------------------------

### Perform flow analysis with Python

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example demonstrating how to initialize a protocol and execute the flow_analyze instruction with defined FSC, SSC, and sample parameters.

```python
p = Protocol()
dataref = "test_ref"
FSC = {"voltage_range": {"low": "230:volt", "high": "280:volt"},
       "area": True, "height": True, "weight": False}
SSC = {"voltage_range": {"low": "230:volt", "high": "280:volt"},
       "area": True, "height": True, "weight": False}
neg_controls = {"well": "well0", "volume": "100:microliter",
                "captured_events": 5, "channel": "channel0"}
samples = [
    {
        "well": "well0",
        "volume": "100:microliter",
        "captured_events": 9
    }
]

p.flow_analyze(dataref, FSC, SSC, neg_controls,
               samples, colors=None, pos_controls=None)
```

--------------------------------

### Example Manifest Preview Output

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/harness.html

Illustrates the expected dictionary format for protocol inputs derived from a manifest's 'preview' section.

```json
{
    "qPCR_input1": "value",
    "qPCR_input2": "value2",
    "qPCR_group": {
        "group_entry1": "value",
        "group_entry2": "value"
    }
}
```

--------------------------------

### Autoprotocol JSON Output Example

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example of the JSON output generated by Autoprotocol for a defined protocol, showing referenced containers and their properties.

```json
{
  "refs": {
    "my_plate": {
      "id": "ct1xae8jabbe6",
      "store": {
        "where": "cold_4"
      }
    }
  }
}
```

--------------------------------

### Protocol Object Initialization and Usage

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Demonstrates how to initialize a Protocol object and add container references and instructions.

```APIDOC
## Protocol Object

### Description
A Protocol is a sequence of instructions to be executed, and a set of containers on which those instructions act.

### Parameters
- **refs** (Optional[Dict[str, Ref]]) - Pre-existing refs that the protocol should be populated with.
- **instructions** (List[Instruction]) - Pre-existing instructions that the protocol should be populated with.
- **propagate_properties** (bool, optional) - Whether liquid handling operations should propagate aliquot properties from source to destination wells.
- **time_constraints** (List[TimeConstraint]) - Pre-existing time_constraints that the protocol should be populated with.

### Examples
#### Initializing a Protocol and Referencing a Container
```python
p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                        cont_type="96-pcr", storage="cold_4")
```

#### Adding Instructions to a Protocol
```python
p.transfer(source=my_plate.well("A1"),
           dest=my_plate.well("B4"),
           volume="50:microliter")
p.thermocycle(my_plate, groups=[
             { "cycles": 1,
               "steps": [
                 { "temperature": "95:celsius",
                   "duration": "1:hour"
                 }]
             }])
```

### Autoprotocol Output Example
```json
{
  "refs": {
    "my_plate": {
      "id": "ct1xae8jabbe6",
      "store": {
        "where": "cold_4"
      }
    }
  }
}
```
```

--------------------------------

### Configure Spectrophotometry Instruction

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Demonstrates how to build complex spectrophotometry groups including absorbance, fluorescence, luminescence, and shaking parameters, then execute the instruction.

```python
p = Protocol()
read_plate = p.ref("read plate", cont_type="96-flat", discard=True)

groups = Spectrophotometry.builders.groups(
    [
        Spectrophotometry.builders.group(
            "absorbance",
            Spectrophotometry.builders.absorbance_mode_params(
                wells=read_plate.wells(0, 1),
                wavelength=["100:nanometer", "200:nanometer"],
                num_flashes=15,
                settle_time="1:second"
            )
        ),
        Spectrophotometry.builders.group(
            "fluorescence",
            Spectrophotometry.builders.fluorescence_mode_params(
                wells=read_plate.wells(0, 1),
                excitation=[
                    Spectrophotometry.builders.wavelength_selection(
                        ideal="650:nanometer"
                    )
                ],
                emission=[
                    Spectrophotometry.builders.wavelength_selection(
                        shortpass="600:nanometer",
                        longpass="700:nanometer"
                    )
                ],
                num_flashes=15,
                settle_time="1:second",
                lag_time="9:second",
                integration_time="2:second",
                gain=0.3,
                read_position="top"
            )
        ),
        Spectrophotometry.builders.group(
            "luminescence",
            Spectrophotometry.builders.luminescence_mode_params(
                wells=read_plate.wells(0, 1),
                num_flashes=15,
                settle_time="1:second",
                integration_time="2:second",
                gain=0.3
            )
        ),
        Spectrophotometry.builders.group(
            "shake",
            Spectrophotometry.builders.shake_mode_params(
                duration="1:second",
                frequency="9:hertz",
                path="ccw_orbital",
                amplitude="1:mm"
            )
        ),
    ]
)

shake_before = Spectrophotometry.builders.shake_before(
    duration="10:minute",
    frequency="5:hertz",
    path="ccw_orbital",
    amplitude="1:mm"
)

p.spectrophotometry(
    dataref="test data",
    obj=read_plate,
    groups=groups,
    interval="10:minute",
    num_intervals=2,
    temperature="37:celsius",
```

--------------------------------

### Define a qPCR Protocol

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

This example illustrates how to set up a qPCR protocol, which requires specifying dye types and datarefs. It includes a temperature profile suitable for qPCR.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")


```

--------------------------------

### GET /wells/all

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Retrieve all wells belonging to the container.

```APIDOC
## GET /wells/all

### Description
Return a WellGroup representing all Wells belonging to this Container.

### Method
GET

### Parameters
#### Query Parameters
- **columnwise** (bool) - Optional - If true, returns the WellGroup columnwise instead of rowwise.
```

--------------------------------

### Incubate a container in Autoprotocol

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Demonstrates how to define a protocol, reference a container, seal it, and initiate an incubation process.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed/covered before it can be incubated
p.seal(sample_plate)
p.incubate(sample_plate, "warm_37", "1:hour", shaking=True)
```

```none
"instructions": [
    {
       "object": "sample_plate",
       "op": "seal"
    },
    {
        "duration": "1:hour",
        "where": "warm_37",
        "object": "sample_plate",
        "shaking": true,
        "op": "incubate",
        "co2_percent": 0
    }
  ]
```

--------------------------------

### GET /_tip_capacity

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/liquid_handle_method.html

Estimates the maximum usable volume for a tip.

```APIDOC
## GET /_tip_capacity

### Description
Calculates the best estimate of total usable volume for a tip after accounting for overage volume, based on either a defined or calculated tip type.

### Response
#### Success Response (200)
- **max_volume** (Unit) - The maximum allowable volume for the method's tip type.
```

--------------------------------

### Load aliquots for Illumina sequencing

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Demonstrates how to initialize a protocol and call the illuminaseq method with a list of sample wells and their respective library concentrations.

```python
p = Protocol()
sample_wells = p.ref(
    "test_plate", None, "96-pcr", discard=True).wells_from(0, 8)

p.illuminaseq(
    "PE",
    [
        {"object": sample_wells[0], "library_concentration": 1.0},
        {"object": sample_wells[1], "library_concentration": 5.32},
        {"object": sample_wells[2], "library_concentration": 54},
        {"object": sample_wells[3], "library_concentration": 20},
        {"object": sample_wells[4], "library_concentration": 23},
        {"object": sample_wells[5], "library_concentration": 23},
        {"object": sample_wells[6], "library_concentration": 21},
        {"object": sample_wells[7], "library_concentration": 62}
    ],
    "hiseq", "rapid", 'none', 250, "my_illumina")
```

```none
"instructions": [
    {
        "dataref": "my_illumina",
        "index": "none",
        "lanes": [
            {
                "object": "test_plate/0",
```

--------------------------------

### Dispense API

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Documentation for the dispense instruction, including parameters and examples.

```APIDOC
## POST /api/instructions/dispense

### Description
Dispenses a specified reagent into a container.

### Method
POST

### Endpoint
/api/instructions/dispense

### Parameters
#### Request Body
- **instructions** (array) - Required - A list of dispense instructions.
  - **reagent** (string or Well) - Required - The reagent to dispense. Can be a string (name or resource ID) or a Well object.
  - **object** (string) - Required - The ID of the container to dispense into.
  - **volume** (string or Unit) - Required - The volume of reagent to dispense per well.
  - **is_resource_id** (boolean, optional) - If true, interprets reagent as a resource ID.
  - **step_size** (string or Unit, optional) - Specifies dispense using a peristaltic pump with a given step size. Must be one of 5 uL, 0.5 uL, or 0.05 uL. Defaults to vendor specified values if None.
  - **flowrate** (string or Unit, optional) - The rate of dispensing in volume/time.
  - **nozzle_position** (dict, optional) - Nozzle offsets from the bottom middle of the plate's wells. Format: {"position_x": Unit, "position_y": Unit, "position_z": Unit}.
  - **pre_dispense** (string or Unit, optional) - Volume of reagent to dispense per-nozzle into waste before dispensing into the ref.
  - **shape** (dict, optional) - Shape of the dispensing head. Format: {"rows": int, "columns": int, "format": str}.
  - **shake_after** (dict, optional) - Parameters for shaking the plate after dispensing.

### Request Example
```json
{
    "instructions": [
        {
            "reagent": "water",
            "object": "sample_plate",
            "columns": [
                {
                    "column": 0,
                    "volume": "100:microliter"
                },
                {
                    "column": 1,
                    "volume": "100:microliter"
                }
            ],
            "op": "dispense"
        }
    ]
}
```

### Response
#### Success Response (200)
- **Dispense** (object) - The dispense instruction created.

#### Response Example
```json
{
    "instructions": [
        {
            "reagent": "water",
            "object": "sample_plate",
            "columns": [
                {
                    "column": 0,
                    "volume": "100:microliter"
                },
                {
                    "column": 1,
                    "volume": "100:microliter"
                }
            ],
            "op": "dispense"
        }
    ]
}
```
```

--------------------------------

### GET /wells/inner

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Retrieve inner wells of a container, excluding edges.

```APIDOC
## GET /wells/inner

### Description
Return a WellGroup of all wells on a plate excluding wells in the top and bottom rows and in the first and last columns.

### Method
GET

### Parameters
#### Query Parameters
- **columnwise** (bool) - Optional - If true, returns the WellGroup columnwise instead of rowwise.
```

--------------------------------

### Get Protocol Preview from Manifest

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/harness.html

Parses the 'preview' section of a manifest to generate protocol inputs. Ensure the manifest file exists and protocol names are unique.

```python
p = Protocol()
preview = get_protocol_preview(p, name="qPCR")
```

--------------------------------

### GET /wells/decompose

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Decompose a well index into its row and column coordinates.

```APIDOC
## GET /wells/decompose

### Description
Return a tuple representing the column and row number of the well index given based on the ContainerType of the Container.

### Method
GET

### Parameters
#### Query Parameters
- **well_ref** (int, str, Well) - Required - The well index to decompose.
```

--------------------------------

### Build a basic protocol

Source: https://autoprotocol-python.readthedocs.io/en/latest/index.html

Define protocol references and instructions, then serialize the protocol object into Autoprotocol JSON.

```python
import json
from autoprotocol.protocol import Protocol

# instantiate a protocol object
p = Protocol()

# generate a ref
# specify where it comes from and how it should be handled when the Protocol is done
plate = p.ref("test pcr plate", id=None, cont_type="96-pcr", discard=True)

# generate seal and spin instructions that act on the ref
# some parameters are explicitly specified and others are left to vendor defaults
p.seal(
    ref=plate,
    type="foil",
    mode="thermal",
    temperature="165:celsius",
    duration="1.5:seconds"
)
p.spin(
    ref=plate,
    acceleration="1000:g",
    duration="1:minute"
)

# serialize the protocol as Autoprotocol JSON
print(json.dumps(p.as_dict(), indent=2))
```

--------------------------------

### GET /wells/humanize

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Convert an integer well index into a human-readable representation.

```APIDOC
## GET /wells/humanize

### Description
Return the human readable representation of the integer well index given based on the ContainerType of the Container.

### Method
GET

### Parameters
#### Query Parameters
- **well_ref** (int, str, list) - Required - The well index to convert.
```

--------------------------------

### GET /default_mix_after

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/transfer.html

Retrieves the default parameters for mixing after a dispense operation.

```APIDOC
## GET /default_mix_after

### Description
Generates the default mixing configuration, including repetitions, flow rates, and Z-positions, performed after a dispense step.

### Parameters
#### Request Body
- **volume** (Unit) - Required - The volume to mix.

### Response
#### Success Response (200)
- **dict** - A dictionary containing the mix_after parameters.
```

--------------------------------

### POST /instruction/Incubate

Source: https://autoprotocol-python.readthedocs.io/en/latest/instruction.html

Stores a sample in a specific environment for a defined duration.

```APIDOC
## POST /instruction/Incubate

### Description
Store a sample in a specific environment for a given duration.

### Request Body
- **object** (Ref or str) - Required - The container to be incubated
- **where** (Enum) - Required - Temperature environment (ambient, warm_37, cold_4, cold_20, cold_80)
- **duration** (Unit or str) - Required - Length of time to incubate
- **shaking** (bool) - Optional - Whether to shake the container
- **target_temperature** (Unit or str) - Optional - Target temperature for device
- **shaking_params** (dict) - Optional - Path and frequency of shaking
- **co2** (Number) - Optional - Carbon dioxide percentage
```

--------------------------------

### GET /_is_single_channel

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/liquid_handle_method.html

Checks if the current shape configuration is single-channel compatible.

```APIDOC
## GET /_is_single_channel

### Description
Determines whether the current shape represents a single channel by checking if rows and columns are equal to 1.

### Response
#### Success Response (200)
- **is_single** (bool) - True if single channel, false otherwise.
```

--------------------------------

### Build Documentation with Sphinx

Source: https://autoprotocol-python.readthedocs.io/en/latest/contributing.html

Generate HTML documentation using Sphinx. Ensure you are in the root cloned directory before running this command.

```bash
cd docs  # Assuming you're in the root cloned directory
sphinx-build -W -b html -d tmp/doctrees . tmp/html

```

--------------------------------

### Agitate Container Example

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Demonstrates how to agitate a container using specified mode, speed, duration, and temperature. Ensure the container type and parameters are valid.

```python
p = Protocol()
plate = p.ref("test pcr plate", id=None, cont_type="96-pcr",
              storage="cold_4")
p.agitate(
    ref = plate,
    mode="vortex",
    speed="1000:rpm",
    duration="5:minute",
    temperature="25:celsius"
)

```

--------------------------------

### Get Instruction Index

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Retrieves the index of the last appended instruction in the protocol.

```APIDOC
## GET /protocol/get_instruction_index

### Description
Get the index of the last appended instruction.

### Method
GET

### Endpoint
/protocol/get_instruction_index

### Parameters
None

### Request Example
```
protocol.get_instruction_index()
```

### Response
#### Success Response (200)
- **instruction_index** (int) - The index of the last appended instruction.

#### Response Example
```json
{
  "instruction_index": 0
}
```

### Errors
- **ValueError**: If an instruction index is less than 0.
```

--------------------------------

### GET /_rec_tip_type

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/liquid_handle_method.html

Retrieves the smallest appropriate tip type for a specified volume.

```APIDOC
## GET /_rec_tip_type

### Description
For a given volume, this method identifies the smallest available tip type that can accommodate the target volume plus the required overage.

### Parameters
#### Request Body
- **volume** (Unit) - Required - The target volume to be handled.

### Response
#### Success Response (200)
- **tip_name** (string) - The name of the recommended tip type.

#### Error Response (500)
- **RuntimeError** - Returned if no tip is large enough to hold the target volume plus overage.
```

--------------------------------

### Initialize Spectrophotometry Instruction

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/instruction.html

Creates a Spectrophotometry instruction for plate reads. Requires dataref, object, and groups. Optional parameters include interval, num_intervals, temperature, and shake_before.

```python
class Spectrophotometry(Instruction):
    """
    Execute a Spectrophotometry plate read on the obj.

    Parameters
    ----------
    dataref : str
        Name of the resultant dataset to be returned.
    object : Container or str
        Container to be read.
    groups : list
        A list of groups generated by SpectrophotometryBuilders groups builders, any of absorbance_mode_params, fluorescence_mode_params, luminescence_mode_params, or shake_mode_params.
    interval : Unit or str, optional
        The time between each of the read intervals.
    num_intervals : int, optional
        The number of times that the groups should be executed.
    temperature : Unit or str, optional
        The temperature that the entire instruction should be executed at.
    shake_before : dict, optional
        A dict of params generated by SpectrophotometryBuilders.shake_before that dictates how the obj should be incubated with shaking before any of the groups are executed.
    """

    builders = SpectrophotometryBuilders()

    def __init__(
        self,
        dataref,
        object,
        groups,
        interval=None,
        num_intervals=None,
        temperature=None,
        shake_before=None,
    ):
        spec = {
            "dataref": dataref,
            "object": object,
            "groups": groups,
            "interval": interval,
            "num_intervals": num_intervals,
            "temperature": temperature,
            "shake_before": shake_before,
        }

        super(Spectrophotometry, self).__init__(op="spectrophotometry", data=spec)
```

--------------------------------

### Initialize and Reference a Container in a Protocol

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Instantiate a Protocol object and add a reference to an existing container with specified properties. Use this to begin defining your experimental workflow.

```python
p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                        cont_type="96-pcr", storage="cold_4")
```

--------------------------------

### Define Thermocycle groups structure

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Example structure for the groups parameter in the thermocycle method.

```python
"groups": [{
    "cycles": integer,
    "steps": [
        {
            "duration": duration,
            "temperature": temperature,
            "read": boolean // optional (default false)
        },
        {
            "duration": duration,
            "gradient": {
```

--------------------------------

### Illumina Sequencing JSON Output

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of the JSON structure generated by an illuminaseq instruction.

```json
"instructions": [
    {
        "dataref": "my_illumina",
        "index": "none",
        "lanes": [
            {
                "object": "test_plate/0",
                "library_concentration": 1
            },
            {
                "object": "test_plate/1",
                "library_concentration": 5.32
            },
            {
                "object": "test_plate/2",
                "library_concentration": 54
            },
            {
                "object": "test_plate/3",
                "library_concentration": 20
            },
            {
                "object": "test_plate/4",
                "library_concentration": 23
            },
            {
                "object": "test_plate/5",
                "library_concentration": 23
            },
            {
                "object": "test_plate/6",
                "library_concentration": 21
            },
            {
                "object": "test_plate/7",
                "library_concentration": 62
            }
        ],
        "flowcell": "PE",
        "mode": "mid",
        "sequencer": "hiseq",
        "library_size": 250,
        "op": "illumina_sequence"
    }
]
```

--------------------------------

### Initialize Protocol and Reference Container

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Instantiate a Protocol object and add a reference to a container, specifying its ID, type, and storage location.

```python
p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                                    cont_type="96-pcr", storage="cold_4")
```

--------------------------------

### Acoustic Transfer JSON Output

Source: https://autoprotocol-python.readthedocs.io/en/latest/protocol.html

Example of the JSON structure generated by an acoustic_transfer instruction.

```json
[
    {
        "groups": [
            {
                "transfer": [
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/2",
                        "from": "echo_plate/0"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/3",
                        "from": "echo_plate/1"
                    },
                    {
                        "volume": "0.004:microliter",
                        "to": "plate/4",
                        "from": "echo_plate/1"
                    }
                ]
            }
        ],
        "droplet_size": "25:microliter",
        "op": "acoustic_transfer"
    }
]
```

--------------------------------

### GET /wells/robotize

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Convert a well reference into its integer representation based on the container type.

```APIDOC
## GET /wells/robotize

### Description
Return the integer representation of the well index given, based on the ContainerType of the Container.

### Method
GET

### Parameters
#### Query Parameters
- **well_ref** (str, int, Well, list) - Required - The well reference to convert.
```

--------------------------------

### Initialize Mix LiquidHandlingMethod

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/mix.html

Initializes the Mix LiquidHandlingMethod with optional tip type, blowout settings, repetitions, and Z-axis position. Blowout settings can be a boolean or a dictionary of parameters.

```python
def __init__(self, tip_type=None, blowout=True, repetitions=None, position_z=None):
    """
    Parameters
    ----------
    tip_type : str, optional
        tip_type to be used for the LiquidHandlingMethod
    blowout : bool or dict, optional
        whether to execute a blowout step or the parameters for one.
        this generates two operations, an initial air aspiration before
        entering any wells, and a corresponding final air dispense
        after the last operation that involves liquid
        See Also LiquidHandle.builders.blowout
    repetitions : int
        the number of times the mix should be repeated
    position_z : dict
        the position that the tip should move to prior to mixing, if the
        position references the `liquid_surface` then mix movements will
        track the surface with the defined offset.
        See Also LiquidHandle.builders.position_z
    """
    super(Mix, self).__init__(tip_type=tip_type, blowout=blowout)

    # parameters for required behavior
    self.repetitions = repetitions
    self.position_z = position_z

    # LiquidHandle parameters that are generated and modified at runtime
    self._liquid = None
```

--------------------------------

### Perform Sanger Sequencing with Autoprotocol

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Demonstrates how to initialize a protocol, reference a sample plate, and execute the sangerseq operation on a range of wells.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.sangerseq(sample_plate,
            sample_plate.wells_from(0,5).indices(),
            "seq_data_022415")
```

```none
"instructions": [
    {
        "dataref": "seq_data_022415",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5"
        ],
        "op": "sanger_sequence"
    }
]
```

--------------------------------

### GET /wells

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/container.html

Retrieve a WellGroup containing references to wells corresponding to the provided indices.

```APIDOC
## GET /wells

### Description
Return a WellGroup containing references to wells corresponding to the index or indices given.

### Method
GET

### Parameters
#### Query Parameters
- **args** (str, int, list) - Required - Reference or list of references to a well index either as an integer or a string.

### Response
#### Success Response (200)
- **WellGroup** (object) - Wells from specified references
```

--------------------------------

### Initialize EvaporateBuilders

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/builders.html

Initializes the EvaporateBuilders class, setting up lists of valid modes and parameters for different evaporation techniques.

```python
class EvaporateBuilders(InstructionBuilders):
    """
    Helpers for building Evaporate instructions
    """

    def __init__(self):
        super(EvaporateBuilders, self).__init__()
        self.valid_modes = [option.name for option in EvaporateBuildersValidModes]
        self.valid_gases = [option.name for option in EvaporateBuildersValidGases]
        from autoprotocol.types.builders import EvaporateBuildersRotateParams

        self.rotate_params = [option.name for option in EvaporateBuildersRotateParams]
        self.centrifuge_params = [
            option.name for option in EvaporateBuildersCentrifugeParams
        ]
        self.vortex_params = [option.name for option in EvaporateBuildersVortexParams]
        self.blowdown_params = [
            option.name for option in EvaporateBuildersBlowdownParams
        ]
```

--------------------------------

### GET /liquid_class/calibrated_volume

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/liquid_handle/liquid_class.html

Calculates the calibrated volume for a specific transfer volume and tip type.

```APIDOC
## GET /liquid_class/calibrated_volume

### Description
Calculates the calibrated volume for a given volume and tip_type based on the liquid class configuration.

### Parameters
#### Query Parameters
- **volume** (str or Unit) - Required - Desired volume to be transferred into the target well
- **tip_type** (str) - Required - Liquid handling device to be used for the transfer

### Response
#### Success Response (200)
- **calibrated_volume** (Unit) - The calculated calibrated volume
```

--------------------------------

### Initialize Sonicate Instruction

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/instruction.html

Constructs a Sonication instruction. Specify temperature, frequency, mode, and mode-specific parameters.

```python
class Sonicate(Instruction):
    """
    Sonication instruction.

    Parameters
    ----------
    wells: WellGroup
        Wells to sonicate.
    duration: Unit
        Duration of sonication.
    mode: str
        Mode of sonication (`horn` or `bath`).
    temperature: Unit or str, optional
        Temperature at which the sample is kept during sonication. Optional, defaults to ambient
    frequency: Unit or str, optional
        Frequency of the ultrasonic wave, usually indicated in kHz. Optional; defaults to the most commonly used frequency for each mode: 20 kHz for `horn`, and 40 kHz for `bath` mode
    mode_params: Dict
        Dictionary containing mode parameters for the specified mode.

    """

    def __init__(self, wells, duration, mode, mode_params, frequency, temperature):
        json_dict = {
            "wells": wells,
            "duration": duration,
            "frequency": frequency,
            "mode": mode,
            "mode_params": mode_params,
        }
        if temperature:
            json_dict["temperature"] = temperature
        super(Sonicate, self).__init__(op="sonicate", data=json_dict)
```

--------------------------------

### Perform Liquid Transfers

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Examples of using standard and specialized transfer methods for liquid handling.

```python
from autoprotocol.liquid_handle import Transfer
from autoprotocol.instruction import LiquidHandle

p.transfer(
    source.well(0), destination.well(0), "5:ul",
    method=Transfer(
        mix_before=True,
        dispense_z=LiquidHandle.builders.position_z(
           reference="well_top"
        )
    )
)
```

```python
from autoprotocol.liquid_handle import DryWellTransfer

p.transfer(
    source.well(0), destination.well(1), "5:ul",
    method=DryWellTransfer
)
```

--------------------------------

### Example Protocol with Seal/Unseal/Cover Operations

Source: https://autoprotocol-python.readthedocs.io/en/latest/autoprotocol.html

This Python method demonstrates basic container operations including transfer, sealing, unsealing, covering, and uncovering. It's intended for use within a protocol definition.

```python
def example_method(protocol, params):
cont = params['container']
p.transfer(cont.well("A1"), cont.well("A2"), "10:microliter")
p.seal(cont)
p.unseal(cont)
p.cover(cont)
p.uncover(cont)
```

--------------------------------

### Illumina Sequencing Lane Configuration Example

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/protocol.html

Defines the structure for specifying lanes in an Illumina sequencing run, including the source aliquot/well and the library concentration.

```none
"lanes": [
{
    "object": aliquot, Well,
    "library_concentration": decimal, // ng/uL
},
{
    "object": "test_plate/1",
    "library_concentration": 5.32
},
{
    "object": "test_plate/2",
    "library_concentration": 54
},
{
    "object": "test_plate/3",
    "library_concentration": 20
},
{
    "object": "test_plate/4",
    "library_concentration": 23
},
{
    "object": "test_plate/5",
    "library_concentration": 23
},
{
    "object": "test_plate/6",
    "library_concentration": 21
},
{
    "object": "test_plate/7",
    "library_concentration": 62
}
]
```

--------------------------------

### Initialize Provision Instruction

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/instruction.html

Initializes the Provision instruction to dispense a specified resource from a catalog into destination wells. Ensures a new tip is used for each destination to prevent contamination and validates the measurement mode.

```python
def __init__(self, resource_id, dests, measurement_mode="volume", informatics=None):
        if measurement_mode not in PROVISION_MEASUREMENT_MODES:
            raise RuntimeError(
                f"{measurement_mode} is not a valid measurement mode for provisioning"
            )

        super(Provision, self).__init__(
            op="provision",
            data={
                "resource_id": resource_id,
                "measurement_mode": measurement_mode,
                "to": dests,
            },
            informatics=informatics,
        )
```

--------------------------------

### Build LiquidHandle mode parameters

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/builders.html

Helper method for building transport mode parameters, including tip positioning and volume resolution settings.

```python
def mode_params(
        self,
        liquid_class: Optional[str] = None,
        position_x: Optional[dict] = None,
        position_y: Optional[dict] = None,
        position_z: Optional[dict] = None,
        tip_position: Optional[dict] = None,
        volume_resolution: Optional[VOLUME] = None,
    ):
        """Helper for building transport mode_params

        Mode params contain information about tip positioning and the
        liquid being manipulated

        Parameters
        ----------
        liquid_class : str, optional
            The name of the liquid class to be handled. This affects how
            vendors handle populating liquid handling defaults.
        position_x : dict, optional
            Target relative x-position of tip in well.
            See Also LiquidHandle.builders.position_xy
        position_y : dict, optional
            Target relative y-position of tip in well.
            See Also LiquidHandle.builders.position_xy
        position_z : dict, optional
            Target relative z-position of tip in well.
            See Also LiquidHandle.builders.position_z
        tip_position : dict, optional
            A dict of positions x, y, and z. Should only be specified if none of
            the other tip position parameters have been specified.
        volume_resolution : Unit, optional
            LiquidHandle dispense mode volume resolution specifies the droplet size to dispense.
            A specified resolution will exclude machines that are not configured for the given droplet size.
            By default, None means any droplet size will suffice. Check default droplet size on your machine configuration.


        Returns
        -------
        dict
            mode_params for a LiquidHandle instruction

        Raises
        ------
        ValueError
```

--------------------------------

### Serialized Autoprotocol JSON output

Source: https://autoprotocol-python.readthedocs.io/en/latest/index.html

The resulting JSON structure generated by the protocol building example.

```json
{
  "instructions": [
    {
      "op": "seal",
      "object": "test pcr plate",
      "type": "foil",
      "mode": "thermal",
      "mode_params": {
        "temperature": "165:celsius",
        "duration": "1.5:second"
      }
    },
    {
      "op": "spin",
      "object": "test pcr plate",
      "acceleration": "1000:g",
      "duration": "1:minute"
    }
  ],
  "refs": {
    "test pcr plate": {
      "new": "96-pcr",
      "discard": true
    }
  }
}
```

--------------------------------

### POST /incubate

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/instruction.html

Stores a sample in a specific environment for a given duration.

```APIDOC
## POST /incubate

### Description
Stores a sample in a specific temperature environment for a set duration.

### Method
POST

### Endpoint
/incubate

### Request Body
- **object** (str) - Required - Container to be incubated
- **where** (str) - Required - Temperature environment (e.g., ambient, warm_37, cold_4)
- **duration** (str) - Required - Length of incubation
- **shaking** (bool) - Optional - Whether to shake the container
- **co2** (number) - Optional - CO2 percentage
- **target_temperature** (str) - Optional - Target device temperature
- **shaking_params** (dict) - Optional - Shaking path and frequency
```

--------------------------------

### Unit Output Representation

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/unit.html

Expected string output format for the provided Unit arithmetic examples.

```none
10000010.0:microliter
10.0:microliter / second
0.036:liter / hour
```

--------------------------------

### Initialize MeasureVolume Instruction

Source: https://autoprotocol-python.readthedocs.io/en/latest/_modules/autoprotocol/instruction.html

Creates an instruction to measure the volume of containers. Accepts a list of containers and a dataref name.

```python
class MeasureVolume(Instruction):
    """
    Measure the mass of containers

    Parameters
    ----------
    object: list(Container)
        list of containers
    dataref: str
        Name of the data for the measurement
    """

    def __init__(self, object, dataref):
        json_dict = {"object": object, "dataref": dataref}
        super(MeasureVolume, self).__init__(op="measure_volume", data=json_dict)
```