From 6de3f6de963249cbc9a5b4777cd6be6daf221e6d Mon Sep 17 00:00:00 2001 From: Edward Cormany Date: Tue, 13 Aug 2024 16:38:00 -0400 Subject: [PATCH] accessing CSV data --- api/docs/v2/parameters/using_values.rst | 24 +++++++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/api/docs/v2/parameters/using_values.rst b/api/docs/v2/parameters/using_values.rst index bd61e7af8b85..6c9558b18330 100644 --- a/api/docs/v2/parameters/using_values.rst +++ b/api/docs/v2/parameters/using_values.rst @@ -33,7 +33,7 @@ You can also save parameter values to variables with names of your choosing. Parameter Types =============== -Each attribute of ``params`` has the type corresponding to its parameter definition. Keep in mind the parameter's type when using its value in different contexts. +Each attribute of ``params`` has the type corresponding to its parameter definition (except CSV parameters; see :ref:`rtp-csv-data` below). Keep in mind the parameter's type when using its value in different contexts. Say you wanted to add a comment to the run log, stating how many samples the protocol will process. Since ``sample_count`` is an ``int``, you'll need to cast it to a ``str`` or the API will raise an error. @@ -45,6 +45,28 @@ Say you wanted to add a comment to the run log, stating how many samples the pro Also be careful with ``int`` types when performing calculations: dividing an ``int`` by an ``int`` with the ``/`` operator always produces a ``float``, even if there is no remainder. The :ref:`sample count use case ` converts a sample count to a column count by dividing by 8 — but it uses the ``//`` integer division operator, so the result can be used for creating ranges, slicing lists, and as ``int`` argument values without having to cast it in those contexts. +.. _rtp-csv-data: + +Manipulating CSV Data +===================== + +CSV parameters have their own :py:class:`~opentrons.protocols.parameters.types.CSVParameter` type, since they don't correspond to a built-in Python type. This class has properties and methods that let you access the CSV data in one of three ways: as a file handler, as a string, or as nested lists. + +The :py:obj:`.CSVParameter.file` parameter provides a `file handler object `_ that points to your CSV data. You can pass this object to functions of the built-in :py:obj:`csv` module, or to other modules you import, such as ``pandas``. + +The :py:obj:`.CSVParameter.contents` parameter returns the entire contents of the CSV file as a single string. You then need to parse the data yourself to extract the information you need. + +The :py:meth:`.CSVParameter.parse_as_csv` method returns CSV data in a structured format. Specifically, it is a list of list of strings. This lets you access any "cell" of your tabular data by row and column index. This example parses a runtime parameter named ``csv_data``, stores the parsed data as ``parsed_csv``, and then accesses different portions of the data:: + + parsed_csv = protocol.params.csv_data + parsed_csv[0] # first row (header, if present) + parsed_csv[1][2] # second row, third column + [row[1] for row in parsed_csv] # second column + +.. versionadded:: 2.20 + +Remember that, like all Python lists, the lists representing your CSVs are zero-indexed. + Limitations ===========