Add usage info to README

[will-moore]

Currently, arriving at https://pypi.org/project/omero-metadata/ (e.g. from the new 'apps' page ome/www.openmicroscopy.org#249) users have no idea what this tool does or how to use it.

Even $ bin/omero metadata --help would be a useful starting point.

[will-moore]

I again find myself trying to understand how to use this plugin.
My starting point is a comment I made at the same time as creating this issue:
ome/omero-parade#47 (comment)
which seems to have been working then.

To reproduce, I created a 9-well plate using Dataset_To_Plate script and created a csv:

Well, Drug, Concentration, Cell Count, Percent Mitotic
A1, DMSO, 10.1, 10, 25.4
A2, DMSO, 0.1, 1000, 2.54
A3, DMSO, 5.5, 550, 4
B1, Monastrol, 12.3, 50, 44.43
B2, Drug3, 1.1, 1, 15.4
B3, Water, 20.1, 44, 12.3
C1, Acid, 15.1, 20, 25.4
C2, DrugX, 4.44, 10, 35.4
C3, XYZ, 0.001, 303, 45.4

and run like this

python /path/to/site-packages/omero_metadata/populate.py -s localhost -p 4064 -u will -w password Plate:101 ~/Desktop/plate.csv 

I get this output for EACH row in the csv (9 rows)

INFO:omero_metadata.populate:Missing image name column, skipping.
INFO:omero_metadata.populate:Missing plate name column, skipping.

Followed by stacktrace "Unable to create table: %s" % DEFAULT_TABLE_NAME) etc.

So, something seems to have changed since I last tried running this script.
Even though I am providing a csv with Well A1 etc.

Working my way through the source code in populate.py it seems that def post_process() is called once for each row, and it builds the columns_by_name dict by iterating through the columns again for each row.

At this point I have no understanding of what the script is trying to do or how to use it.

[will-moore]

If I print out the columns_by_name each time it is created for each row, I see it includes:

'well': object #0 (::omero::grid::WellColumn)
{
    name = Well
    description = 
    values = 
    {
        [0] = 101
    }
}

where e.g. 108 is the ID of the Well referred to by A1.

Although there are no columns for Well Name, printing out the well_name_column gives

object #0 (::omero::grid::StringColumn)
{
    name = Well Name
    description = 
    size = 2
    values = 
    {
    }
}

[dominikl]

I think whoever wrote this plugin or knows what the code does, should get back and add at least basic documentation (what a method does, what parameter it expects and what it returns). At least for me, not being a Python guru, it is basically unmaintainable like that.

[will-moore]

@pwalczysko You've had some success running "populate metadata" plugin recently. Can you share what you did to get it working?

[pwalczysko]

@will-moore https://docs.openmicroscopy.org/internal/testing_scenarios/BulkAnnotations.html is the basics - Testing scenarios :)

[will-moore]

OK, thanks. My bad. Testing locally I had forgotten that I'm now on a laptop that doesn't have pyTables installed! I assumed the problem was related to the INFO output above.

[pwalczysko]

Testing locally I had forgotten that I'm now on a laptop that doesn't have pyTables installed! I

No problem, same here. But you can play with outreach if you will.

[manics]

It's 8½ years old! ome/openmicroscopy@876841f

[will-moore]

PR opened at #28
to indicate the list of subcommands and how to run the plugin, as well as detailed usage of populate metadata for csv. More can be added later but this will do for now.