Metadata-Version: 2.3
Name: mascope-jupyter-widgets
Version: 2026.1.16
Summary: Interactive widgets to construct data analysis notebooks for Mascope
Author: Jussi Vehviläinen, Oskari Kausiala, Konstantin Tumashevich
Author-email: Jussi Vehviläinen <jussi.vehvilainen@karsa.fi>, Oskari Kausiala <oskari.kausiala@karsa.fi>, Konstantin Tumashevich <konstantin.tumashevich@karsa.fi>
License: MIT
Requires-Dist: mascope-sdk>=2025.10.14
Requires-Dist: mascope-tools>=2025.10.27
Requires-Dist: pandas>=2.2.3,<3.0.0
Requires-Dist: pandera>=0.22.1,<0.23.0
Requires-Dist: ipywidgets>=8.1.5,<9.0.0
Requires-Dist: numpy>=2.2.2,<3.0.0
Requires-Dist: tqdm>=4.67.1,<5.0.0
Requires-Dist: python-dotenv>=1.0.1,<2.0.0
Requires-Dist: colorcet>=3.1.0,<4.0.0
Requires-Dist: plotly==5.24.1
Requires-Dist: ipyaggrid>=0.5.4,<0.6.0
Requires-Dist: matplotlib>=3.10.1,<4.0.0
Requires-Dist: seaborn>=0.13.2,<0.14.0
Requires-Dist: scipy>=1.15.2,<2.0.0
Requires-Dist: pandarallel>=1.6.5,<2.0.0
Requires-Dist: loguru>=0.7.3
Requires-Dist: statsmodels>=0.14.4
Requires-Dist: isospecpy>=2.2.3
Requires-Dist: nbformat>=5.10.4
Requires-Dist: molmass>=2025.4.14
Requires-Python: >=3.12, <3.14
Description-Content-Type: text/markdown

# Mascope Jupyter Widgets

This package provides interactive Jupyter widgets to construct data analysis notebooks for Mascope, utilizing [Mascope SDK](https://pypi.org/project/mascope_sdk/) to fetch data from the server.

See also [Mascope Tools](https://pypi.org/project/mascope_tools/) for extended analysis capabilities.

## 🚀 Getting started

### 1. Install Python

- Install [Python >= 3.12](https://www.python.org/downloads/).

### 2. Set up a virtual environment and install dependencies

When developing in Python, it is best practice to use [virtual environments](https://docs.python.org/3/library/venv.html) to
manage project dependencies. To set up a virtual environment for the project, in your terminal, run the following commands:

```sh
# initialize virtual environment
project-dir> python -m venv .venv
# activate the virtual environment
project-dir> .venv/Scripts/activate  # On Windows
project-dir> source .venv/bin/activate  # On Mac or Linux
# install dependencies
(.venv) project-dir> pip install mascope-jupyter-widgets jupyterlab
```

### 3. Configure Mascope access

To enable access from the notebook environment to your organization's Mascope instance, the following configuration steps need to be performed:

1. In the project directory, create an empty text file named `.env`.
2. In Mascope account settings, generate and copy a _Jupyter Notebooks_ access token.
3. Edit the `.env` file with the URL of your Mascope instance and your personal access token, as follows:

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

### 4. Launch JupyterLab

[JupyterLab](https://jupyterlab.readthedocs.io/en/latest/#) is a popular notebook authoring and editing environment.

To run Jupyter Lab, you need to:

1. Open a terminal.
2. Navigate to the directory where your virtual environment is located.
3. Activate the virtual environment.
4. Launch JupyterLab.

```sh
# navigate to the source code directory
user> cd /path/to/project-dir
# activate the virtual environment
project-dir> .venv/Scripts/activate  # On Windows
project-dir> source .venv/bin/activate  # On Mac or Linux
# run jupyter lab
(.venv) project-dir> jupyter-lab
```

A browser window opens, with JupyterLab open. Now browse and open a notebook you wish to run and edit, or create a new one.

If you are not familiar with Jupyter Lab, we recommend starting from their [getting started tutorial](https://jupyterlab.readthedocs.io/en/stable/getting_started/overview.html).

## 📒 Examples

Below there are a few examples demonstrating how to load processed data from Mascope, and quick ways to visualize it. For more elaborate data visualization, you may have a look at for example [Plotly for Python](https://plotly.com/python/).

### Load data

To load data from Mascope, start with `MascopeDataBrowser`:

```
import mascope_jupyter_widgets as mjw

db = mjw.MascopeDataBrowser()
```

After loading, in the next cell, initialize a `MascopeDataWrapper` instance:

```
dataset = mjw.MascopeDataWrapper(db)
```

These two cells you would typically place at the beginning of your notebook. Now, you have easy access to many useful data properties.

> **NOTE:** When you load new data in the data browser, the dataset object gets automatically updated so you don't need to re-instantiate it.

### Target timeseries

To access intensities of all targets matched in Mascope, indexed by datetime, you may use the following dataset properties:

```
dataset.target_compound_timeseries
```

```
dataset.target_ion_timeseries
```

It is very easy to resample the data into different time resolution, for example to compute 1 hour means:

```
1h_timeseries = dataset.target_compound_timeseries.resample("1H").mean()
```

To see matched compositions, yoy may use e.g. `dataset.target_ion_timeseries.columns`. To access the timeseries of a specific target ion or compound, just select the corresponding column from the dataframe, e.g.

```
dataset.target_ion_timeseries['HSO4-']
```

### Peak data

If you have selected to `Import Peaks` when loading the data, you also have the property

```
dataset.peaks_matched
```

available, which contains all peaks of the loaded samples.

To get a quick glance of the peaks, you can for example visualize the, in a simple mass defect plot like this:

```
dataset.peaks_matched.plot(x="mz", y="mass_defect", kind="scatter")
```

### Match data

All the "match data" computed by Mascope are available as dataframes in the dataset object:

```
dataset.match_samples
dataset.match_compounds
dataset.match_ions
dataset.match_isotopes
```

> **NOTE:** The property `dataset.match_samples` contains all sample metadata from the loaded batches, including timestamps, filenames as well as other attributes.
