Updating README

README.rst

@@ -70,30 +70,37 @@ object IDs in the ``OMERO.table``.
 
 The ``CSV`` file must be provided as local file with ``--file path/to/file.csv``.
 
-If you wish to ensure that ``number`` columns are created for numerical data, this will
-allow you to make numerical queries on the table.
-Column Types are:
+OMERO.tables have defined column types to specify the data-type such as `double` or `long` and special object-types of each column for storing OMERO object IDs such as ``ImageColumn`` or ``WellColumn``
 
+**The default behaviour of the script is to automatically detect these column types from an input ``CSV``**. This behaviour works as folows:
+* Columns named with a supported object-type (e.g. 'image', 'plate'...) or with object_id (e.g. 'image_id', 'dataset_id' ) will generate the corresponding column type in the OMERO.table. e.g (ImageColumn, PlateColumn, DatasetColumn, etc)
+* Other column types will be detected based on the column's data using the pandas library (e.g. column of data type double).
+
+
+However, it is possible to manually define the column types , ignoring the automatic header detection, if a ``CSV`` with a ``# header`` row is passed. The ``# header`` row should be the first row of the CSV and defines columns according to the following list (see examples below):
 - ``d``: ``DoubleColumn``, for floating point numbers
 - ``l``: ``LongColumn``, for integer numbers
 - ``s``: ``StringColumn``, for text
 - ``b``: ``BoolColumn``, for true/false
 - ``plate``, ``well``, ``image``, ``dataset``, ``roi`` to specify objects
 
-These can be specified in the first row of a ``CSV`` with a ``# header`` tag (see examples below).
-The ``# header`` row is optional. Default column type is ``String``.
+Automatic header detection can also be ignored if using the ``--manual_headers`` flag. If the ``# header`` is not present and this flag is used, column types will default to ``String`` (unless the column names correspond to OMERO objects such as ``image`` or ``plate``).
 
 NB: Column names should not contain spaces if you want to be able to query
 by these columns.
 
+Examples
+^^^^^^^^^
+
 **Project / Dataset**
+^^^^^^^^^
 
 To add a table to a Project, the ``CSV`` file needs to specify ``Dataset Name``
 and ``Image Name`` or ``Image ID``::
 
     $ omero metadata populate Project:1 --file path/to/project.csv
-
-project.csv::
+    
+project.csv (manual column types definition)::
 
     # header s,s,d,l,s
     Image Name,Dataset Name,ROI_Area,Channel_Index,Channel_Name
@@ -102,7 +109,15 @@ project.csv::
     img-03.png,dataset01,0.093,3,TRITC
     img-04.png,dataset01,0.429,4,Cy5
 
-This will create an OMERO.table linked to the Project like this with
+project.csv (automatic column types detection)::
+
+    Image Name,Dataset Name,ROI_Area,Channel_Index,Channel_Name
+    img-01.png,dataset01,0.0469,1,DAPI
+    img-02.png,dataset01,0.142,2,GFP
+    img-03.png,dataset01,0.093,3,TRITC
+    img-04.png,dataset01,0.429,4,Cy5
+
+Both manual definition or automatic detection of column types will create an OMERO.table linked to the Project as folows with
 a new ``Image`` column with IDs:
 
 ========== ============ ======== ============= ============ =====
@@ -118,11 +133,14 @@ If the target is a Dataset instead of a Project, the ``Dataset Name`` column is
 
 
 **Screen / Plate**
+^^^^^^^^^
 
 To add a table to a Screen, the ``CSV`` file needs to specify ``Plate`` name and ``Well``.
-If a ``# header`` is specified, column types must be ``well`` and ``plate``.
+If a ``# header`` is specified, column types must be ``well`` and ``plate``::
 
-screen.csv::
+    $ omero metadata populate Screen:1 --file path/to/screen.csv
+
+screen.csv (manual column types definition)::
 
     # header well,plate,s,d,l,d
     Well,Plate,Drug,Concentration,Cell_Count,Percent_Mitotic
@@ -131,7 +149,15 @@ screen.csv::
     A3,plate01,DMSO,5.5,550,4
     B1,plate01,DrugX,12.3,50,44.43
 
-This will create an OMERO.table linked to the Screen, with the
+screen.csv (automatic column types detection)::
+
+    Well,Plate,Drug,Concentration,Cell_Count,Percent_Mitotic
+    A1,plate01,DMSO,10.1,10,25.4
+    A2,plate01,DMSO,0.1,1000,2.54
+    A3,plate01,DMSO,5.5,550,4
+    B1,plate01,DrugX,12.3,50,44.43
+
+Similarly, this will create an OMERO.table linked to the Screen, with the
 ``Well Name`` and ``Plate Name`` columns added and the ``Well`` and
 ``Plate`` columns used for IDs:
 
@@ -147,6 +173,7 @@ Well  Plate  Drug   Concentration  Cell_Count  Percent_Mitotic  Well Name   Plat
 If the target is a Plate instead of a Screen, the ``Plate`` column is not needed.
 
 **ROIs**
+^^^^^^^^^
 
 If the target is an Image or a Dataset, a ``CSV`` with ROI-level or Shape-level data can be used to create an
 ``OMERO.table`` (bulk annotation) as a ``File Annotation`` linked to the target object.
@@ -158,9 +185,11 @@ NB: Columns of type ``shape`` aren't yet supported on the OMERO.server.
 
 Alternatively, if the target is an Image, the ROI input column can be
 ``Roi Name`` (with type ``s``), and an ``roi`` type column will be appended containing ROI IDs.
-In this case, it is required that ROIs on the Image in OMERO have the ``Name`` attribute set.
+In this case, it is required that ROIs on the Image in OMERO have the ``Name`` attribute set::
+
+    $ omero metadata populate Image:1 --file path/to/image.csv
 
-image.csv::
+image.csv (manual column types definition)::
 
     # header roi,l,l,d,l
     Roi,shape,object,probability,area
@@ -169,6 +198,16 @@ image.csv::
     503,1068,3,0.2,25
     503,1069,4,0.8,400
     503,1070,5,0.5,200
+
+
+image.csv (automatic column types detection)::
+
+    Roi,shape,object,probability,area
+    501,1066,1,0.8,250
+    502,1067,2,0.9,500
+    503,1068,3,0.2,25
+    503,1069,4,0.8,400
+    503,1070,5,0.5,200
 
 This will create an OMERO.table linked to the Image like this: