Protocols¶

If you have successfully downloaded the data and information for a Project you can now access the Protocol used with the MultispeQ as well.

When you look at the Protoject’s information in it’s raw format, you will notice, the dictionary has two keys related to the Protocols. It is important to understand the difference before working with them.

protocols contains a list with the protocols associated with the Project. It contains detailed information like the Protocol’s name, its author, the actual code, the macro to analyze the raw output, and much more.
protocol_json is on the same level as protocols and contains the actual protocol code sent to the MultispeQ.

Important

Since protocol_json contains the actual code sent to the MultispeQ, it is strongly recommended to use for the analysis as well. All the functions described below use this protocol code.

MultispeQ Protocols¶

The code below is a recap from the previous example on how to access the protocol name and code.

Example: Get the protocol from the project information¶

import jii_multispeq.project as project
import jii_multispeq.protocol as protocol

projectId = 29652

## Get the project data and information
df, info = project.get(projectId=projectId)

## Get Protocol Name
protocol_name =  protocol.get_protocol_name(info)
print(protocol_name)

## Get the code for the selected protocol
protocol_code =  protocol.get_protocol(info)
print( protocol_code )

In contrast to the Project example, here we only define the projectId variable, assuming we already saved the project’s data & information locally.

Important

There are actually multiple ways to get the protocol’s name. The names are also used in the dataframe dictionary called df in this examle. To list the names you can also run the following code:

df, info = project.download( projectId=projectId )
print( df.keys() )

Protocol Code¶

In the above example the variable protocol_code is created to contain the protocol’s code from a project. Instead of receiving the protocol code from a project, it can also simply be defined in a script.

Example: Protocol defined instead of received from project information¶

protocol_code = {
   # Protocol Instructions
}

In the subsequent examples the varibale protocol_code will be used to access the diffent components of the protocol which can be used in the data analysis.

Variable Arrays (`v_arrays`)¶

examples/python/protocol-data.py¶

## Get the variable array (v_arrays) from a selected protocol
v_arrays = protocol.get_v_arrays(protocol_code)
print( v_arrays )

Sub-Protocols¶

Most more complex protocols are devided up into sub-protocols within the _protocol_sets_ key of the protocol code. The functions below allow to access such sub-protocols.

Labels¶

Each sub-protocol can be identified by a label. The function get_subprotocol_labels() returns a list of labels for each sub-protocol. In case a sub-protocol has no label, None is returned.

Example: Get sub-protocol labels¶

## Get all labels from sub-protocols
labels = protocol.get_subprotocol_labels(protocol_code)
print( labels )

Output: List of sub-protocol labels¶

['no_leaf_baseline', None, 'env', 'PIRK', 'PAM', 'spad', 'finish']

Sub-Protocol (by Label)¶

Example: Get sub-protocol by label name¶

## Get sub-protocols by label
by_label = protocol.get_subprotocols_by_label(protocol_code, "PIRK")
print( by_label )

Output: Sub-protocol as returned by label name¶

[
  {'label': 'env', 
    'environmental': [
      ['light_intensity'], 
      ['temperature_humidity_pressure'], 
      ['temperature_humidity_pressure2'], 
      ['contactless_temp'], 
      ['compass_and_angle']
    ], 
    'autogain': [
        [1, 1, 3, 20, 50000],
        [0, 10, 1, 20, 50000]
      ],
    'do_once': 1,
    'e_time': 1
  }
]

Important

The get_subprotocols_by_label() function returns a list with dictionaries.

Sub-Protocol (by Index)¶

The get_subprotocol_by_index() function returns a single sub-protocol based on the index position.

Example: Get sub-protocol by index position¶

## Get sub-protocols by index
by_index = protocol.get_subprotocol_by_index(protocol_code, 2)
print( by_index )

Output: Sub-protocol as returned by index¶

[
  {'label': 'env', 
    'environmental': [
      ['light_intensity'], 
      ['temperature_humidity_pressure'], 
      ['temperature_humidity_pressure2'], 
      ['contactless_temp'], 
      ['compass_and_angle']
    ], 
    'autogain': [
        [1, 1, 3, 20, 50000],
        [0, 10, 1, 20, 50000]
      ],
    'do_once': 1,
    'e_time': 1
  }
]

Important

The get_subprotocol_by_index() function returns a dictionary.

Project Protocol Example¶

To summarize, this is the full example to get a protocol from the Project’s information and extract different information from it for an advanced data analysis.

examples/python/protocol-data.py¶

"""
Working with a Protocol 

Accessing the protocol from the Project Information and
it's components which can further assist in the data analysis.
"""

import jii_multispeq.project as project
import jii_multispeq.protocol as protocol

projectId = 29652

## Get the project data and information
df, info = project.get(projectId=projectId)

## Get Protocol Name
protocol_name =  protocol.get_protocol_name(info)
print(protocol_name)

## Get the code for the selected protocol
protocol_code =  protocol.get_protocol(info)
print( protocol_code )

## Get the variable array (v_arrays) from a selected protocol
v_arrays = protocol.get_v_arrays(protocol_code)
print( v_arrays )

## Get all labels from sub-protocols
labels = protocol.get_subprotocol_labels(protocol_code)
print( labels )

## Get sub-protocols by label
by_label = protocol.get_subprotocols_by_label(protocol_code, "PIRK")
print( by_label )

## Get sub-protocols by index
by_index = protocol.get_subprotocol_by_index(protocol_code, 2)
print( by_index )

Download: python script [.py] Jupyter Notebook [.ipynb]

Local Protocols¶

When using the MultispeQ locally, it can be beneficial, to save the protocol and the accompanying analysis function in a separate file, instead of copying the protocol into separate script files.

The suggested template contains a header for a detailed description, the protocol code (_protocol), the analysis function (_analyze) and an example response from a MultispeQ (_example).

Note

More Resources

More information on the available protocol commands and structure as well as protocols to use with the MultispeQ are available with the JII-MultispeQ-Protocols package and the accompanying Documentation - JII-MultispeQ-Protocols.

Protocol File - Template¶

Example file for protocol and analysis code¶

"""
Protocol Name
=============

A detailed protocol description

"""

# MultispeQ Protocol
_protocol = [{}]

# Function to analyze MultispeQ measurement
def _analyze ( data ):
  """
  Analysis of the data returned from the MultispeQ
  """

  # Define the output dictionary here
  output = {}

  return output

# Example measurement (from MultispeQ, not analyzed - optional)
_example = [{}]

Download: Template [.py] - Protocol Template

Protocols¶

MultispeQ Protocols¶

Protocol Code¶

Variable Arrays (v_arrays)¶

Sub-Protocols¶

Labels¶

Sub-Protocol (by Label)¶

Sub-Protocol (by Index)¶

Project Protocol Example¶

Local Protocols¶

Protocol File - Template¶

Variable Arrays (`v_arrays`)¶