========================================================================
             Deconvolution Pipeline User Guide
========================================================================

#example (single cell data--see Methods in manuscript)
bash run_deconvolution.sh \
  --input_pseudo "/faststorage/project/cattle_gtexs/Deconvolution/Cattle/Pseudo/Cerebral cortex/Cerebral cortex_pseudo.rds" \ #single cell simulation data
  --input_ref "/faststorage/project/cattle_gtexs/Deconvolution/Cattle/Pseudo/Cerebral cortex/Cerebral cortex_ref.rds" \ #single cell reference data
  --gtf_file "/faststorage/project/cattle_gtexs/reference/Bos_taurus.ARS-UCD1.2.110.gtf" \
  --output_dir "/faststorage/project/cattle_gtexs/Deconvolution/output_results" \
  --project_dir "/faststorage/project/cattle_gtexs" \
  --tissue "Cerebral_cortex"


1. Pipeline Overview

This pipeline is a highly integrated workflow for advanced deconvolution analysis of single-cell and bulk RNA-seq data.

The complete workflow is controlled by a master Bash script (run_deconvolution.sh), which sequentially executes five functional R scripts.

The pipeline supports command-line long options for specifying input and output paths, real-time terminal output with simultaneous log recording, and robust runtime error-code capture and fail-fast termination mechanisms.


2. File Structure

Place the following files in the same directory on the server:

├── run_deconvolution.sh                       # Master command-line pipeline script
├── 2.1 Pseudo bulk construction.R             # Step 1 script
├── 2.2 Deconvolution benchmarking.R           # Step 2 script
├── 2.3 DWLS_CellComponents_deconvolution.R    # Step 3 script
├── 2.4 BMIND_CellExpression_deconvolution.R   # Step 4 script
└── 2.5 MeduSa_CellState_deconvolution.R       # Step 5 script

Once the pipeline starts, the following directory will be automatically created in the current working directory:

└── pipeline_logs/                             # Runtime and error logs for each module


3. Detailed Description, Modifications, and Usage Recommendations for Each Step

------------------------------------------------------------------------
[Step 1] 2.1 Pseudo bulk construction.R
------------------------------------------------------------------------

- Core function:

  Generates pseudo-bulk expression matrices with known cell-type proportions by computationally mixing the input single-cell data.

------------------------------------------------------------------------
[Step 2] 2.2 Deconvolution benchmarking.R
------------------------------------------------------------------------

- Core function:

  Benchmarks the performance of eight conventional deconvolution methods using the pseudo-bulk data with known ground-truth cell-type proportions generated in Step 2.1.

------------------------------------------------------------------------
[Step 3] 2.3 DWLS_CellComponents_deconvolution.R
------------------------------------------------------------------------

- Core function:

  Uses the dampened weighted least squares (DWLS) algorithm to estimate cell-type proportions in individual bulk samples.

- Usage recommendations:

  When running the master pipeline script, make sure to provide the correct English tissue name through --tissue (e.g., Cerebral_cortex) to enable seamless output transfer to the next step.


------------------------------------------------------------------------
[Step 4] 2.4 BMIND_CellExpression_deconvolution.R
------------------------------------------------------------------------

- Core function:

  Uses the Bayesian mixed-effects model implemented in bMIND to estimate cell-type-specific molecular expression profiles in bulk samples based on known cell-type proportions.


- Usage recommendations:

  Because the Step 2.4 script automatically scans multiple tissues, ensure that the tissue-level prediction results generated by the upstream Step 2.3 script, or previously generated tissue-level results, are stored in the corresponding Results_DWLS/ directory using the expected format before running this step.


------------------------------------------------------------------------
[Step 5] 2.5 MeduSa_CellState_deconvolution.R
------------------------------------------------------------------------

- Core function:

  Extends deconvolution beyond discrete cell types by using the MeDuSA algorithm to infer abundance patterns along continuous cell states and developmental trajectories in bulk samples.


- Usage recommendations:

  The MeDuSA algorithm is computationally intensive when fitting continuous cell states and uses substantial CPU resources (ncpu = 12 by default). If computational resources are limited or the job is waiting in a cluster queue, reduce the ncpu parameter in the R script according to the available cluster resources.


4. Runtime Error Handling and Log Management

1. Real-time dual output (tee mechanism):

   The master script uses a dual-output mechanism:

   Rscript ... 2>&1 | tee

   This means that all progress messages, warnings, package-loading information, and other output generated by the R scripts are displayed in real time in the terminal, just as when running an R script interactively. At the same time, all output is simultaneously written to the corresponding log files in the ./pipeline_logs/ directory for troubleshooting and archival purposes.

2. Precise exit-code capture and fail-fast termination:

   The master script uses the PIPESTATUS[0] array to capture the actual exit code of each R script. If any R script fails because of data-format errors, matrix-dimension mismatches, missing packages, or out-of-memory (OOM) errors, its true non-zero exit code is immediately captured by the Bash script.

   The pipeline then triggers a fail-fast mechanism and immediately terminates all subsequent steps, preventing downstream analyses from continuing with invalid or incomplete data. A clear error message and the corresponding exit code are displayed in the terminal to facilitate troubleshooting, deployment, and maintenance.
