These design philosophies are mainly borrowed from ggplot, Zen of Python, and Rust.
- Modularity over abstraction
Abstraction is nice but sacrifices customizability. If the user can provide + ggsize(800,600) and change the figure size at any point, there is no need to accept for plotting functions width or heigth as paramaters. The same applies to the many other possible layers and aesthetics of the plot. This approach is particularly useful with notebooks and exploratary data analysis, EDA. On top of eliminating unncessary complexity, the approach eliminates the risk of conflicting arguments.
- Predictability over flexibility
Flexibility provides convenience but sacrifices predictibality. If providing a single key produces a single plot and providing a sequence of keys prodcues a grid of plots the return type would be different (i.e, PlotSpec vs SupPlotsSpec) for the same function. The follow-up workflow would have to be totally different for these two cases.
Cellestial ensures reproducibility by strict return types. Naming convention allows such strict return types. Instead of cl.umap() accepting a sequence of keys (Sequence[str]) and returning a grid of plots (SupPlotsSpec), it only accepts a single key (str) it is guaranteed to return a single plot (PlotSpec).
Plural versions of such functions are available, if the user needs a grid of plots with provided keys. For instance, cl.umaps() requires a sequence of strings as keys and is guaranteed to return grid of plots (SupPlotsSpec).
In case the user wants to merge multiple violins/boxplot geoms on a single plot, the user can simply call the cl.violin() or cl.boxplot() with sequence of keys which strictly return PlotSpec. However, if the user wants the grid with the same keys, the sequence can be provided to the plural versions of the same plot types i.e cl.violins() or cl.boxplots() which are guaranteed to return SupPlotsSpec.
- Explicity over implicity
Explicit function and parameter names allow the users to be fully aware and sure of what they are doing. While it is more convenient or easier to write vln() or inc_dims = instead of violin() or include_dimensions =, the former is less intuitive and requires users to remember how the programmer choose to shorten the words.
- Simplicity & Expressivenes
Cellestial is a data visualization library, therefore the plotting functions names does not have to include keywords such as plot in the names nor they have to be in different namespaces. Cellestial API is simple enough for most users yet expressive enough for users to know what exactly they are using.