csi_images API documentation

# csi_images

This package contains classes and functions for interacting with images and image data. While much of the functionality is specific to the CSI-Cancer organization, some of the functionality and structure may be beneficial for the broader community. Other packages in the CSI-Cancer organization may depend on this package.

## Structure

This package contains these helpful modules:

1. `csi_scans.py`: a module for interacting with scan-level files, such as .czi files.
   - `Scan`: a class that contains all of the scan metadata. for interacting with scan metadata, such as the slide ID, the path to the scan, and scan parameters.
2. `csi_tiles.py`: a module for interacting with tiles, which have a particular (x, y) position in the scan. Tiles have several frames taken at the same position.
   - `Tile`: a class for containing a tile's metadata data. Imports `csi_scans.py`.
     - `get_tiles()`: gets the tile of a scan at a particular coordinate.
     - `get_all_tiles()`: gets all of the tiles of a scan.
     - `get_tiles_by_row_col()`: gets the tiles in particular rows and columns.
     - `get_tiles_by_xy_bounds()`: gets the tiles within particular x and y bounds.
3. `csi_frames.py`: a module for interacting with frames, which are individual images from the scan. Each frame in a tile has a different channel, or light spectrum. Imports `csi_scans.py` and `csi_tiles.py`. For more information on this organization, see the CSI IT documentation.
   - `Frame`: a class for containing a frame's metadata.
     - `get_image()`: gets the image of the frame.
     - `get_frames()`: gets the frames of a tile.
     - `get_all_frames()`: gets all of the frames of a scan.
     - `make_rgb_image()`: creates an RGB image from the frames.
     - `make_rgbw_image()`: creates an RGBW image from the frames. A superset of `make_rgb_image()`, but both exist for convenience and clarity.
4. `csi_events.py`: a module for interacting with individual events. Imports `csi_scans.py`, `csi_tiles.py`, and `csi_frames.py`.
   - `Event`: a class for containing an event's metadata and feature data. Key metadata (scan, tile, x, y) is required; the others are optional and flexible.
     - `get_scan_position()`: gets the x, y position of the event in the scan coordinate system.
     - `get_slide_position()`: gets the x, y position of the event in the slide coordinate system.
     - `extract_event_images()`: extracts the images of the event from the scan, reading from the scan images to do so. Convenient for getting a few events.
     - `crop_images_to_event()`: crops the images of the event from the scan, using the passed-in images. More efficient when getting many events.
   - `extract_all_event_images()`: efficiently extracts the images of a list of events.
   - `get_features_as_dataframe()`: combines the features from a list of events into a DataFrame.
   - `get_metadata_as_dataframe()`: combines the metadata from a list of events into a DataFrame.
   - `save_to_hdf5()`: loads a list of events from a CSV file. Not implemented yet.
   - `load_from_hdf5()`: montages a list of events. Not implemented yet.
   - `save_to_csv()`: loads a list of events from a CSV file. Not implemented yet.
   - `load_from_csv()`: montages a list of events. Not implemented yet.

### Planned Features

- `csi_events.py`: a module for interacting with individual events. Imports `csi_scans.py`, `csi_tiles.py`, and `csi_frames.py`.
  - `montage_events()`: Combines crops for an event into side-by-side montages.

## Documentation

For more detailed documentation, open up `docs/index.html` in your browser.

To regenerate the documentation, ensure that you have installed the package and then run:

    make_docs

## Installation

If you haven't yet, make sure to set up an SSH key for GitHub.

1. Activate your `conda` (`conda activate yourenv`) or `venv` (`source path/to/your/venv/bin/activate`) environment first.
2. Clone `csi_images` and install:

    cd ~/path/to/your/repositories
    git clone git@github.com:CSI-Cancer/csi_images.git
    pip install ./csi_images

Alternatively, you can "editable" install the package, which will allow you to make changes to the package and have them reflected in your environment without reinstalling:

    pip install -e ./csi_images

This will add symbolic links to your `site-packages` directory instead of copying the package files over.

View Source

    1"""
    2.. include:: ../README.md
    3"""