Objective: Use Cytoscape v10 Export Image calls available in CyREST (e.g., /v1/commands/view/export jpg) instead of existing /v1/commands/view/export. The new functions have adequate zooming and have additional parameters that control image creation.
Discussion: The two choices I see are to
1) invent new functions (e.g., export_image_jpg()) that call new CyREST functions and have parameters specific only to the associated format
2) keep the existing function (i.e., export_image()) and add parameters available for new CyREST functions
Personally, I'd prefer new functions (#1), but that means creating 5 new functions and deprecating one function. This means that existing callers would have to change (because of the deprecation) even if they were using only a minimal parameter list. Additionally, adding 5 new functions could well mean adding corresponding notebook_export_show_image() variants, too. This is geometric expansion is unattractive.
2 is attractive because users of minimal export_image() calls don't need to change, but the list of parameters would need to be expanded, and we would have to document which parameters are accepted for which formats, and which parameters are deprecated.
The deprecation strategy for either choice is a bit complicated.
For #1, there are choices ... roughly, export_image() would need to show a console message and eventually be removed (in the distant future). But the new functions would need to detect the Cytoscape version and call export_image() for versions prior to v10 ... and not show the deprecation message.
For #2, there are choices ... roughly, for Cytoscape v10 and beyond, if old parameters are present (but not new parameters), a deprecation message would be shown on the console and /v1/commands/view/export would be called. If new parameters are present (but not old parameters), the new CyREST calls would be used. If new parameters and old parameters are present, an exception would be thrown. The default behavior (e.g., for just a Zoom parameter) would be to call the new CyREST functions.
For pre-v10, if new parameters are present, an exception would be thrown.
Conclusion: Considering the function proliferation in #1, it seems preferable to choose #2, where parameters are deprecated, but not functions themselves. This would result in some complex coding in export_image() and some extra parameters in notebook_export_show_image(), but would create the least trauma for clients using simple export_image() calls and avoid a geometrically expanding name space.
export_image() # For pre-v10, use View Export. For v10, use View Export PNG with zoom=100$$$export_image(resolution=600) # for pre-v10, use View Export. For v10, show deprecation message and use View Export. $$$$export_image(zoom=200) # for pre-v10, use View Export with zoom=200. For v10, use View Export PNG with zoom=200. $$$$$export_image(hide_labels=True)# for pre-v10, throw exception. For v10, use View Export PNG.
export_image(pageSize="Folio")# for pre-v10, throw exception. For v10, throw exception.
export_image(units="pixels", zoom=200) # for pre-v10, use View Export. For v10, show deprecation message and use View Export.
export_image(units="pixels", hide_labels=True)# for pre-v10, throw exception. For v10, throw exception.
$$$ Calling View Export PNG could produce a different image than View Export if A) the image generation in Cytoscape is different or B) callers in pre-v10 rely on the Tunable behavior of using the last zoom value. I propose that using zoom=100 as a default zoom produces more consistent results, and I assert that few/any users rely on the Tunable behavior. This is a risk worth discussion.
$$$$ The resolution= parameter is invalid for the PNG format, but CyREST doesn't throw an error. The resolution= parameter makes it clear that the View Export should be used, even for Cytoscape v10.
$$$$$ We choose to call the new CyREST functions by default, and this could result in a different image if the Cytoscape code for View Export is different than the View Export PNG code. This is a risk worth discussion.
Objective: Use Cytoscape v10 Export Image calls available in CyREST (e.g.,
/v1/commands/view/export jpg) instead of existing/v1/commands/view/export. The new functions have adequate zooming and have additional parameters that control image creation.Discussion: The two choices I see are to
1) invent new functions (e.g.,
export_image_jpg()) that call new CyREST functions and have parameters specific only to the associated format2) keep the existing function (i.e.,
export_image()) and add parameters available for new CyREST functionsPersonally, I'd prefer new functions (#1), but that means creating 5 new functions and deprecating one function. This means that existing callers would have to change (because of the deprecation) even if they were using only a minimal parameter list. Additionally, adding 5 new functions could well mean adding corresponding
notebook_export_show_image()variants, too. This is geometric expansion is unattractive.2 is attractive because users of minimal
export_image()calls don't need to change, but the list of parameters would need to be expanded, and we would have to document which parameters are accepted for which formats, and which parameters are deprecated.The deprecation strategy for either choice is a bit complicated.
For #1, there are choices ... roughly,
export_image()would need to show a console message and eventually be removed (in the distant future). But the new functions would need to detect the Cytoscape version and callexport_image()for versions prior to v10 ... and not show the deprecation message.For #2, there are choices ... roughly, for Cytoscape v10 and beyond, if old parameters are present (but not new parameters), a deprecation message would be shown on the console and
/v1/commands/view/exportwould be called. If new parameters are present (but not old parameters), the new CyREST calls would be used. If new parameters and old parameters are present, an exception would be thrown. The default behavior (e.g., for just a Zoom parameter) would be to call the new CyREST functions.For pre-v10, if new parameters are present, an exception would be thrown.
Conclusion: Considering the function proliferation in #1, it seems preferable to choose #2, where parameters are deprecated, but not functions themselves. This would result in some complex coding in
export_image()and some extra parameters innotebook_export_show_image(), but would create the least trauma for clients using simpleexport_image()calls and avoid a geometrically expanding name space._Existing
export_image()signature:_def export_image(filename=None, type='PNG', resolution=None, units=None, height=None, width=None, zoom=None, network=None, base_url=DEFAULT_BASE_URL, *, overwrite_file=False):_Proposed
export_image()signature:_def export_image(filename=None, type='PNG', resolution=None, units=None, height=None, width=None, zoom=None, network=None, base_url=DEFAULT_BASE_URL, *, overwrite_file=False, all_graphics_details=None, hide_labels=None, transparent_background=None, export_text_as_font=None, orientation=None, page_size=None):Examples:
export_image()# For pre-v10, useView Export. For v10, useView Export PNGwithzoom=100$$$export_image(resolution=600)# for pre-v10, useView Export. For v10, show deprecation message and useView Export. $$$$export_image(zoom=200)# for pre-v10, useView Exportwithzoom=200. For v10, useView Export PNGwithzoom=200. $$$$$export_image(hide_labels=True)# for pre-v10, throw exception. For v10, useView Export PNG.export_image(pageSize="Folio")# for pre-v10, throw exception. For v10, throw exception.export_image(units="pixels", zoom=200)# for pre-v10, use View Export. For v10, show deprecation message and useView Export.export_image(units="pixels", hide_labels=True)# for pre-v10, throw exception. For v10, throw exception.$$$ Calling
View Export PNGcould produce a different image thanView Exportif A) the image generation in Cytoscape is different or B) callers in pre-v10 rely on the Tunable behavior of using the last zoom value. I propose that usingzoom=100as a default zoom produces more consistent results, and I assert that few/any users rely on the Tunable behavior. This is a risk worth discussion.$$$$ The
resolution=parameter is invalid for the PNG format, but CyREST doesn't throw an error. Theresolution=parameter makes it clear that theView Exportshould be used, even for Cytoscape v10.$$$$$ We choose to call the new CyREST functions by default, and this could result in a different image if the Cytoscape code for
View Exportis different than theView Export PNGcode. This is a risk worth discussion.