Add preliminary documentation for read_rockmaker()

docs/api/index.rst

@@ -1,7 +1,7 @@
 traytable methods
 =================
 
-Note that the submodules ``traytable.screens`` and ``traytable.wells`` exist purely for bookkeeping, and all four methods below (``screen()``, ``tray()``, ``clonetray()`` and ``well()`` are available from the top-level ``import traytable``.
+Note that the submodules ``traytable.screens``, ``traytable.wells``, ``traytable.csv`` exist purely for bookkeeping, and all methods below are available from the top-level ``import traytable``.
 
 Making screens and trays
 ------------------------
@@ -14,5 +14,9 @@ Logging crystals
 
 .. automodule:: traytable.wells
    :members: well
+
+.. automodule:: traytable.csv
+   :members: read_rockmaker
+
 
 The methods ``setrows()`` and ``setcols()`` are exported by the package, but not documented here because their use is not recommended, and they may be deprecated in a future version.

docs/quickstart/index.md

@@ -56,6 +56,10 @@ To save some typing, you can create trays with `tt.clonetray()`. Usage is `newtr
 tray1 = tt.tray(screen, rows=[1,8], cols=[5,10], date='2021-01-02'
 tray2 = tt.clonetray(tray1, date='2021-01-03')
 ```
+#### The `read_rockmaker()` method
+**Note**: More extensive documentation of this feature to come.  
+It is possible to score crystals on RockMaker/RockImager via the online GUI. As a preliminary means of interfacing between `traytable` and RockMaker, I have added the `tt.read_rockmaker()` function, which accepts a "Score Report" `.csv` file and reads it into a `traytable` format.
+
 #### Special treatment of dates  
 A crystal will frequently have two dates associated with it - when the tray was set, and when the crystal is being logged. Two things of note happen to address this:
  - Arguments named `'date'` passed to `tt.tray()` and `tt.well()` automatically become columns named `'date_set'` and `'date_logged'`, respectively.

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = traytable
-version = 0.2.0
+version = 0.2.1
 author = Dennis Brookner
 author_email = debrookner@gmail.com
 description = A python package for tabulating crystallization results across many trays

traytable/csv.py

@@ -9,7 +9,27 @@
 
 
 def read_rockmaker(tray, filename=None, path=".", score_dict=None, old_df=None):
-
+    """
+    Import crystal hits via a RockMaker-style csv file
+
+    Parameters
+    ----------
+    tray : dict
+        The tray, produced by tt.tray, for which you are logging hits.
+    filename : string, optional
+        The name of the csv file. Defaults to "Score Report - {tray name}.csv"
+    path : string, optional
+        Filepath to the csv file, if not in the current directory
+    score_dict : dict, optional
+        If None (default), scores are left as integers 1-9. If "rockmaker", integers are converted via the rockmaker naming convention.
+        Any other dictionary can be passed and used to convert integer scores as desired.
+    olf_df : pandas.core.frame.DataFrame, optional
+        Dataframe to which results should be appended
+    Returns
+    -------
+    screen : dict
+        A dictionary containing the screen
+    """
     if filename is None:
         temp = argname(tray)
         filename = f"Score Report - {temp}.csv"
@@ -61,7 +81,7 @@ def read_rockmaker(tray, filename=None, path=".", score_dict=None, old_df=None):
         data[key] = value
 
     if score_dict is not None:
-        if score_dict == "default":
+        if score_dict == "rockmaker":
             score_dict = {
                 0: "Clear",
                 1: "Dust",