Towards consistent style, part 1: a naming guide

[timholy]

JuliaImages has grown over several years through the efforts of many people; now that Julia is itself stable, I anticipate new waves of growth in the coming years. To help ensure its health and vibrancy, I think we need to establish some guidelines that will help give such a large, distributed project a unified feel. To me, step 1 of this process is to develop a naming guide and to rename some of our functions or objects accordingly. The sooner we do this the better.

A naming guide should not be arbitrary, but be based on principles. I propose we use this issue to hash out the principles. Here are a few thoughts to get the discussion rolling:

• maintain consistency with the Julia Style Guide
• operations whose primary goal is to construct something should be nouns:
  • when the goal is to create a specific type, use the uppercase constructor name (e.g., HOG())
  • when the type created depends on the inputs, use a lowercase function (e.g., colorview)
• operations that fetch a property or type parameter should be nouns (e.g., axes, eltype)
• for functions that compute something or perform an operation, start with a verb (e.g., warp)
• "lazy" computations should use the noun form (e.g., mappedarray rather than maparray)

More examples of current names that are consistent with these guidelines:

• testimage, line are fine as-is (by the "constructors are nouns" convention)
• colorview as a lazy computation is better than an alternative like combinechannels
• the new build_histogram and adjust_histogram (implemented in Adds build_histogram(Equalization(),...) Images.jl#761, Adds adjust_histogram(Equalization(),...) Images.jl#762) are better than imhist and histeq (which, for now, still remain)

Some examples of current names that would change due to these guidelines:

• imfilter violates the "start with a verb" convention. filterarray, mapstencil (inspired by mapwindow) would both be acceptable
• imshow->showimage
• while dilate is good, tophat seems wrong, though I don't immediately have a suggestion as to how to change it

[Tokazama]

Should all functions that are only meant to support higher level API begin with an underscore?

[Tokazama]

Should indices_spatial or timeaxis be renamed since they do something similar but for space or time? Something like indices_spatial->spatialaxes or timeaxis -> indices_time.

[johnnychen94]

• avoid too specific names, instead, use multiple dispatch. For instance, denoise_TVL1, denoise_TVL2 --> denoise(::AbstractDenoiseMethod)

[zygmuntszpak]

When dealing with Mathematical Morphology operations we could define

abstract type MorphologicalOperation end

struct Erosion <: MorphologicalOperation end
struct Dilation <: MorphologicalOperation end
struct Opening <: MorphologicalOperation end
struct Closing <: MorphologicalOperation end
struct BottomHat <: MorphologicalOperation end
struct TopHat <: MorphologicalOperation end
struct Laplacian <: MorphologicalOperation end
struct HitAndMiss <: MorphologicalOperation end

and then dispatch on analyze_morphology(::MorphologicalOperation(), img, ...).

This is analogous to what we are starting to do with our histogram operations, i.e. adjust_histogram(...) and, in general, I think we could refactor a lot of the codebase to follow this pattern to reduce the vocabulary of different function names.

[timholy]

Worth pointing out that most people seem to prefer sum(A) to reduce(+, A). Nevertheless, I agree that might be the best solution.

[zygmuntszpak]

I would count myself among the group that would prefer sum(A) to reduce(+,A). I will open another issue where I will go over the current API and propose some alternatives. We could then get community feedback and hopefully strike the right balance.

[johnnychen94]

As a quick note, I don't mean to vote for im*

Drawbacks of "start with a verb" convention:

• images are just arrays, and some image-manipulate functions such as rotate resize will likely cause a conflict with other packages.
• if we want to avoid potential naming conflicts, we need to add image suffix to it, e.g., showimage, rotateimage, resizeimage. But it looks lengthy for these "trivial" functions. -- of course lengthy isn't a real problem.
• showim or showimg looks terrible to me.

good point of im* naming style:

• From a user's viewpoint, im* naming makes it easy to use TAB to filter out image-related functions.

---

Is there any reference saying that we must use the "start with a verb" convention?

Python packages uses the package name as the prefix to TAB (e.g., plt.TAB), and they have _* and __* naming styles to filter out those package details. So they don't need another im prefix.

But for Julia we don't necessarily do using Images: imrotate or Images.imrotate, just using Images and imTAB gives us all we want as a user

I think im* prefix for those exported methods is important to users. -- Images.TAB get a list of everything.

A list of names with im* prefix -- thinking of im* as a variant of *image but with TAB completion supported, e.g.,:

• imanalyze_morphology
• imapply_noise
• imbinarize
• imshow

---

one reason for not using im* prefix is that images are just arrays. But since images are just arrays, we can argue in the same way that *image suffix is not good naming practice, and in the same way that showimage should be show.

[johnnychen94]

Which names should be taken?

add noise to an image:

• apply_noise(img, n::Noise)
• apply(img, n::Noise)

update the image tracker status:

• update_tracker!(tracker::Tracker, img)
• update!(tracker::Tracker, img)

apply_noise looks like redundant since the type n::Noise already indicates this. For this reason, I prefer apply and update!

[Deepank308]

I think that apply(n::noise, img) and update!(tracker::Tracker, img) are better. This removes redundancy and code will look a lot cleaner. Also, when read aloud - "Apply this noise to this image" and "Update this tracker with this image" sounds good as pointed out here.

So as general convention when we have a function with img and algorithm as its arguments, some_function_name(img, algorithm) sounds good. While if we happen to have img and some_struct as the arguments, some_function(some_struct, img) sounds better.

Just an idea, please guide me if I'm going wrong.

[johnnychen94]

So as general convention when we have a function with img and algorithm as its arguments, some_function_name(img, algorithm) sounds good. While if we happen to have img and some_struct as the arguments, some_function(some_struct, img) sounds better.

Can you explain this? what are algorithm and some_struct here and why they make a difference in the argument order?

[Deepank308]

For example :

• Algotrithm may be Otsu Binarization so it will sound like - "Binarize this image with Otsu"
• some_struct may be, as above, Tracker or noise so it will sound like - "Update the tracker with this image"

I think I got it wrong, the agrument order for consistent reading depends more on the function name rather than algo or some_struct

[johnnychen94]

My understanding is:

• binarize(img, algo::BinarizationAlgorithm) reads as "binarize image using method algo" -- what-how
• update!(::Tracker, img) reads as "update tracker with image img" -- what-what
• apply!(img, n::Noise) reads as "apply noise n to image" -- what-what

They're quite different here. Hypothetically, if there're many methods applying noise:

• apply!(img, n::Noise, algo::ApplyNoiseAlgorithm) reads as "apply noise to img using method algo" -- what-what-how

all these examples still follow the where-what-how pattern

[Deepank308]

Ok, I got what you are trying to say.
But apply!(n::Noise, img) also follows the same pattern and is more clear to read as "apply noise n to image" as opposed to apply!(img, n::noise)

[johnnychen94]

yes, I have to admit that apply(n::Noise, img) reads better than apply(img, n::Noise)

But this case is quite special in the sense that we can support in-place modification, i.e., apply!(img, n::Noise), where conventionally the first argument will be modified. Not supporting apply(img, n::Noise) will surprise users.

Considering the existence of in-place modification methods, we might not follow the where-what-how pattern; we need follow what-how-where or what-where-how pattern.

[Tokazama]

Recent ideas about a shared functions API may be worth considering for solidifying naming (brought up here and most recently implemented here.

Pros:

• Easy to maintain (b/c it only provides the function name and some documentation)
• Easy to maintain consistency in API between packages in JuliaImages (b/c all would depend on it).

Cons:

• Would likely require some minor changes in many packages (mostly those that overload ImageCore functions).