mascope-jupyter-widgets 2025.5.21.post3

Interactive widgets to construct data analysis notebooks for Mascope

Mascope Jupyter Widgets

This repository contains interactive widgets to construct data analysis notebooks for Mascope, utilizing Mascope SDK to fetch data from the server.

All developer docs are in this document:

• 🚀 Getting started - installation / configuration / authentication
• 📚 Modules - filtering / mascope_data / mass_defect / timeseries

Getting started

Installation

This project uses uv for dependency management, and therefore it is a prerequisite for installation. Install uv following their instructions.

Once installed, open a terminal, navigate into the repository directory mascope-jupyter-widgets/ and run

uv sync

Environment configuration

NOTE: The .env file needs to be placed in the directory from which you launch the notebooks

To load data from the Mascope database, you will need to configure the URL as well as a personal access token.

1. In the source code directory, copy .env.example to a new file named .env in the same location.
2. Generate and copy a Jupyter Notebooks access token in your Mascope account management.
3. Replace placeholders in the .env file with the URL of your Mascope instance and your personal access token:

MASCOPE_ACCESS_TOKEN=p3R5oN4l4cC35s70Ken
MASCOPE_URL="https://org.mascope.app"

Note: The .env file is gitignored to prevent accidental commit of personal access tokens. Never commit your actual token to the repository.

Modules

The repository is structured into modules as follows:

mascope-jupyter-widgets/      Repository root
  mascope-jupyter-widgets/      Package directory
    binning/                      Dataset binning module
    filtering/                    Dataset filtering module
    mascope_data/                 Data loading module
    mass_defect/                  Mass defect analysis module
    sample_timeseries/            Sample peak timeseries analysis module
    spectrum/                     Spectrum analysis module
    timeseries/                   Timeseries analysis module

binning/

Module providing tools to bin data to mz-groups.

Names exported to package namespace:

• BinningWidget

  Interactive notebook widget to bin peaks of the dataset samples to mz-groups. It provides different methods and vizualisations for the binning analyze.

filtering/

Module providing tools to select a subset of the loaded dataset based on various filtering criteria.

Names exported to package namespace:

• FilteringWidget

  Interactive notebook widget to filter a subset of the data currently loaded into MascopeDataWrapper. With the filters applied, all the data propertites exposed by MascopeDataWrapper return the filtered data.

mascope_data/

Module providing tools to load and interface with Mascope data.

Names exported to package namespace:

• MascopeDataBrowser

  Interactive notebook widget to browse and load data from Mascope server.

• MascopeDataWrapper

  A class providing a standardized interface to the data loaded from Mascope, consisting of various pandas dataframes exposed as class properties. An instance of the data wrapper is used as the input to analysis modules.

mass_defect/

Module providing tools to perform mass defect analysis on the loaded dataset.

Names exported to package namespace:

• MassDefectWidget

  Interactive notebook widget to visualize the dataset based on mass defect, providing various ways of scaling and normalization.

sample_timeseries/

Module providing tools to perform sample peak timeseries analysis on the loaded dataset.

Names exported to package namespace:

• SampleTimeSeriesWidget

  Interactive notebook widget to visualize the dataset sample peak timeseries.

spectrum/

Module providing tools to perform spectrum analysis on the loaded dataset.

Names exported to package namespace:

• SpectrumWidget

  Interactive notebook widget to visualize the dataset spectrums.

timeseries/

Module providing tools to perform timeseries analysis on the loaded dataset.

Names exported to package namespace:

• TimeSeriesWidget

  Interactive notebook widget to visualize the dataset based on time, providing various ways of aggregation.