# Reproducibility Package — Manuscript-Frozen Version

This package was prepared to reproduce **exactly the numerical values currently written in the frozen manuscript and supplementary material** for the article:

**Interpretable Prediction of the Elastic Modulus of Hooked-End Steel Fiber-Reinforced Concrete**

## 1. Scope of this package

This version is intentionally aligned to the **frozen manuscript state**. It has two complementary goals:

1. preserve the original analytical workbooks supplied by the author;
2. export cleaned machine-readable CSV files with the correct row counts used in the manuscript;
3. preserve the final closed-form equation exactly as written in the current manuscript;
4. reproduce the spreadsheet-trace metrics directly from the optimized prediction columns stored in the author workbooks;
5. export the manuscript-facing result tables **exactly as currently reported** in the frozen article and supplementary material.

This package therefore distinguishes between:

- **spreadsheet-trace outputs**: metrics recomputed directly from the preserved author workbooks;
- **manuscript-frozen outputs**: exact result tables matching the current manuscript text, Table 1, Table A.1, and Table B.1.

This distinction is deliberate. It ensures exact reproduction of the current manuscript while preserving traceability to the original analytical files.

## 2. Folder structure

- `data_raw/`  
  Original files supplied by the author. Preserved without modification.

- `data_curated/`  
  Cleaned CSV exports generated from the raw spreadsheets after removing blank/footer rows.

- `scripts/`  
  Python scripts used to prepare the data, preserve the final closed-form equation, export workbook-trace metrics, generate manuscript-frozen result tables, and map study membership.

- `results/`  
  Output files generated by the scripts in this package.

- `docs/`  
  Supporting documents, including the current frozen manuscript PDF, the current frozen supplementary PDF, the methodology document, and the variable dictionary.

## 3. Raw analytical files preserved

The following source files are preserved in `data_raw/`:

- `Base_Unificada.xlsx`
- `Base_MODELAGEM_113_Comparativo_V5.xlsx`
- `Base_VALIDACAO_138_Comparativo_V5.xlsx`
- `Dados limpos de modelagem.xlsx`
- `Dados limpos de validação.xlsx`
- `Indicadores de modelagem.xlsx`
- `Indicadores de validação.xlsx`
- `comparacao_equacoes_simplificadas.xlsx`

## 4. Current frozen supporting documents

The following files are preserved in `docs/`:

- `Modelo de Artigo 08 (ACI) - EN(2).pdf`
- `Supplementary Material - Artigo - EN(3).pdf`
- `METODOLOGIA COMPLETA DE REGRESSÕES E ANÁLISES ESTATÍSTICAS.docx`
- `variable_dictionary.csv`

## 5. Computational environment

Required libraries are listed in `requirements.txt`:

- pandas
- numpy
- openpyxl

Recommended installation:

```bash
python -m venv .venv
source .venv/bin/activate   # on Windows use: .venv\Scripts\activate
pip install -r requirements.txt
```

## 6. Workflow

### Stage 1 — Clean and normalize the spreadsheets

Script: `scripts/00_prepare_data.py`

This script:
- reads the raw Excel files;
- removes blank/footer rows with missing IDs;
- exports the cleaned CSV files:
  - `base_modelagem_113_curada.csv`
  - `base_validacao_138_curada.csv`
  - `base_unificada_curada.csv`

Expected cleaned row counts:
- modeling subset: 113
- validation subset: 138
- unified database: 251

Run with:

```bash
python scripts/00_prepare_data.py
```

### Stage 2 — Preserve the final closed-form equation

Script: `scripts/01_model_equation.py`

This script encodes the final equation exactly as written in the frozen manuscript:

```text
Ec = 9.9 * fc^0.31 * (1 + 0.0055 * Vf^0.78) * exp(-0.0002 * fc) + 0.011 * (L/D)^0.85
```

### Stage 3 — Export spreadsheet-trace metrics

Script: `scripts/02_export_workbook_trace_metrics.py`

This script:
- recomputes metrics directly from the optimized prediction columns already stored in the author workbooks;
- recomputes the same metrics from the final closed-form equation in `01_model_equation.py`;
- writes:
  - `results/workbook_trace_metrics.csv`
  - dataset-level files with final-formula predictions.

These outputs preserve traceability to the original spreadsheets, even when manuscript-facing values are rounded or frozen differently.

Run with:

```bash
python scripts/02_export_workbook_trace_metrics.py
```

### Stage 4 — Export manuscript-frozen result tables

Script: `scripts/03_export_manuscript_frozen_results.py`

This script writes the result tables exactly as currently reported in the frozen manuscript and supplementary material:

- `results/manuscript_frozen_core_metrics.csv`
- `results/manuscript_frozen_table1_summary.csv`
- `results/manuscript_frozen_appendix_a_table_a1.csv`
- `results/manuscript_frozen_benchmark_table_b1.csv`

These files are the primary outputs to cite when exact agreement with the current frozen manuscript is required.

Run with:

```bash
python scripts/03_export_manuscript_frozen_results.py
```

### Stage 5 — Export study membership map

Script: `scripts/04_export_study_membership_map.py`

This script maps which studies appear in `Modeling`, `Validation`, or both, based on the unified database labels.

Output:
- `results/study_membership_map.csv`

Run with:

```bash
python scripts/04_export_study_membership_map.py
```

## 7. Key outputs for exact manuscript reproduction

### 7.1 Core reported manuscript values

File: `results/manuscript_frozen_core_metrics.csv`

This file reproduces the exact current manuscript-facing values for:
- blind holdout validation;
- source-exclusive verification.

### 7.2 Frozen Table 1 values

File: `results/manuscript_frozen_table1_summary.csv`

This file reproduces the exact values currently reported in Table 1 of the frozen manuscript.

### 7.3 Frozen Appendix A values

File: `results/manuscript_frozen_appendix_a_table_a1.csv`

This file reproduces the exact values currently reported in Table A.1 of the frozen manuscript.

### 7.4 Frozen Appendix B values

File: `results/manuscript_frozen_benchmark_table_b1.csv`

This file reproduces the exact values currently reported in Table B.1 of the frozen manuscript.

## 8. Important interpretive note

This package is a **manuscript-frozen reproducibility package**.

It is designed to reproduce:
- the exact numerical values currently written in the manuscript and supplementary material;
- the cleaned analytical datasets with the same nominal subset sizes reported in the article;
- the original spreadsheet-native optimized predictions.

It should therefore be interpreted as a journal-submission support package, not as a claim that every publication-facing value is generated exclusively from one single downstream script without any manuscript-stage rounding, freezing, or editorial harmonization.

## 9. Suggested data availability statement

### If the repository is already public

> The curated database, variable metadata, computational scripts, and manuscript-frozen result tables supporting the findings of this study are publicly available in a permanent repository at: DOI: [insert DOI].

### If the repository will be made public upon submission or acceptance

> The curated database, variable metadata, computational scripts, and manuscript-frozen result tables supporting the findings of this study will be deposited in a public repository with a persistent DOI upon submission/acceptance.

