quickstart

Quickstart

Setting up your environment

Prerequisites

Python 3.12.X
uv package manager

Getting Started

Clone the Impulse repository.
run uv sync to create an environment

main.py

main.py is the entry point for starting a compute job. Run uv main.py --help for information about arguments to pass to the compute job.

$ uv run main.py --help
usage: main.py [-h] [--input INPUT] [--recursive] [--accession_number ACCESSION_NUMBER] [--fw_name FW_NAME] [--reset]

options:
  -h, --help            show this help message and exit
  --input INPUT, -i INPUT
                        The input path. If the input path is a directory, iterates over all files inside. Pass --recursive option to loop through all child directories.
  --recursive, -r       If this argument is passed, adds files recursively to the workflow.
  --accession_number ACCESSION_NUMBER, -a ACCESSION_NUMBER
                        The identifier for which the files should be linked. This should be a barcode.
  --fw_name FW_NAME, -n FW_NAME
                        A custom name of the workflow. If no argument is passed, defaults to value of --identifier
  --reset               Forces reset of all data. If you do not have admin access, this will fail.

Let us now look at each of the arguments used by the main.py CLI program. A full working sample will be provided at the end of this page.

--input, -i (required): the input argument is a path to the directory that stores the image files on which you want to run a compute job.

--recursive, -r (optional): if the recursive argument is provided, the program will loop through all subdirectories of the path provided by input

--accession_number, -a (required): the accession_number argument takes plain text with no spaces. This is where you should put the PRIMARY IDENTIFIER (READ NO DUPLICATES) so that the job is correctly attributed with an agreed-upon ID.

--fw_name, -n (optional): this argument takes plain text, with no spaces. It will name the compute job so you can find it in MongoDB or the fireworks monitoring GUI.

--reset (optional): this argument resets the database. Only database admins can reset (currently Aerith). YOU WILL LOSE ALL DATA IF THIS ARGUMENT IS PASSED AS ADMIN. Recovery is possible, as our database is snapshot every day.

download_files.py

download_files.py is run after a compute job is completed (we will demonstrate how to check the status of a compute job later.)

$ uv run download_files.py --help
usage: download_files.py [-h] [--accession_number ACCESSION_NUMBER] [--output_file OUTPUT_FILE]

options:
  -h, --help            show this help message and exit
  --accession_number ACCESSION_NUMBER, -id ACCESSION_NUMBER
                        The barcode identifier for what you wish to download.
  --output_file OUTPUT_FILE, -o OUTPUT_FILE
                        A file path to which the file will be saved.

Let us now look at each of the arguments used by the download_files.py CLI program. A full working sample will provided at the end of this page.

--accession_number, -id (required): The accession_number argument is the plain text argument that finds all documents in the database with which that accession number is attributed.

--output_file, -o (optional): If you want to put your downloaded files in a custom directory, you may pass a relative or absolute path here. Default value is .

Expected behavior:

Makes a MongoDB query to find all files with accession number.
Creates a directory that is the value provided by accession_number.
If --output_file is passed, create the accession number directory in the path provided. Otherwise, create the directory in the cwd.
Creates a directory named <accession_number>, with all files associated with that accession_number inside the directory.

Sample output:

$ tree
.
└── p1074_35556032756942
    ├── p1074_35556032756942_0000000001.png
    ├── p1074_35556032756942_0000000002.png
    ├── p1074_35556032756942_0000000003.png
    ├── p1074_35556032756942_0000000004.png
    ├── p1074_35556032756942_0000000005.png
    ├── p1074_35556032756942_0000000006.png
    ├── p1074_35556032756942_0000000007.png
    ├── p1074_35556032756942_0000000008.png
    ├── p1074_35556032756942_0000000009.png
    ├── p1074_35556032756942_0000000010.png
    ├── p1074_35556032756942_0000000011.png
    ├── p1074_35556032756942_0000000012.png
    └── p1074_35556032756942.json

Navigation Menu