Package: clusterfun
ClusterfunClusterfunis a python plotting library to explore image data. Play around with a live demo onhttps://clusterfun.app.Getting startedA simple exampleMain featuresDefault parametersPlot typesBar chartConfusion matrixGridHistogramPie chartScatterplotViolin plotData loadingGetting startedClusterfun can be installed with pip:pip install clusterfunClusterfun requires Python 3.8 or higher.Plots accept data in the form of a pandas DataFrame, which will be installed automatically if not already present.
No account, payment, or internet connection is required to use clusterfun. Clusterfun is open source and free to use.A simple exampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.scatter(df,x="x",y="y",media="img_path",color="painter")Data can be hosted locally or on AWS S3.As you can see, a clusterfun plot takes as input a pandas dataframe and column names indicating which columns to use for the visualisation. In this way, it is similar to the seaborn or the plotly library. But in clusterfun, you can:Click and drag to select data to visualise it in a gridHover over data points to see them on the right side of the pageClick on data points to view zoomed in versions of the image related to the data pointThis makes clusterfun ideal for quickly visualising image data, which can be useful in the context of building datasets, exploring edge cases and debugging model performance.Main featuresDefault parametersThe default parameters for the plot types are as follows:df: pd.DataFrame(required)The dataframe used for the data to plot. Most other parameters are column names in this dataframe (e.g. media, color, etc.).media: str(required)The column name of the media to display in the plot. See data loading for more information about the type of media that can be displayed.show: bool = TrueWhether to show the plot or not. If show is set to True, clusterfun will start a local server to display the plot in a web browser. More specifically, we start a FastAPI server where we mount the webpage as a static file. The application itself does not require an internet connection. All data is loaded locally and does not leave your machine/browser.
If show is set to False, clusterfun only saves the required data to serve the plot later on and return the path to where the data is stored. If you want to serve the plot yourself later on, you can runclusterfun  {path - to - data}|{uuid}in the command line to start a local server for the plot you are interested in.color: Optional[str] = NoneIf given, points will be colored based on the values in the given column. Powerful for visualising clusters or classes of data.title: Optional[str] = NoneThe title to use for the plot.bounding_box: Optional[str] = NoneYou can visualise bounding boxes on top of your images by with thebounding_boxparameter. For this to work, you need to have a bounding box column in the dataframe used to plot the data. Each cell in the dataframe needs to contain a dictionary or a list of dictionaries with bounding box values: xmin, ymin, xmax, ymax, label (optional), color (optional). The keys of the expected dictionary are:xmin: float | intymin: float | intxmax: float | intymax: float | intlabel: Optional[str] = Nonecolor: Optional[str] = NoneIf no color is provided, a default color scheme will be used. The color value can be a color name or hex value. The label will be displayed in the top left of the bounding box.
Example:single_bounding_box={"xmin":12,"ymin":10,"xmax":100,"ymax":110,"color":"green","label":"ground truth"}Plot typesThe following plot types are available:Bar chartConfusion matrixGridHistogramPie chartScatterplotViolin plotBar chartdefbar_chart(df:pd.DataFrame,x:str,media:str,color:Optional[str]=None,...)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to plotx: strThe column name of the data for the bar chart. One bar per unique value will be plotted.media: strThe column name of the media to displaycolor: Optional[str] = NoneIf added, the color will be used to create a stacked bar chart.Exampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.bar_chart(df,x="painter",media="img_path",color="style")Confusion matrixdefconfusion_matrix(df:pd.DataFrame,y_true:str,y_pred:str,media:str,...)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to ploty_true: strThe ground truth label. Values can be integers or strings.y_pred: strThe column name of the predicted label. Values can be integers or strings.media: strThe column name of the media to displayExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/cifar10.csv")clt.confusion_matrix(df,y_true="label",y_pred="pred",media="img_path")Griddefgrid(df:pd.DataFrame,media:str,...)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to plotmedia: strThe column name of the media to displayExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.grid(df,media="img_path")Histogramdefhistogram(df:pd.DataFrame,x:str,media:str,bins:int=20,...)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to plotx: strThe column name of the data for the histogrammedia: strThe column name of the media to displaybins: int = 20The number of bins to use for the histogramExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.histogram(df,x="brightness",media="img_path")Pie chartdefpie(df:pd.DataFrame,color:str,)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to plotcolorColumn for the pies of the pie chartExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.pie_chart(df,color="painter",media="img_path")Scatterplotdf: pd.DataFrame,
    x: str,
    y: str,
    ...
) -> Path:Parametersdf: pd.DataFrameThe dataframe with the data to plotx: strThe column name of the data for the x-axisy: strThe column name of the data for the y-axisExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.scatter(df,x="x",y="y",media="img_path")Violin plotdefviolin(df:pd.DataFrame,y:str,...)->Path:Parametersdf: pd.DataFrameThe dataframe with the data to ploty: strThe column name of the data for the y-axisExampleimportpandasaspdimportclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")df=df[df.painter.isin(["Pablo Picasso","Juan Gris","Georges Braque","Fernand Leger"])]clt.violin(df,y="brightness",media="img_path")Data loadingClusterfun supports AWS S3 and local data storage and loading.
The dataframe column corresponding to the media value in the plot will be used to determine where to load the media from.importclusterfunascltdf=pd.read_csv("https://raw.githubusercontent.com/gietema/clusterfun-data/main/wiki-art.csv")clt.grid(df,media="img_column")AWS S3 media should start withs3://.
Make sure to set aAWS_REGIONenvironment variable to the region where your data is stored.Support for Google Cloud Storage is coming soon.