API Reference¶

Auto-generated reference for the renumics.spotlight Python package. Individual modules:

Dataset — the Spotlight HDF5 dataset (renumics.spotlight.dataset).
Data types — the Spotlight type system (renumics.spotlight.dtypes).
Layout — build inspection layouts (renumics.spotlight.layout).

`renumics.spotlight`¶

spotlight ¶

Renumics Spotlight allows you to quickly explore your datasets.

To serve an interactive view of your dataset, simply pass it to spotlight.show.

import pandas as pd
from renumics import spotlight
df = pd.DataFrame(
   {
        "int": range(4),
        "str": "foo",
        "dt": pd.Timestamp("2017-01-01T12"),
        "cat": pd.Categorical(["foo", "bar"] * 2),
    }
)
spotlight.show(df)

Spotlight tries to infer supported column types from your data, but you can overwrite these column types. Supply your custom mapping as dtype parameter to spotlight.show. For detailed overview of all the supported data types, see renumics.spotlight.dtypes.

viewer = spotlight.show(df, dtype={"int": "float", "str": "category"})

We try to support a wide range of data sources, such as CSV, Parquet, ORC and Hugging Face datasets.

df = pd.read_csv("https://raw.githubusercontent.com/Renumics/spotlight/refs/heads/main/data/mnist/mnist-tiny.csv")
spotlight.show(df, dtype={"image": dtypes.image_dtype})

import datasets
ds = datasets.load_dataset("mnist", split="test")
spotlight.show(ds)

As an alternative that fully supports and persist our column types you can use our custom H5 dataset.

from datetime import datetime
from renumics import spotlight
with spotlight.Dataset("docs/example.h5", "w") as dataset:
    dataset.append_int_column("int", range(4))
    dataset.append_string_column("str", "foo")
    dataset.append_datetime_column("dt", datetime(2017, 1, 1, 12))
    dataset.append_categorical_column("cat", ["foo", "bar"] * 2)
spotlight.show("docs/example.h5")

To show an updated dataset change some viewer settings (e.g. provide custom types), you can reuse the viewer instance returned by spotlight.show.

df = pd.read_csv("https://raw.githubusercontent.com/Renumics/spotlight/refs/heads/main/data/mnist/mnist-tiny.csv")
viewer = spotlight.show(df)
df["str"] = "foo"
viewer.show(df)
viewer.show(dtype={"image": dtypes.image_dtype})

DataIssue ¶

An Issue affecting multiple rows of the dataset

Viewer ¶

A Spotlight viewer. It corresponds to a single running Spotlight instance.

Viewer can be created using spotlight.show.

Attributes:

Name	Type	Description
`host`	`str`	host at which Spotlight is running
`port`	`Optional[int]`	port at which Spotlight is running

running `property` ¶

running: bool

True if the viewer's webserver is running, false otherwise.

df `property` ¶

df: Optional[DataFrame]

Get served DataFrame if a DataFrame is served, None otherwise.

host `property` ¶

host: str

The configured host setting.

port `property` ¶

port: Optional[int]

The port the viewer is running on.

url `property` ¶

url: str

The viewer's url.

show ¶

show(
    dataset: Union[PathType, DataFrame, None] = None,
    folder: Optional[PathType] = None,
    layout: Optional[_LayoutLike] = None,
    no_browser: bool = False,
    allow_filebrowsing: Union[
        bool, Literal["auto"]
    ] = "auto",
    wait: Union[bool, Literal["auto", "forever"]] = "auto",
    dtype: Optional[Dict[str, Any]] = None,
    analyze: Optional[Union[List[str], bool]] = None,
    issues: Optional[Collection[DataIssue]] = None,
    embed: Optional[Union[List[str], bool]] = None,
) -> None

Show a dataset or folder in this spotlight viewer.

Parameters:

Name	Type	Description	Default
`dataset`	`Union[PathType, DataFrame, None]`	Dataset file or pandas.DataFrame (df) to open.	`None`
`folder`	`Optional[PathType]`	Root folder for filebrowser and lookup of dataset files.	`None`
`layout`	`Optional[_LayoutLike]`	Optional Spotlight layout.	`None`
`no_browser`	`bool`	Do not show Spotlight in browser.	`False`
`allow_filebrowsing`	`Union[bool, Literal['auto']]`	Whether to allow users to browse and open datasets. If "auto" (default), allow to browse if `dataset_or_folder` is a path.	`'auto'`
`wait`	`Union[bool, Literal['auto', 'forever']]`	If `True`, block code execution until all Spotlight browser tabs are closed. If `False`, continue code execution after Spotlight start. If "forever", keep spotlight running forever, but block. If "auto" (default), choose the mode automatically: non-blocking (`False`) for `jupyter notebook`, `ipython` and other interactive sessions; blocking (`True`) for scripts.	`'auto'`
`dtype`	`Optional[Dict[str, Any]]`	Optional dict with mapping `column name -> column type` with column types allowed by Spotlight (for dataframes only).	`None`
`analyze`	`Optional[Union[List[str], bool]]`	Automatically analyze common dataset issues (disabled by default).	`None`
`issues`	`Optional[Collection[DataIssue]]`	Custom dataset issues displayed in the viewer.	`None`
`embed`	`Optional[Union[List[str], bool]]`	Automatically embed all or given columns with default embedders (disabled by default).	`None`

close ¶

close(
    wait: Union[bool, Literal["forever"]] = False,
) -> None

Shutdown the corresponding Spotlight instance.

open_browser ¶

open_browser() -> None

Open the corresponding Spotlight instance in a browser.

refresh ¶

refresh() -> None

Refresh the corresponding Spotlight instance in a browser.

close ¶

close(port: Union[int, Literal['last']] = 'last') -> None

Close an active Spotlight viewer.

Parameters:

Name	Type	Description	Default
`port`	`Union[int, Literal['last']]`	optional port number at which the Spotlight viewer is running. If "last" (default), close the last started Spotlight viewer.	`'last'`

Raises:

Type	Description
`ViewNotFoundError`	if no Spotlight viewer found at the given `port`.

show ¶

show(
    dataset: Union[PathType, DataFrame, None] = None,
    folder: Optional[PathType] = None,
    host: str = "127.0.0.1",
    port: Union[int, Literal["auto"]] = "auto",
    layout: Optional[_LayoutLike] = None,
    no_browser: bool = False,
    allow_filebrowsing: Union[
        bool, Literal["auto"]
    ] = "auto",
    wait: Union[bool, Literal["auto", "forever"]] = "auto",
    dtype: Optional[Dict[str, Any]] = None,
    analyze: Optional[Union[bool, List[str]]] = None,
    issues: Optional[Collection[DataIssue]] = None,
    embed: Optional[Union[List[str], bool]] = None,
    ssl_keyfile: Optional[str] = None,
    ssl_certfile: Optional[str] = None,
    ssl_keyfile_password: Optional[str] = None,
    no_ssl: bool = False,
) -> Viewer

Start a new Spotlight viewer.

Parameters:

Name	Type	Description	Default
`dataset`	`Union[PathType, DataFrame, None]`	Dataset file or pandas.DataFrame (df) to open.	`None`
`folder`	`Optional[PathType]`	Root folder for filebrowser and lookup of dataset files.	`None`
`host`	`str`	optional host to run Spotlight at.	`'127.0.0.1'`
`port`	`Union[int, Literal['auto']]`	optional port to run Spotlight at. If "auto" (default), automatically choose a random free port.	`'auto'`
`layout`	`Optional[_LayoutLike]`	optional Spotlight layout.	`None`
`no_browser`	`bool`	do not show Spotlight in browser.	`False`
`allow_filebrowsing`	`Union[bool, Literal['auto']]`	Whether to allow users to browse and open datasets. If "auto" (default), allow to browse if `dataset_or_folder` is a path.	`'auto'`
`wait`	`Union[bool, Literal['auto', 'forever']]`	If `True`, block code execution until all Spotlight browser tabs are closed. If `False`, continue code execution after Spotlight start. If "forever", keep spotlight running forever, but block. If "auto" (default), choose the mode automatically: non-blocking (`False`) for `jupyter notebook`, `ipython` and other interactive sessions; blocking (`True`) for scripts.	`'auto'`
`dtype`	`Optional[Dict[str, Any]]`	Optional dict with mapping `column name -> column type` with column types allowed by Spotlight (for dataframes only).	`None`
`analyze`	`Optional[Union[bool, List[str]]]`	Automatically analyze common dataset issues (disabled by default).	`None`
`issues`	`Optional[Collection[DataIssue]]`	Custom dataset issues displayed in the viewer.	`None`
`embed`	`Optional[Union[List[str], bool]]`	Automatically embed all or given columns with default embedders (disabled by default).	`None`
`ssl_keyfile`	`Optional[str]`	Optional SSL key file.	`None`
`ssl_certfile`	`Optional[str]`	Optional SSL certificate file.	`None`
`ssl_certfile`	`Optional[str]`	Optional SSL keyfile password.	`None`
`no_ssl`	`bool`	Do not require SSL sertificate and keyfile when starting on non-localhost.	`False`

viewers ¶

viewers() -> List[Viewer]

Get all active Spotlight viewer instances.

clear_caches ¶

clear_caches() -> None

Clear all cached data.

API Reference¶

renumics.spotlight¶

spotlight ¶

DataIssue ¶

Viewer ¶

running property ¶

df property ¶

host property ¶

port property ¶

url property ¶

show ¶

close ¶

open_browser ¶

refresh ¶

close ¶

show ¶

viewers ¶

clear_caches ¶

`renumics.spotlight`¶

running `property` ¶

df `property` ¶

host `property` ¶

port `property` ¶

url `property` ¶