API Reference
=============

Trap steering
-------------

Control over trap steering is provided through the `Trap` class. Instances of this class are available by default as::

    from bluelake import trap1, trap2, trap3, trap4

    trap1.move_to(x=1, y=2)

    # Note: this line will fail on dual-trap systems:
    trap3.move_to(x=0, y=0)

    # Additional trap steering devices that are defined in bluelake:
    # (depending on actual availability of the hardware on your C-Trap)
    from bluelake import trap12xy, trap12z, trap34xy, trap34z, nanostage

.. autoclass:: bluelake.Trap


Stage control
-------------

Navigation within the flowcell is done through ``bluelake.stage``, an instance of the `Stage` class::

    from bluelake import stage

    stage.move_to('My favorite point')

.. autoclass:: bluelake.Stage


Fluidics control
----------------

To contol the microfluidics, use ``bluelake.fluidics``, an instance of the `Fluidics` class::

    from bluelake import fluidics

    fluidics.open_valves(1, 2, 3, 6)

.. autoclass:: bluelake.Fluidics


Power control
-------------

Power settings can be changed through the following objects that are defined in the ``bluelake`` module::

    from bluelake import power

    # Trapping laser
    print(power.trapping_laser)  # power in %
    power.trapping_laser = 50    # set to 50% power

    # Power modulation (availability varies per system)
    print(power.overall_trapping_power)
    print(power.qtrap_split)
    print(power.trap1_split)

    # Bright-field LED
    print(power.bright_field_led)

    # Excitation lasers (only for confocal systems)
    from bluelake import excitation_lasers
    print(excitation_lasers.red)
    print(excitation_lasers.green)
    print(excitation_lasers.blue)



Timeline
--------

Access to data from the timeline is provided through the ``bluelake.timeline`` object, an instance of the `Timeline` class described below.

Index `timeline` to gain access to individual channels::

    from bluelake import timeline

    force_channel = timeline["Force HF"]["Force 1x"]

The first index is the name of a channel group; the second index is the name of a channel within the group. Group and channel names match the ones displayed in the Bluelake user interface.

The above code snippet sets the ``force_channel`` variable to an instance of the `Channel` class described below. We can now, for instance, check the latest force value that has been measured using::

    print(force_channel.latest_value)


.. autoclass:: _timeline.Timeline
   :exclude-members: add_channel, add_channel_from_file, add_group

.. autoclass:: _timeline.Group

.. autoclass:: _timeline.Channel
   :exclude-members: slice_at_lod

.. autoclass:: _timeline.Spec


Confocal
--------

For C-Trap systems that feature a confocal scanner, a ``bluelake.confocal`` object is available. Through this instance of the `Scanner` class described below, simple automation of confocal scans can be done.

.. py:module:: confocal

.. autoclass:: _confocal.Scanner

Miscellaneous
-------------

.. autofunction:: bluelake.pause

.. function:: reset_force

    Set forces to zero. Calibrate force offsets for all channels to zero force.

.. autofunction:: bluelake.get_force_calibration
.. autoclass:: bluelake.PiezoTracker