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.

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

Starting specs 1 and 2 #1

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
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
7 changes: 5 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,2 +1,5 @@
# spec
Minimal shared API spec
# Shared specifications for Python Visualization

This repo will store any specifications that arise as well as any build and testing code that is determined to be useful for managing and verifying the use of specs.

Every spec will have a version and target a specific section of the library API.
46 changes: 46 additions & 0 deletions spec_01.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
- Spec: 1
- Title: Methods on libraries
- Version: 0.1
- Last-Modified: 2019-07-19
- Authors: [James Bednar](),
[Julia Signell]([email protected]),
[Jake Vanderplas]()
- Status: Active
- Type: Standards
- Content-Type: text/markdown
- Created: 2019-07-19

## Abstract
This spec describes a proposed shared API for enabling plotting libraries.
jsignell marked this conversation as resolved.
Show resolved Hide resolved

This spec uses LIBRARY to refer to any specific visualization library.

## 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 ("JSON support not available in LIBRARY").
jsignell marked this conversation as resolved.
Show resolved Hide resolved

## `.__spec_version__()` method
Calling `.__spec_version__()` on the library should return a list of the specs that the library complies with. It should include the version of the spec that is being used.

```python
>>> LIBRARY.__spec_version__()
Copy link
Collaborator

Choose a reason for hiding this comment

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

Could this be made more explicit? Something like __pyviz_version__ or __pyviz_plot_version__ (oh that gets long fast)? Main concerns are spec being too generic and future specifications by this group (plotting versus maps versus jupyter widget interface versus something else). Maybe they are all in one large specification, but want to point it out at least.

Copy link
Member Author

Choose a reason for hiding this comment

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

maybe __pyviz_spec_version__?

Copy link
Member

Choose a reason for hiding this comment

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

Sounds good to me. Good point, @djhoese .

Copy link
Member

Choose a reason for hiding this comment

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

Or maybe just __pyviz_spec__.

{1: 0.1, 2: 0.1}
```

## Enable output from library
Each library should provide a uniform way to enable itself in jupyter notebook & jupyterlab.

> #### What currently exists
> - matplotlib has `%matplotlib inline`
> - bokeh has `bokeh.output_notebook()`
> - altair has `alt.renderers.enable('notebook')`
jsignell marked this conversation as resolved.
Show resolved Hide resolved

### Proposal 1 : magics
Every library should define something like `%enable_LIBRARY`
jsignell marked this conversation as resolved.
Show resolved Hide resolved

### Proposal 2: method
jsignell marked this conversation as resolved.
Show resolved Hide resolved
Provide an `enable()` method on the library that can take an optional `output` kwarg, but provides a sensible default.
jsignell marked this conversation as resolved.
Show resolved Hide resolved

`LIBRARY.enable()` == `LIBRARY.enable(output='notebook')`

#### Context
This might be preferred over magics because some tools need a specification that is usable both within and outside of jupyter. We can always add special cases to deal with magics, but prefer just to have a normal Python call that can register things with Jupyter if it's available but doesn't otherwise cause syntax errors (if not skipped) or missing functionality (if skipped) outside of Jupyter/IPython.
jsignell marked this conversation as resolved.
Show resolved Hide resolved
86 changes: 86 additions & 0 deletions spec_02.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
- Spec: 2
- Title: Methods on figure objects
- Version: 0.1
- Last-Modified: 2019-07-19
- Authors: [James Bednar](),
[David Hoese](),
[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 from various plotting libraries.
jsignell marked this conversation as resolved.
Show resolved Hide resolved

In this notebook we will use **figure** to refer to any object that has a visible representation but which can also be saved, exported, etc. This includes generic visualizations or animation that may or may not be a "plot" (axes, ticks, etc)?
jsignell marked this conversation as resolved.
Show resolved Hide resolved

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

## 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 ("JSON support not available in LIBRARY").
jsignell marked this conversation as resolved.
Show resolved Hide resolved

## Jupyter methods
Every library that supports rendering in Jupyter should support the various IPython rich display methods, i.e. `repr_html`, `repr_png`, `_ipython_display_`.
jsignell marked this conversation as resolved.
Show resolved Hide resolved

## `.show()`
Every figure should have the ability to render itself.

### Proposal
1) The top-level figure class has a `.show()` method that can be called without arguments to display the figure as a side-effect.
jsignell marked this conversation as resolved.
Show resolved Hide resolved
2) The optional `renderer` kwarg can be used to override the current default renderer. e.g.:
- `FIGURE.show(renderer='png')` to display the figure as a static png image/
- `FIGURE.show(renderer='browser')` to display the figure in a browser tab. This works in non-jupyter/IPython contexts.
Copy link
Collaborator

Choose a reason for hiding this comment

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

What level of interactivity should be required from this show interface? And should there be a defined list of "preferred" rendering options that a library should support with defined names (ex. so one library doesn't use jpg while another uses jpeg).

Does browser mean interactive javascript based display? Or could it mean open a browser tab and display the PNG version of this figure? Does the browser rendering open a new tab if in a jupyter notebook environment or does it display it inline in the notebook cell's output?

Copy link
Member

Choose a reason for hiding this comment

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

I would argue for a minimal standard for show that can be met by all libraries, and thus would not assume any interactivity or JavaScript.

Copy link
Member Author

Choose a reason for hiding this comment

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

should this maybe be output instead of renderer so that it can match .save()?

Copy link
Member Author

Choose a reason for hiding this comment

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

should the output option just be 'html' then and a browser tab is implicitly where html would be displayed?

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 think that makes sense.


## `.save()` method
Every figure should have the knowledge of how to export itself to a file on disk.

> #### What currently exists
> - matplotlib has `.savefig` which saves the current figure, with options `fname` and `format` among others.
> - plotly has `write_*` methods which write the figure to a `file` (or writable object) and return `None`.
> - bokeh has top level `export_*` methods for each output format as well as `save` (only outputs html) which both take a FIGURE as the arg.

### Proposal
Figures should have `FIGURE.save()` method for exporting.

There are several kwargs that `save` should include:

1) `file`: should be a file object or optionally a path to a file. If a file path is used rather than a file object and that is not supported, the library should raise a sensible error. Can default to some user configured value.
jsignell marked this conversation as resolved.
Show resolved Hide resolved
2) `output`: should be a file format that the figure can be exported to i.e. `'png'`, `'json'`, `'html'`. The library should set a default output and/or allow the user to configure the output. For instance matplotlib does:
jsignell marked this conversation as resolved.
Show resolved Hide resolved
> If format is not set, then the output format is inferred from the extension of `fname`, if any, and from `rcParams["savefig.format"]` otherwise. If `format` is set, it determines the output format.
>
>from: [matplotlib.pyplot.savefig](https://matplotlib.org/3.1.1/api/_as_gen/matplotlib.pyplot.savefig.html)

**NOTE**: These kwargs are deliberately selected to avoid builtins in python 3 which precludes `format`, but no longer precludes `file`.

After these two, save can have any additional kwargs needed.

#### What to return
`FIGURE.save()` should return the file path or object that was saved to.

#### Some examples
Save to default location:

```python
FIGURE.save()
```

Save to a particular location:

```python
with open('/path/to/output.html', 'w') as file:
FIGURE.save(file)
```

is equivalent to

```python
FIGURE.save(file='/path/to/output.html')
```

is equivalent to

```python
FIGURE.save('/path/to/output.html', output='html')
```
31 changes: 31 additions & 0 deletions spec_03.md
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 animation that may or may not be a "plot" (axes, ticks, etc)?
jsignell marked this conversation as resolved.
Show resolved Hide resolved

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 ("JSON support not available in LIBRARY").
jsignell marked this conversation as resolved.
Show resolved Hide resolved

## 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 parent figure, or if deeply nested, the grand or great-grandparent figure. If the object doesn't belong to a figure then it should return `None`.
jsignell marked this conversation as resolved.
Show resolved Hide resolved

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