###############
### 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:
2CL89M2id0833morphinemale_1h/
3CL12F17Rid1182morphinefemale_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.

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)