Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding spec_03 #2

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Adding spec_03 #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions spec_03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
- Spec: 3
- Title: Methods on children of figures
- Version: 0.1
- Last-Modified: 2019-07-19
- Authors: [Jon Mease]([email protected]),
[Julia Signell]([email protected]),
- Status: Active
- Type: Standards
- Content-Type: text/markdown
- Created: 2019-07-19

## Abstract
This spec describes a proposed shared API for accessing objects within the figure hierarchy from various plotting libraries.

This spec uses **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animations that may or may not be considered a "plot" with axes, ticks, and so on.

When referring to parts of a figure (such as axes and ticks) we'll use the term: **child**.

When detailing a method, this spec uses FIGURE to refer to any specific figure object and LIBRARY to refer to any specific visualization library, and CHILD to refer to the child of a figure.

## If a method doesn't make sense
If a given operation doesn't make sense for that library, then it can satisfy the spec by simply having that method return a message to that effect ("Unsupported: LIBRARY does not provide JSON output").

## Accessing root figure
Every child should know what figure it belongs to.

### Proposal
Every object in the figure hierarchy should have a `.root` property that returns the top-level parent figure. A deeply nested child object would not return its immediate parent, but the highest-level parent it is aware of (which may be its parent, grandparent, great-grandparent, etc., depending on how deeply it is nested). If the object doesn't belong to a figure then it should return `None`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought I posted this in the old PR, but can't find it now. Is it possible that a child has multiple parents? A data element that is shown in two or more "views"? Should this be allowed? If so, should .root be a list?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is a "view" equivalent to a figure? Semantically it seems that you should be able to view the same figure over and over again.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm good question. Forgive me if I'm confusing too many out of scope topics, but a Figure could have multiple axes (sub-axes), and these could potentially be looking at the same "thing". You could also have two figures (ex. two separate GUI windows) that are displaying the same "thing". If the library supports sharing drawn elements in this way then a child could have multiple parents and therefore multiple root Figures.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have been thinking about this in terms of a figure component (something like a colorbar). I don't imagine data belonging to a figure in the same way. Do you have the concept of a figure component that is in two different figure objects (as opposed to two different views of the same figure)?

It doesn't seem unreasonable to me that such a thing might exist. I just want to be positive that it does, before changing the root to return a list. Lists that almost always have a length of one drive me crazy :)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So if I think in terms of vispy, my answer is a little weird. Vispy can structure something as two "views" of a single "graph" of visual elements/components. These "views" can have cameras attached to them so you can have one view that you can pan/zoom in 2D space and another view that you can rotate around in 3D space or maybe another that is static. At least this is the idea. I have never actually done this in my own work, but the logic is there.

When vispy was first being developed it also allowed for these visual elements/components to have multiple parents. So you could have two "graphs" of visual/elements with any number of the elements being shared between the graphs or not shared. This functionality was dropped at some point because it made other features harder to implement, but there are still example scripts sitting in vispy's repository that try to take advantage of this.

So the usual case (99%) is that you have one graph with one root. That doesn't mean you couldn't have more. I could also see someone arguing that maybe the data is shared between a multi-figure setup, but the visual component representing that data is not shared. This is an implementation detail though.

I'm not sure it is worth it to worry about the complexities of this right now. That said, if handling a list of a single element (I hear you, it is annoying) doesn't make things too hard then maybe it is good to future proof?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given the discussion above and the earlier one about these topics in PR #1, I think spec_03 does not represent universally agreed upon, broadly useful functionality in the same way 02 and 01 do. So I vote against including 03 in the spec; it seems like it opens up more problems than it solves.


> #### What currently exists
> plotly calls these "graph objects" and returns them on the `figure` property.