Skip to content

NSDF Dark Matter CLI

Terminal showing CLI help output with available commands: version, ls, and download

The NSDF Dark Matter CLI offers a pool of operations to access and download the R76 dark matter dataset. The CLI serves as a top level component in a workflow to download data which can then be analyzed with the NSDF Dark Matter Library

🚀 Getting Started

Virtual Environment

To begin, make sure you have Python 3.10 or higher installed on your machine. You can download it from the official website: Install Python.

In this guide, we will be using uv to manage a virtual environment. You can install uv by following this installation guide.

Note

If you prefer, you can use a different environment manager such as conda or Python's built-in venv

Creating the environment

To create a new virtual environment, run the following command in your terminal:

uv

uv venv darkmatter_cli_env --python 3.10

Conda

conda create -n darkmatter_cli_env python=3.10

Python venv

python -m venv darkmatter_cli_env

Activating the environment

Next, we activate the environment:

uv (recommended)

source darkmatter_cli_env/bin/activate

Conda

conda activate darkmatter_cli_env

Python venv

source darkmatter_cli_env/bin/activate

You should now see the environment name in your terminal prompt, indicating it’s active.

Installing the CLI

From release

We are ready to install the CLI. First, download the wheel file.

wget https://github.com/nsdf-fabric/nsdf-slac/releases/download/v0.1.0/nsdf_dark_matter_cli-0.1.0-py3-none-any.whl

Now, we can install the CLI by passing the wheel file with the following command:

uv (recommended)

uv pip install nsdf_dark_matter_cli-0.1.0-py3-none-any.whl

Conda

pip install nsdf_dark_matter_cli-0.1.0-py3-none-any.whl

Python venv

pip install nsdf_dark_matter_cli-0.1.0-py3-none-any.whl

That's it! The CLI is now installed and ready to use. We can start working with it.

🖥️ The NSDF Dark Matter CLI

To explore all available CLI commands and options, run the following help command:

nsdf-cli --help

Terminal showing CLI help output with available commands: version, ls, and download

Listing remote files

Want to know what files are available to download? Use the ls command to list them. You can also limit how many results you see by passing the --limit flag.

nsdf-cli ls --limit 5

Terminal showing the CLI ls command output. It list the name of the files available in the remote storage

Looking for something specific? Use the --prefix flag to filter files by name:

nsdf-cli ls --prefix 07180928_2310

Downloading a dataset locally

Once you've found the file you want, downloading it is easy with the download command:

nsdf-cli download 07180827_0000_F0001

Terminal showing the CLI download command. It downloads the file specified

Downloaded files go into the idx directory, and each one gets its own subfolder based on the mid_id. After downloading a few datasets, your folder might look like this:

idx/
   |
   07180925_0000_F0001/
   |
   07181007_0000_F0001/
   |
   07180916_0000_F0002/

A mid_id directory is composed of the following files:

07180925_0000_F0001/
                   |
                   07180827_0000_F0001.csv
                   |
                   07180827_0000_F0001.txt
                   |
                   07180827_0000_F0001.idx
                   |
                   07180925_0000_F0001/
                                      |
                                      0000.bin

Next Steps

Now that you have some data, it’s time to dive into analysis! Head over to the NSDF Dark Matter Library guide to learn how to start working with the dataset.