Package: omero2pandas
omero2pandasA convenience package to download data from OMERO.tables into Pandas dataframes.Installationomero2pandas can be installed with pip on Python 3.6+:pip install omero2pandasomero2pandas also supports authentication using tokens generated byomero-user-token.
Compatible versions can be installed as follows:pip install omero2pandas[token]See theomero-user-token documentationfor more information.Usageimportomero2pandasdf=omero2pandas.read_table(file_id=402)df.head()Tables can be referenced based on their OriginalFile's ID or their Annotation's ID.
These can be easily obtained by hovering over the relevant table in OMERO.web, which shows a tooltip with these IDs.To avoid loading data directly into a dataframe, you can also download directly into a CSV:importomero2pandasomero2pandas.download_table("/path/to/output.csv",file_id=2,chunk_size=1000)chunk_sizecan be specified when both reading and downloading tables. It determines
how many rows are loaded from the server in a single operation.Supplying credentialsMultiple modes of connecting to OMERO are supported. If you're already familiar with omero-py, you can supply a premade client:importomeroimportomero2pandasmy_client=omero.client(host="myserver",port=4064)df=omero2pandas.read_table(file_id=402,omero_connector=my_client)df.head()Alternatively, your connection and login details can be provided via arguments:importomero2pandasdf=omero2pandas.read_table(file_id=402,server="omero.mysite.com",port=4064,username="myuser",password="mypass")df.head()If you haveomero_user_tokeninstalled, an existing token will be automatically detected and used to connect:importomero2pandasdf=omero2pandas.read_table(file_id=402)df.head()You can also generate the connection object separately using the built-in wrapper:importomero2pandasconnector=omero2pandas.connect_to_omero(server="myserver",port=4064)# User will be prompted for any missing connection info.df=omero2pandas.read_table(file_id=402,omero_connector=connector)df.head()When prompting for missing connection information, the package automatically detects whether
omero2pandas is running in a Jupyter environment. If so, you'll get a login widget to complete details.
Otherwise a CLI interface will be provided.This behaviour can be disabled by supplyinginteractive=Falseto the connect call.Reading dataSeveral utility methods are provided for working with OMERO.tables. These all support the full range of connection modes.Fetch the names of the columns in a table:importomero2pandascolumns=omero2pandas.get_table_columns(annotation_id=142)# Returns a list of column namesFetch the dimensions of a table:importomero2pandasnum_rows,num_cols=omero2pandas.get_table_size(annotation_id=12)# Returns a tuple containing row and column count.You can read out specific rows and/or columnsimportomero2pandasmy_dataframe=omero2pandas.read_table(file_id=10,column_names=['object','intensity'],rows=range(0,100,10))my_dataframe.head()# Returns object and intensity columns for every 10th row in the tableReturned dataframes also come with a pandas index column, representing the original row numbers from the OMERO.table.Writing dataPandas dataframes can also be written back as new OMERO.tables.
N.b. It is currently not possible to modify a table on the server.Connection handling works just as it does with downloading, you can
provide credentials, a token or a connection object.To upload data, the user needs to specify which OMERO object the table
will be associated with. To do this, the third and fourth arguments
should be the object ID and object type. Supported objects are Dataset,
Well, Plate, Project, Screen and Image.importpandasimportomero2pandasmy_data=pandas.read_csv("/path/to/my_data.csv")ann_id=omero2pandas.upload_table(my_data,"Name for table",142,"Image")# Returns the annotation ID of the uploaded file objectOnce uploaded, the table will be accessible on OMERO.web under the file
annotations panel of the parent object. Using unique table names is advised.Advanced UsageThis package also contains utility functions for managing an OMERO connection.omero2pandas.connect_to_omero()takes many of the arguments from the other functions and returns anOMEROConnectionobject.TheOMEROConnectionhandles your OMERO login and session, cleaning everything up automatically on exit. This has some accessory methods to access useful API calls:importomero2pandasconnector=omero2pandas.OMEROConnection()connector.connect()client=connector.get_client()blitz=connector.get_gateway()When a client is active within theOMEROConnectionobject, calls to this wrapper class will also be forwarded directly to the client object.OMEROConnection objects can also be used as a context manager:importomero2pandaswithomero2pandas.OMEROConnection(server='my.server',port=4064,username='test.user',)asconnector:blitz=connector.get_gateway()image=blitz.getObject('Image',id=100)# Continue using the standard OMERO API.The context manager will handle session creation and cleanup automatically.Querying tablesYou can also supplyPyTables condition syntaxto theread_tableanddownload_tablefunctions.
Returned tables will only include rows which pass this filter.Basic syntaxSelect rows representing objects with area greater than 20:omero2pandas.read_table(file_id=10,query='(area>20)')Multiple conditionsSelect rows representing objects with an even ID number lower than 50:omero2pandas.read_table(file_id=10,query='(id%2==0) & (id<50)')Complex conditionsSelect rows representing objects which originated from an ROI named 'Nucleus':omero2pandas.read_table(file_id=10,query='x!="Nucleus"',variables={'x':omero.rtypes.rstring('Roi Name')})N.b. Column names containing spaces aren't supported by the native syntax, but can be supplied as variables which are provided by thevariablesparameter.The variables map needs to be a dictionary mapping string variables toOMERO rtypesobjects rather than raw Python objects.
These should match the relevant column type. Mapped variables are substituted into the query during processing.Avariablesmap usually isn't needed for simple queries. The basic condition string should automatically get converted to a meaningful type, but when this fails
replacing tricky elements with a variable may help.