search

napari / napari

napari: a fast, interactive, multi-dimensional image viewer for python
https://napari.org
BSD 3-Clause "New" or "Revised" License
2.19k stars 422 forks source link

✨ Terminology in napari #3231

Closed haesleinhuepf closed 2 years ago

haesleinhuepf commented 3 years ago

Overview of design need

I would like to start a discussion about terminology in napari versus other image analysis tools (I mostly refer to ImageJ). I often find myself explaining basic things to end-users, just because things have different / "unusual" names in napari. Examples:

This is problematic as imaging scientists may not find what they search for in the documentation, e.g. searching for lookup table: image

Furthermore, some of the terms are also not consistent within napari: image

Would it make sense to rename some of those terms in the user interface and documentation to ease the life of end-users and in particular beginners?

What level of design is needed? (Choose all that apply)

This section may be updated by the designer / UX researcher working on this issue

Is design a blocker?

If selecting Yes, how much design input is needed to unblock engineering? For example, is a full, final visual design needed, or just a recommendation of which conceptual direction to go?

psobolewskiPhD commented 3 years ago

I'm agnostic on the first and last ones—I didn't/don't find them confusing. Shape is readily understandable and at the moment—correct me if I'm wrong—Shapes by themselves in bare napari don't really do anything other than just being shapes, so you're installing some plugin to leverage them which I think can vary, so the plugin should be the one with docs as to what they're using shapes for.

Keybinding vs. keyboard shortcut I'd say are largely interchangeable? Mac people tend to say keyboard shortcut I think because it's in the OS that way? I guess stricte something like to pan/zoom would be more of a binding than a shortcut. But it's just semantics... I don't know enough about the 2nd and 3rd to comment.

Regarding colormap vs LUT, this one I can comment about since it was one of the first things in napari I wanted to play with (dreamy Christophe Leterrier inverse LUTs 😍). I remember searching the docs just like Robert shows. To me LUT is pretty universal, it's the term in the Leica LAS X software as well. Ironically, once @sofroniewn pointed me to napari colormaps, I found out it was actually super trivial—easier than ImageJ. So if napari is going to use colormap then the docs should definitely include "lookup table (LUT)" so that it's discoverable.

liaprins-czi commented 3 years ago

Thanks again to you both for creating and weighing in on this very helpful issue! I agree with the idea of developing a general "How to name things" guide.

Also linking to another very related heuristic issue: UI terminology #15 and looping in our UX researcher @LCObus for awareness.

liaprins-czi commented 3 years ago

I also like the idea of somehow making the docs searchable for more than just the "napari term". This might be by including alternative terms in the documentation as you suggest or maybe there is another way. Looping in @melissawm who will be lookign at how to structure our docs, in case this is relevant to what you will be working on at any point.

LCObus commented 3 years ago

Great points @haesleinhuepf , thanks for raising them! We definitely don't want to make users learn a new language if the functionality is identical, especially given the understandable activation energy that comes with learning napari after using imageJ. That confusion isn't kind to our users, and the design principle here is called "recognition not recall"- aka dont make your community do more work. That said, there are complimentary products that have different names ("thread" in slack similar to "stream" in zulip). I'm curious if these concepts are also named differently across other platforms or if napari is the outlier :) My recommendation: 1) Identify from core devs the origin of the names- is there a strong opinion about why we differentiate "shapes" from "roi"? are they actually different from the item in imageJ? if no strong opinion, consider reverting. 2) For items that should maintain differentiated terminology, add a "similar to ____" in a terms guide, and define the difference. There should be articulate rationale for the different term to make it useful for users to learn. 3) universal/interchangable names (like keybinding/shortcut) should also be cross referenced, but uniformly in the viewer.

goanpeca commented 3 years ago

Having a glossary would be helpful :)

tlambert03 commented 3 years ago

I'd also suggest that ImageJ not be the only thing which we compare to here.

While there is undoubtedly lots of overlapping functionality, it's not in our mission statement to be the python equivalent of ImageJ. I agree completely that we shouldn't use new terms gratuitously (i.e. "just to be different" or something)... but inasmuch as there is meaningful difference in the objects used between the two platforms, I'm don't feel like we should stretch to force the same terminology. For most of the x = y in the first post, I think x ≈ y is perhaps more accurate...

For example Shapes as implemented in napari actually don't really exist as far as I know in ImageJ (correct me if I'm wrong @haesleinhuepf ... does ImageJ support vectorial representations of objects that could be, for example, exported to SVG?) In that regard, it's more of an illustrator like object. We have discussed adding something like ROIs to napari (and they might use some of the shapes machinery behind the scenes), but we don't really have ROIs just yet.

hook specs aren't exactly the same as plugin types ..., etc...

The exception is "colormaps = LUT": that's a pretty direct equivalence. However, matplotlib uses colormap, and I'd say parity with people's expectations from matplotlib is just as important (if not more) to ImageJ

psobolewskiPhD commented 3 years ago

@LCObus wrote:

  • Identify from core devs the origin of the names- is there a strong opinion about why we differentiate "shapes" from "roi"? are they actually different from the item in imageJ? if no strong opinion, consider reverting.

As a new user, I'd be very wary of such reverts! Napari has been out for some time, people have learned or are learning—and not everyone is coming from ImageJ, which isn't necessarily a pinnacle of UX design either. In this case, the layers model napari uses is fundamentally different from ImageJ and more similar to graphics programs like Illustrator or Photoshop. Changing Shapes to ROIs now? That is something that would confuse someone new or an occasional napari user and not help much a ImageJ user, since they'd just a set a different set of expectations that are not necessarily fulfilled either (without plugins at least). For the new user, docs and tutorials are the better solution, with alternate terminology presented. I think using analogies to other software can be very worthwhile, perhaps even making a dedicated doc (maybe video?) for users coming from ImageJ.

LCObus commented 3 years ago

I agree that potential reverts should be handled with extreme care! my primary recommendation is to audit these important terms to assess differences and ensure there isn't actually any unnecessary additional naming conventions (which was @haesleinhuepf 's original concern, but as @tlambert03 noted, it sounds like there indeed ARE useful differences which would be helpful to note for new users). The goal would be to align any identical terms, then identify and document any "similar to in ___"

haesleinhuepf commented 3 years ago

For example Shapes as implemented in napari actually don't really exist as far as I know in ImageJ (correct me if I'm wrong @haesleinhuepf ... does ImageJ support vectorial representations of objects that could be, for example, exported to SVG?) In that regard, it's more of an illustrator like object. We have discussed adding something like ROIs to napari (and they might use some of the shapes machinery behind the scenes), but we don't really have ROIs just yet.

That's the origin of my colleagues' confusion. In ImageJ, there is plenty of tools to draw shapes very prominently: image ... which serve as ROIs. Those are vector-based structures btw (SVG-like), and the end-user doesn't care. I was using the analogon 'shapes' as ROIs in napari-plot-profile. I'm happy to change it, if there come alternatives, e.g. a ruler.

I agree that potential reverts should be handled with extreme care!

+1, that's why this discussion. :-)

hook specs aren't exactly the same as plugin types ..., etc...

Interesting that you put that link here. https://imagej.net/develop/plugins#plugin-types This sounds to me like exactly the same thing as what napari-developers call hook-specs. But again, end-users don't care. They only see "plugins". I'm mostly concerned about communication with end-users. They typically speak a different language then developers, also in the ImageJ ecosystem btw.

I'd say parity with people's expectations from matplotlib is just as important (if not more) to ImageJ

That depends on the target audience. If napari aims at matplotlib users, I agree.

Maybe, we can start collecting terms (in a glossary like @goanpeca suggested?) and clarify what they mean... E.g. "Different plugin types can be implemented using hook specs" (correct?) We can then later discuss which terms the end-user will be confronted to. I'd hope the end-user doesn't need to see / understand the whole complexity on technical level...

goanpeca commented 3 years ago

In general I would encourage to use more known common names, independent on how things are called in python world. As napari is used by new (non dev) users as a click and point UI tool, and not a programming tool, calling things by their python usual names (matplotlib example by @tlambert03) does not seem to help in this use case.

Similar to how Qt has QDockwidget and we had "add dockwidget" in a menu, which is not very clear, unless you use Qt/PyQt.

If napari aims at matplotlib users, I agree.

I think napari aims to reach users in this order:

  1. non-dev users first (which will probably become THE majority of users eventually)
  2. Then it will aim at power users that will use a console and do more advanced stuff
  3. more advanced users (plugin developers)

I think the documentation should make clear distinctions between these use cases so that the progression of learning is ... progressive :).

User docs

Advanced User docs

Plugin Developer Docs

jni commented 3 years ago

I want to second Talley's concerns here. I agree 100% that we should aim to be internally consistent. I disagree that we should mimic ImageJ. It should be considered an accident of history that napari came out of the bioimaging community, and thus we currently have an overrepresentation of users and developers from that community. We absolutely aim to be a domain-agnostic viewer/platform (it's in our values), so if we want to find common terminology, we should look at that terminology across domains. Re colormap vs LUT, ArcGIS, for example, uses colormap. Tableau uses "quantitative color palette".

Where terminology conflicts, I suggest we try to find a principled way of choosing, one that describes most generally the concept we are trying to convey. Back to colormaps, I dislike the LUT terminology, because colormaps may or may not be based on lookup tables. They might also be a linear interpolation function between two colors, for example. So "colormap" (a function mapping values to colours) is a strictly more general term.

I think @goanpeca's classification of audiences is useful, but I don't see it that clearly. I very much aim for napari to be a "gateway drug" for even non-coding scientists to start to dabble in Python, as they try to record and modify workflows, or customise napari's behaviour. In other words, I think consistency with the Python ecosystem is indeed important, even as our non-coding audience grows, because I'm as interested, if not more interested, in smoothing the user->developer ramp as I am in smoothing the non-user->user ramp.

I think napari aims to reach users in this order:

  • non-dev users first (which will probably become THE majority of users eventually)
  • Then it will aim at power users that will use a console and do more advanced stuff
  • more advanced users (plugin developers)

I am in general nervous about veering too hard in the "we cater primarily to non-dev users" direction. Again, let's not forget the first line in our mission statement: "napari aims to be the multi-dimensional image viewer for Python and to provide GUI access to a plugin ecosystem of image analysis tools for scientists to use in their daily work." "Viewer for Python" and "GUI access to a plugin ecosystem" are equal partners there, and I think they should remain so, particularly right now: we are still in the early days of napari and we still have a lot of growth to capture by catering to the scientific Python community.

Most important for me personally, the whole point of napari was originally to look at things while working in scientific Python. Although I am very happy to see the non-dev community grow, I would be very sad if devs become second class citizens.

I think in general I'd just like to proceed with caution here, and approach this problem with a glossary that explains all our core concepts and links to similar concepts in other software (as @LCObus flags). Except with things like "dock widget" vs "panel" which I think are pretty good substitutions. =) Our terminology should match concepts, not APIs.

melissawm commented 3 years ago

Thank you all for the very helpful discussion - it seems like a glossary would be a good place to start. Initially I thought of suggesting something akin to the NumPy for MATLAB users document (as it is a fairly common case for people to migrate from matlab to NumPy/Python, it may also be the case that people arrive at napari from some other tool) but from @jni 's response above maybe that's not what the community wants.

haesleinhuepf commented 3 years ago

Again, let's not forget the first line in our mission statement: "napari aims to be the multi-dimensional image viewer for Python and to provide GUI access to a plugin ecosystem of image analysis tools for scientists to use in their daily work."

Thanks @jni for reminding us of this and for being so clear on this aspect. That helps a lot when communicating with potential users. 👍

I would be very sad if devs become second class citizens.

I would be very sad if non-coders become second class citizens ☺️🙌

It's good to have this discussion here. I'd hope that some [bio-]image analysis courses can adopt the right terminology. I'm happy to update my courses, especially if terminology is well thought-through. For example, I personally also prefer "color-maps" over "lut", because color-map is human language. Lut is not. 😉

sofroniewn commented 3 years ago

Great discussion here folks, a lot of good point all around - i also agree though with the main points from @jni and @tlambert03

it seems like a glossary would be a good place to start.

Yes I agree here

Initially I thought of suggesting something akin to the NumPy for MATLAB users document (as it is a fairly common case for people to migrate from matlab to NumPy/Python, it may also be the case that people arrive at napari from some other tool) but from @jni 's response above maybe that's not what the community wants.

I think we should explore this idea, they could help a lot of our potential users. It might also help us in our current dev phase to have such guides, though I agree with @jni those migrating users aren't our only focus

jni commented 3 years ago

from @jni 's response above maybe that's not what the community wants.

Oh, @melissawm I'm sorry, I think I might have given the wrong impression: a glossary is a great place to start, and I'm very much in favour of an "ImageJ <> napari" guide! I love that Matlab to NumPy document btw and I send users there all the friggin time. The main purpose of my post is to say that I don't want napari to rush to adopt ImageJ conventions, just like I wouldn't want NumPy to start using 1-based indexing because Matlab does it. I prefer NumPy to do its thing and have a translation guide (from Matlab but also from other tools!), and similarly I prefer napari to do its thing and have one or more translation guides for different communities.

@haesleinhuepf

I would be very sad if non-coders become second class citizens ☺️🙌

Agreed! Let's keep both in mind. 😊 Believe me, a little part of me dies every time a user asks me how to do something simple and I tell them that they have to fire up the IPython console! 😂

For example, I personally also prefer "color-maps" over "lut", because color-map is human language. Lut is not.

Oh good! I feel like you could have made that point in your earlier post. Even re-reading it I feel like you were advocating in favour of Lut. =)

But, I'm happy, it seems that the conversation is converging. Community consensus for the win! 🎉

haesleinhuepf commented 3 years ago

I feel like you were advocating in favour of Lut.

I'm not advocating for anything. My perspective is just limited to ImageJ, because I work(ed) so much with it. My goal was to just point at a need for discussion. I guess that worked :-)

GenevieveBuckley commented 2 years ago

I found this Glossary of Image Processing Terms, which seems reasonably ok. Linking here as a reference.

GenevieveBuckley commented 2 years ago

My other big picture feedback is that the glossary should be grouped into meaningful sections, instead of listed in alphabetical order. Two reasons why:

  1. It's much easier to understand information if there's some sort of framework or structure to it
  2. People can Ctrl+F to search for any word they like instantly. (If you really wanted we could work out how to put a search bar at the top of the glossary page, but I feel like most people will hit Ctrl+F if they want that)

What should the sections be?