# About

This data was generated to study the effect of acute morphine administration on the activation of male and female mouse brains at 1h and 4h post treatment https://doi.org/10.1101/2025.02.19.638902

The code needed to reproduce the results, along with the instructions, is located at https://github.com/CBI-PITT/cfos_morphine_pipeline

Code and instruction updates may be added to this repository after this data is published.


# Project Directory Structure (Dataset + Analysis Outputs)

This project contains 27 datasets (brains) located in individual folders (e.g. `2CL89_*`, `3CL12_*`, `3CL47_*`).
Each of these folders follows the same internal structure and contains raw data, analysis outputs, and meta files required for reproducing the analysis.

---

## Top-level layout

Each experiment folder name encodes information such as:

- **Cohort ID** (e.g. `2CL89`, `3CL12`, `3CL47`)
- **Sample ID (within the cohort)** (e.g. `M1`,`F2`, etc.)
- **Internal numeric ID** (e.g. `id0833`)
- **Treatment** (`morphine` or `saline`)
- **Sex** (`male` or `female`)
- **Timepoint** (`1h`, `4h`)

Example folders:
- `2CL89_M2_id0833_morphine_male_1h/`
- `3CL12_F17R_id1182_morphine_female_1h/`

---

## Standard dataset folder structure

Each folder starting with `2CL89_*`, `3CL12_*`, or `3CL47_*` contains:
```
<DATASET_FOLDER>/
├── analysis/
├── ground_truth/
├── <sample>.ims
├── deepblink_particle.h5
├── metadata.csv
├── model.pth
└── settings.json
```

The folder structure is the same as in the example shown in the GitHub repository and includes files needed to reproduce the results of this study.

---

## Contents

**analysis/**

Contains analysis outputs.
See Analysis folder structure below.

**ground_truth/**

Contains ground-truth annotations/labels used for validation, training comparison, or manual correction.

**.ims**

The raw imaging file (Imaris format) for this brain. (e.g. F1.ims)

**deepblink_particle.h5**

Deepblink model for cell detection (provided for convenience)

**metadata.csv**

Meta information about datasets, including treatment, timepoint, sex

**model.pth**

PyTorch model weights used for cell classification for this sample.

**settings.json**

Configuration used to run the analysis (parameters, paths, etc.).

---

### Analysis folder structure

Each analysis/ folder contains:

```
analysis/
├── registration/
├── resolution_level_x/
├── job_<id>_analysis_df.csv
└── predicted_cells.csv
```

**registration/**

Stores image registration outputs (results of brainreg alignment to the allen_mouse_10um atlas).

**resolution_level_x/**

Stores intermediate results at a given processing resolution.

Inside resolution_level_x/:

```
resolution_level_x/
├── bg_fg_mask_apoc/
└── channel_1/
```

**bg_fg_mask_apoc/**

Background/foreground masks for each z-layer

**channel_1/**
Downsampled signal channel (to skip tiff extraction from the Imaris file)

**job_<id>_analysis_df.csv**

A main analysis results table for the brain. Further used for statistical inference.

Example: job_01182_analysis_df.csv

**predicted_cells.csv**

Model-predicted cells. If manual correction was needed, it is indicated in this file name.

## Summary:

```
DATA_ROOT/
├── 2CL89_M2_id0833_morphine_male_1h/
│   ├── analysis/
│   │   ├── registration/
│   │   ├── resolution_level_x/
│   │   │   ├── bg_fg_mask_apoc/
│   │   │   └── channel_1/
│   │   ├── job_<id>_analysis_df.csv
│   │   └── predicted_cells_manually_corrected.csv
│   ├── ground_truth/
│   ├── *.ims
│   ├── deepblink_particle.h5
│   ├── metadata.csv
│   ├── model.pth
│   └── settings.json
...
│
└── 3CL47_M2_id1250_morphine_male_4h/
    └── (same structure)
```