Add labels to the export dialog & exported image

[Robert Leach]

USE CASE: WHAT DO YOU WANT TO DO?

Export with labels

STEPS TO REPRODUCE AN ISSUE (OR TRIGGER A NEW FEATURE)

1. command-e

CURRENT BEHAVIOR

Labels are not included in exported images

EXPECTED BEHAVIOR

This is based on the requirements in issue #292, but I have simplified them a bit based on my experience with Java TreeView 2...

1. The currently displayed label type (and their formatting & font) in the main window are the labels that will be exported (including concatenated label types if that's what's displayed)
2. All labels of the currently displayed region will be exported by default unless the user explicitly selects "Selected" or "No"
3. If no labels are selected for export, no space is created for them in the exported image
4. Note, adding labels significantly increases the size of image formats such as PNG, so we will have to deal with our size limitation issues (in BB issue #383). Need to support 6kx6k.
5. If an export file will be too big with labels, disable the Yes & Selected label options & select none. Add a tool tip to explain why they are disabled.
6. Selected labels will be highlighted if show selections is checked.
7. Ideally, if a few disparate labels are selected, resolution can be ramped down. This is optional, because it's more difficult.

Given the risen complexity of the export dialog by adding this feature, and the desire to keep options simple/clean stated in other issues, I have arranged "sections" of the export dialog and renamed "Matrix:" to "Region:" so that I could use "Matrix" as a heading for the section.

Mockup (based on current state of master 11/16/2016):

DEVELOPERS ONLY SECTION

SUGGESTED CHANGE (Pseudocode optional)

Regarding updating the enabled & selected states of the components of the export interface, this is a summary of the hierarchical rules. Note, since issue #409, the very bringing up of the export dialog will have to be checked to see if a region small enough to export exists. If no valid export can be made, a warning dialog should come up suggesting the user select a region to export (since the matrix is too big.

Determine which formats are enabled (upon initialization):
    Using minimum options:
        Region: selection or visible (whichever is valid & smallest)
        Aspect: 1:1
        Row labels: No
        Col Labels: No

Determine which Regions are enabled:
    Using current options:
        Format
    Using minimum options:
        Aspect: 1:1
        Row labels: No
        Col Labels: No

Determine which aspects are enabled:
    Using current options:
        Format
        Region
    Using minimum options:
        Row labels: No
        Col Labels: No

Determine which row label options are enabled:
    Using current options:
        Format
        Region
        Aspect
    Using minimum options:
        Col Labels: No

Determine which row label options are selected:
    Using current options:
        Format
        Region
        Aspect
        Col Labels

Determine which col label options are enabled:
    Using current options:
        Format
        Region
        Aspect
    Using minimum options:
        Row Labels: No

Determine which row label options are selected:
    Using current options:
        Format
        Region
        Aspect
        Row Labels

FILES AFFECTED (where the changes will be implemented) - developers only

unknown

LEVEL OF EFFORT - developers only

major

COMMENTS

Various options for the label radio buttons were explored & it was decided over Slack that Yes, No, and Selected were the most intuitive and understandable options and did not require any complex code for manipulating selections to make them valid given the exported region.

[Anastasia Baryshnikova]

Is this a duplicate of #439?

[Robert Leach]

Whoops. Yeah, guess so. I'd just finished reviewing issues that I started rummaging through yesterday. Missed it when you added this.

[Robert Leach]

Updated the mockup image because there were still a few extras in it that we decided not to implement.

[Robert Leach]

Issue #439 was marked as a duplicate of this issue.

[Anastasia Baryshnikova]

It's not clear from the mockup what are the 2 lists of labels: are they the labels themselves or the names of label types? For example, let's say I have a matrix with 2 row headers (ORF and GENENAME) and 2 column headers (ORF and GENENAME). I think the export interface should show "ORF" and "GENENAME" as options, not the list of all orfs and all genenames..

[Robert Leach]

They are labels. Default would be to export all labels. The label type would be the one that is visible in the interface. This style of presenting label options allow someone to export just one label or any number of labels that they want to call attention to. Of course we could simplify it and not allow anything other than all labels or no labels, like a simple checkbox. I don't have any problem with that. However, note that 2 adjacent labels ramps up the required resolution and thus file size in order for the labels to be legible in an image format like PNG. Disparate labels would significantly decrease the resolution requirements and file size.

[Anastasia Baryshnikova]

I don't think we need to give the option to export 1 label or a few select labels. If you're exporting a matrix (the whole thing, the visible part or the selection), you can include all of its labels or none of them. Anything else would be too confusing, I think, and unexpected. I'm ok with exporting only 1 label type, the one that's currently visible in the interface.

[Robert Leach]

I'm fine with that, as long as it's understood that at certain matrix sizes, labels will be disabled because the bufferedImage class has a size limit. Right now, we have 3 pixels per row and column for a 6k by 6k matrix. That's about the largest that we can do, which is insufficient for text. This applies to image formats only.

We do have another bitbucket issue to address the size limitation, but until that's addressed, there's only so much we can do.

[Anastasia Baryshnikova]

yep, I think that's totally expected that you can't export labels for very large matrices. I think the main use case for this feature is for making figures where you can point to specific row/column, so the matrix won't be very large there.

[Robert Leach]

Sure, and at some point, if we support annotations, we may be able to highlight those that they want to call attention to (other than selected labels).

[Anastasia Baryshnikova]

Another suggestion came up from conversation with a user: exporting just tree + labels (without data).

[Robert Leach]

Removing milestone: Import/export data (automated comment)

[Robert Leach]

Organizing requirements first, but I'm taking this issue for work now.

[Robert Leach]

Edited details of this issue to reflect decisions made in the comments and to make adjustments in the layout of the dialog mockup in anticipation of previously stated desires that it have a clean/simple feel.

Previous mockup (based on previous state of #292):

@abarysh - could you provide your feedback on the new mockup I've proposed embedded in the issue description (i.e. not the mockup that I've preserved in this comment)?

[Anastasia Baryshnikova]

@hepcat72 The new mockup looks ok.

[Robert Leach]

Ah, wait. There are a number of problems with the mockup. (Things are always clearer in the morning.) If the user is zoomed in and they elect to export the entire matrix, "visible" is difficult to interpret and might yield results unexpected by the user... (or might not) BUT, there's no way to select to export "all" labels in that instance (unless you interpret "visible" to mean what's visible in the exported image as opposed to what's visible in the IMV). Assuming 2 different contexts in the same interface (or any other TreeView interface) is confusing.

So perhaps the options should be:

• All
• Visible
• Selected
• None

And "All" should be grayed out if "All" is not the selected region to export. (Likewise, "Selected" should be grayed out in the provided example.)

Note, adding another option ("All") would widen the window. Alternatively, I could leave off "None" by making the options checkboxes instead of radio buttons and then use form validations to do thing like (for example):

• If the matrix radio button changes, the labels would automatically change to match (unless "None" or "Selected" is the selected label option)
• If the user selects "All" labels or "None", the other checkboxes would de-select
• Actually code would have to be used to make them act like radio buttons in all cases except when a checkbox is deselected (which radio buttons can't do).

Now that I think about it, I can't say that I like this design. It's probably better to simply allow the window to be a tad wider. However, it makes me realize that there are other issues:

• What if the user selects "Selected" labels, but the selected matrix region is "Visible" AND there are selected labels for tiles that are not in view?
  1. Probably, the "Selected" option should be grayed out and deselected when "Visible" region is selected AND when no selections are currently visible
  2. I think it's reasonable to only include selected labels (if that's the chosen option) when they are a part of the exported region. Furthermore, I don't think the user needs to be warned that selections exist outside of the exported region. Does anyone disagree with this? @abarysh ?
• If the user selects the exported region to be "Selection" and the selections are disjoint, selecting to export the "Visible" labels should be allowed and result in the unselected rows/columns to be labeled. Furthermore, I don't think the user needs to be warned that visible labels exist outside the exported "Selection" region that will not be included in the exported image.
• If there's only 1 contiguous selection and the exported region is selected to be "Selection", the "Visible" labels option should be grayed out.

Can anyone think of a simpler logic or a simpler way to present options that will not conflict with the exported region? Perhaps simpler options would be:

• Full exported region
• Selected
• None

There are 2 problems with this:

• There's no way to export the entire matrix and only export the labels in the visible area, though this seems like a very minor limitation to me and could be circumvented by canceling and selecting the visible region only
• I can't think of a succinct way of saying "Full exported region". Do you think "All" would be understood by the user to only include those labels in the exported region?

[Robert Leach]

I'll go with these options:

• All (in Region)
• Selected
• None

Default will be "All...". Selected will be disabled if there's no selection or if no selection is visible in the exported region. It will be assumed that the user understands that any label selected outside the exported region (e.g. User selects "Visible" export matrix region and "Selected" labels) will not be included in the output image.

[Robert Leach]

Edited the mockup and requirements to reflect agreed upon changes in the comments both below and over slack.

Previous mockup:

[Robert Leach]

I added some rules to the SUGGESTED CHANGE section to act as a guide in including the labels in the logic for enable/disabled and selected/unselected.

[Robert Leach]

Resolved in PR issue443.

[Robert Leach]

Issue #532 was marked as a duplicate of this issue.