'Animate' method arguments poor documentation

[minerharry]

Plotly's animations are very cool and smooth, especially compared to matplotlib which I usually use for python graphing. However, the details of 'method':'animate', how it pulls from figure.frames, and what the arguments to the method actually are (or what the method itself actually is) is incredibly opaque, especially from the python side where the js backend is hard to get to and parse. I should mention, however, that this issue is not limited to the python docs; going to javascript, R, etc and searching animate or method animate or animate arguments all turn up empty (or, more often, to the 'method':'animate' options in buttons and sliders). After a lot of searching, I eventually found* this page from the plotly.js repo, which helps immensely and matches with the attributes seen in most of the examples - except for the gapminder example, in which the slider is able to index a specific frame of the animation by specifying 'args':[year]. This has no analogue in the plotly.js file, and it's very unclear what such a key indexing could even be doing, given the fact that it's not an integer and thus couldn't be indexing into, for example, the frames array of the figure. After some trial and error, I eventually figured out that it seemed to be picking the frame from the "name" attribute in the framedict of each frame passed to figure.frames. This is very useful, is critical to doing more complex animations, and should be documented.

*from plotly python api -> figure page -> random link.

More generally, the whole 'method' documentation is confusing and has a lot of dead ends. In most documentation areas I see (including on the rest of the internet!), the explanation of 'method' is that it calls an underlying plotly function [somewhere] and passes the arguments specified in 'args' depending on the function. However, in none of these areas does it say what the arguments would be for the different methods, there are very brief descriptions of what the methods do, and most importantly no links to further information about the methods themselves. As mentioned, the only way I found the (incomplete) description of the animate args was from the 'animation_opts' argument to figure.to_html, for crying out loud!

What I'd like to see is a page with a comprehensive description of what the various 'method's do, the full specification of their arguments, links to where the functions are if possible (like, for example, how do they get access to the frame dicts? are the figures passed as arguments, or are they methods of the figure? Can I call one of these methods myself?), and links to that description from the many places that reference 'method' but give no description. (Off the top of my head, I have figure, button, and slider pages in all languages, and the plotly animation reference page(s)).

[johnforestolson]

Big +1. Thanks to minerharry for the detailed problem description, and the link to actually useful information.

[Jerry-Ma]

Hi,
I was searching for animation related documentations and ended up in this tread. I am facing exactly the same issue as described in the OP. It would be great to see it get solved.