accessing CSV data

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 <use-case-sample-count>` 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 <https://docs.python.org/3/c-api/file.html>`_ 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
 ===========