NER and 3D Genome Analysis

This repository contains analysis code for the paper "RNAPII and XPC remodel the 3D genome for UV repair".

All downstream analyses were performed on an Arch Linux system. To facilitate reproducibility of the analyses and manuscript figures, the corresponding code has been deposited primarily as Python-based Jupyter notebooks, with cell outputs preserved, including the generated figures. Additional shell and R scripts used in the analysis are also provided.

Please see the other repositories related to this study for additional research code:

• 1D Simulation Engine
• PHACE-MP

Package Management

Python packages were managed using uv. The required dependencies can be installed using the following command:

uv sync --dev

R packages were managed using renv. The package versions used in this analysis are recorded in r_env/renv.lock.

To install the required R packages and activate the R environment, navigate to the r_env/ directory and start R:

cd r_env
R

Then restore the package environment from the lockfile:

renv::restore()

After restoration, the renv environment will be loaded automatically whenever R is started from the r_env/ directory.

Repository structure

The analysis centres on WT, XPC-knockout and XPA-knockout U2OS cells before and after UV irradiation, with published DLD-1 RNAPII-degron, HeLa, and fibroblast datasets providing complementary comparisons. Hi-C features are integrated with CTCF/XPC ChIP-seq, ATAC-seq, damage-seq, RNAPII occupancy, RNA-seq and XR-seq.

Location	Contents
3d_prep/	Expected contact frequencies, compartment eigenvectors, insulation scores and loop calls from prepared contact maps.
notebooks/	Figure analyses and quality control; see the figure guide and notebook inventory below.
additional/	Exploratory scripts and alternate notebook versions; see its README for descriptions.
scripts/	Sequencing pipeline launchers, signal-track generation, permutation tests, covariate matching and supporting analyses.
src/ggner_3d/	Shared data-loading, genomic-feature, aggregation and plotting helpers.
r_env/	R environment configuration (.Rprofile) and package versions (renv.lock).
pyproject.toml, uv.lock	Python package configuration and dependency lockfile.
main.py	Package greeting placeholder; analysis entry points are the scripts and notebooks.
data/, figs/	Local input/intermediate data and exported plots. These directories are ignored by Git.

Figure guide

References cover the manuscript's Figures 1–5, Fig. 6g, Extended Data Figures 1–8 and Extended Data 10a.

Figure	Analysis and entry points
Fig. 1b–g	WT contact-distance decay: cis_decay.ipynb; compartment strength and saddle maps: compartments.ipynb, saddle.ipynb; TAD pileups and compartment-stratified strength: tads.ipynb; shared/specific loops and anchors: loops.ipynb. Panel a is the experimental schematic.
Fig. 2a–b	CPD formation/repair, ATAC, CTCF and XPC profiles across post-UV-strength TAD quartiles and their assigned, downsampled loops: fig2_rework_Q.ipynb. Panels c–d are excluded wet-lab/microscopy analyses.
Fig. 3a–e	WT versus XPC-knockout TAD/loop pileups, loop/anchor overlaps, and CTCF/ATAC profiles at preserved features: fig3.ipynb. Includes additional XPA comparisons.
Fig. 4a–e, g	XPC–CTCF proximity: xpc_ctcf_null_autosomesX_dynamic.sh → fig4.ipynb; high-/low-XPC matching: prepare_covariate_df.ipynb → run_grid_search.sh / xpc_ctcf_grid_search.R → fig4_inspect_covariate_results_v2.ipynb; PHACE partner rankings: phace_index.ipynb. Panel c illustrates the matching framework.
Fig. 5a–f	Boundary contact changes: fig5_fc_boundaries.ipynb (a); CTCF after RNAPII depletion: fig5_degron_ctcf.ipynb (b); RNAPII-matched focal/control contacts and profiles: the Pol2 group in fig4_inspect_covariate_results_v2.ipynb (c); U2OS RNAPII by post-UV TAD strength: final section of fig2_rework_Q.ipynb (d); MRC5 RNAPII projected onto IMR90 TADs: imr90.ipynb (e); HeLa contacts, RNA-seq, RNAPII and XR-seq: hela.ipynb (f; quartile-setting difference noted below).
Fig. 6g	Zoomed WT contact-distance fold changes after UV relative to untreated WT: cis_decay_upperlimit.ipynb, WT fold-change section. Uses a 2-Mb upper distance limit (currently 100 kb–2 Mb) and exports figs/decay/cis_foldchange_wt_thresh.svg. This panel uses experimental Hi-C data.
Extended Data 1a–e	Cis/trans proportions and chromosome-pair enrichment: genova_trans.R → trans.ipynb (a); replicate SCC: scc.ipynb (b); genotype/timecourse decay: cis_decay.ipynb (c); eigenvector concordance and compartment strength: compartments.ipynb (d–e). calc_map_res.ipynb provides supporting resolution QC.
Extended Data 2a–d	Same-arm cis, arm-to-arm and trans compartment saddle maps across genotypes/timepoints: saddle.ipynb, supported by compartments.ipynb.
Extended Data 3a–e	Per-condition TAD strength: tads.ipynb (a); biological-replicate TAD strength: tads_reps.ipynb (b); quartile pileups, UV fold changes, strength, compartment identity and TAD lengths: fig2_rework_Q.ipynb (c–e).
Extended Data 4a–c	Unstratified damage, XPC, CTCF and ATAC profiles across preserved TADs/loops and separated boundaries/anchors, including experimental versus sequence-simulated CPD profiles: fig2_rework.ipynb.
Extended Data 5a–h	Repair synthesis, knockdown validation and repair-factor recruitment; wet-lab/microscopy analyses are outside this repository's documented scope.
Extended Data 6a–d	Genome-wide XPC–CTCF proximity: fig4.ipynb (a–b); matching balance and covariate distributions: fig4_inspect_covariate_results_v2.ipynb (c–d).
Extended Data 7a–e	DLD-1 TADs grouped by RNAPII-depleted TAD strength, control/fold-change contact maps, RNAPII mean/median profiles and body-to-flank enrichment: pol2_degron_tad_q.ipynb.
Extended Data 8	Focal/control contact maps, paired covariate diagnostics and insulation/RNAPII/XPC/CTCF profiles across matching groups: fig4_inspect_covariate_results_v2.ipynb.
Extended Data 10a	Baseline WT observed/expected contact pileups for divergent, tandem and convergent CTCF site pairs: stripes.ipynb, top row of the orientation grid. Uses motif-associated CTCF sites shared across WT untreated, WT 3 h and XPC-knockout untreated cells, with same-arm pair separations of 100 kb–1 Mb. Exports figs/stripes/ctcf_stripes_orientation_grid.svg; the other rows contain the UV and XPC-knockout contrasts for Extended Data 10b–c.

Hi-C feature preparation: 3d_prep/

These scripts read prepared .mcool files through ggner_3d.cm and write feature tables consumed by the notebooks. Most use the CNV-corrected sweight column.

Script	Purpose and figure use
expected.py	Calculates distance-dependent cis expected contacts, with chromosome/arm selection and optional trans expectations. Supports decay, saddle and pileup analyses throughout Figs. 1–5 and Extended Data 1–4, 6–8.
expected_reps.py	Calculates the same expected-contact tables for individual biological replicates; supports Extended Data 3b.
compartment.py	Calculates GC-phased eigenvectors at 100 kb, preparing reference GC content if needed; supports Fig. 1c–d and Extended Data 1d–e, 2.
insulation.py	Calculates insulation scores and boundary calls at 10 kb over several window sizes; supplies TAD and boundary analyses throughout the figures.
insulation_reps.py	Calculates replicate-level insulation at 10 kb with a 500-kb window; supports Extended Data 3b.
dots.py	Calls significant loop pixels at 10 kb using arm-level expected contacts; supports Fig. 1g, Fig. 2b, Fig. 3b–c/e and Extended Data 4.

Notebook inventory: notebooks/

Figure analyses and quality control

Notebook	Purpose / figure reference
calc_map_res.ipynb	Checks whether at least 80% of bins reach 1,000 contacts; currently checks 10 kb. Supporting Hi-C QC for Extended Data 1.
scc.ipynb	Computes HiCRep stratum-adjusted correlations between contact maps and plots replicate concordance (Extended Data 1b).
trans.ipynb	Plots GENOVA chromosome-pair enrichment and balanced cis/trans contact fractions (Extended Data 1a).
cis_decay.ipynb	Plots contact probability, its slope and within-genotype UV fold changes (Fig. 1b; Extended Data 1c).
compartments.ipynb	Inspects eigenvectors chromosome by chromosome, excludes unreliable assignments, and plots eigenvector correlations, saddles and strength profiles (Fig. 1c–d; Extended Data 1d–e, 2).
saddle.ipynb	Compares compartment-ranked contacts across genomic distance scales, chromosome arms and chromosomes; includes genotype contrasts and external-data options (Extended Data 2; related Fig. 1c–d / Extended Data 1e analyses).
tads.ipynb	Compares boundary strength, aggregate TAD contacts, domain scores and compartment-stratified TAD strength (Fig. 1e–f; Extended Data 3a).
tads_reps.ipynb	Compares replicate domain scores over a common WT untreated TAD set (Extended Data 3b).
loops.ipynb	Counts shared and condition-specific WT loops and anchors before/after UV (Fig. 1g).
fig2_rework_Q.ipynb	Groups TADs by 3-h strength, assigns and downsamples contained loops, and plots chromatin/repair profiles, quartile metrics and contact pileups (Fig. 2a–b; Extended Data 3c–e). Its final RNAPII panel also supports Fig. 5d.
fig2_rework.ipynb	Profiles unstratified preserved TADs/loops and their separate boundaries/anchors, including experimental and simulated damage (Extended Data 4a–c).
fig3.ipynb	Integrates genotype-specific TAD/loop pileups, loop enrichment scores, overlap counts and CTCF/ATAC metaprofiles (Fig. 3a–e); also explores XPA and quartile comparisons.
fig4.ipynb	Plots observed/permuted XPC-to-CTCF summit distances and ECDFs at boundaries and genome-wide; additionally examines promoter overlap (Fig. 4a–b; Extended Data 6a–b).
prepare_covariate_df.ipynb	Builds 10-kb tables combining insulation, CTCF peaks/signal, XPC, ATAC, histone marks, compartment identity, damage and RNAPII for covariate matching (Fig. 4c–e, Fig. 5c; Extended Data 6c–d, 8).
fig4_inspect_covariate_results_v2.ipynb	Evaluates matching balance, compares CTCF/insulation distributions, and assembles focal/control pileups with paired covariate and signal profiles (Fig. 4d–e, Fig. 5c; Extended Data 6c–d, 8).
phace_index.ipynb	Plots precomputed XPC/CTCF PHACE partner rankings, protein classes and contributing species counts (Fig. 4g).
degron_pol2_analysis.ipynb	Reanalyses DLD-1 RNAPII-degron Micro-C: expected contacts, insulation, TADs, RNAPII/CTCF/cohesin profiles, decay and compartments. Preparation/exploration supporting Fig. 5a–b and Extended Data 7.
fig5_fc_boundaries.ipynb	Compares boundary-centred contact fold changes after RNAPII depletion, XPC knockout and UV irradiation (Fig. 5a).
fig5_degron_ctcf.ipynb	Profiles CTCF across TADs preserved between control and RNAPII-depleted cells (Fig. 5b; this is RNAPII depletion, despite the filename).
fig5_pol2_u2os.ipynb	Profiles untreated U2OS RNAPII across TADs grouped by UV-induced strength change; an alternate Fig. 5d analysis. Use fig2_rework_Q.ipynb for the manuscript's post-UV-strength grouping.
imr90.ipynb	Calls/scores IMR90 TADs and projects pre-/post-UV MRC5 RNAPII signal onto TAD-strength quartiles (Fig. 5e).
hela.ipynb	Integrates HeLa pre-/12-min-post-UV TAD contacts with RNA-seq, RNAPII and XR-seq (Fig. 5f). Currently uses strength-change quartiles; the manuscript's absolute 12-min-strength grouping remains as a commented alternative.
pol2_degron_tad_q.ipynb	Groups DLD-1 TADs by depleted-state strength and plots contact changes, baseline RNAPII profiles and body-to-flank enrichment (Extended Data 7a–e).
cis_decay_upperlimit.ipynb	Plots WT post-UV contact-distance fold changes up to 2 Mb (Fig. 6g). Also explores distance bounds and normalisation for knockout, RNAPII-degron (related to Fig. 6a) and HeLa datasets.
stripes.ipynb	Assigns CTCF motif orientations and plots baseline WT contact pileups for divergent, tandem and convergent site pairs (Extended Data 10a), alongside UV and XPC-knockout fold changes (Extended Data 10b–c).

Processing and supporting scripts: scripts/

Script(s)	Purpose / figure reference
atacseq_nfcore/run_nf.sh	Launches nf-core/atacseq; the folder includes WT/XPC sample sheets (ATAC inputs for Figs. 2–4 and Extended Data 4, 6, 8).
atacseq_nfcore/atac_rpgc.sh	Converts ATAC alignments to RPGC bigWigs with configurable filtering, smoothing and optional Tn5 shifting.
ctcf_chipseq_nfcore/run_nf.sh	Launches nf-core/chipseq for CTCF using the included sample sheet (Figs. 2–4; Extended Data 4, 6, 8).
ctcf_chipseq_nfcore/run_bw.sh	Generates CTCF RPGC coverage and SES-normalised log2 ChIP/input tracks.
xpc_chipseq_nfcore/run_nf.sh	Launches nf-core/chipseq for XPC using xpc_spreadsheet.csv (Figs. 2, 4–5; Extended Data 4, 6, 8).
xpc_chipseq_nfcore/rpgc.sh	Generates XPC RPGC bigWigs and timepoint-matched WT/KO log2-ratio tracks, handling paired-/single-end libraries.
rnaseq_nfcore/run_nf.sh	Launches nf-core/rnaseq for the HeLa UV timecourse using the included sample sheet (Fig. 5f).
rnaseq_nfcore/bigwig.sh	Generates CPM bigWigs from existing merged, duplicate-marked, sorted HeLa BAMs (Fig. 5f).
genova_trans.R	Calculates chromosome-pair log2 observed/expected contacts with GENOVA at 1 Mb and exports RDS/TSV matrices for trans.ipynb (Extended Data 1a).
xpc_ctcf_null_autosomesX_dynamic.sh	Permutes XPC summits within chromosome- and ATAC-intensity-matched accessible regions, optionally restricted to boundary windows; exports nearest-CTCF distances and null summaries (Fig. 4a–b; Extended Data 6a–b).
xpc_ctcf_grid_search.R	Uses nullranges matching to search high-/low-XPC thresholds and retained focal fractions; exports balance diagnostics and the selected matched dataset (Fig. 4c–e, Fig. 5c; Extended Data 6c–d, 8).
run_grid_search.sh	Runs that R search for RNAPII, ATAC and individual histone-mark covariates, organising outputs by insulation window.

Each nf-core folder also contains a short readme.md describing its launcher and track-generation scripts.

Shared Python helpers: src/ggner_3d/

Module	Purpose
cm.py	Registers merged/replicate contact-map paths, opens cooler connections, checks weights, creates chromosome/arm views, loads expected/eigenvector/loop tables, and exports scaled contact maps.
boundaries.py	Constructs TADs, matches preserved boundaries, computes domain strength, assigns compartment signal, extracts insulation profiles and aggregates TAD-to-TAD contacts.
dots_common.py	Matches loops/anchors between conditions within a coordinate tolerance and retains their strength annotations.
loop_helpers.py	Reformats matched-loop coordinates and plots shared/specific loop and anchor counts.
bbi_helpers.py	Extracts bigWig signal matrices over genomic regions, with replicate averaging and quartile summaries.
saddle.py	Calculates parallel cis/trans saddles with distance restrictions and chromosome-arm interaction summaries.
saddle_mp.py	Aggregates cis contacts between interval categories, such as TAD-strength quartiles.
plotting.py	Provides shared styles, saddle/strength plots, triangular contact maps and signal metaprofiles with flanking regions.
init.py	Package marker and description.

Working with the analyses

1. Restore the Python/R environments described above and obtain the relevant contact maps, genomic tracks, peak sets and annotations.
2. Update local paths in src/ggner_3d/cm.py, notebook setup cells and scripts. Paths under /home/carlos/oldies/, /home/carlos/Clone/ and /cta/users/vkaya/, SLURM settings and conda/micromamba environments reflect the original analysis machines.
3. Prepare expected contacts, compartments, insulation and loops with 3d_prep/, then open the notebook for the figure of interest. Expected-contact resolution and chromosome/arm grouping must match the consumer; for example, dots.py needs arm-level expectations, whereas expected.py currently defaults to chromosome-level expectations. Replicate analyses require the corresponding replicate tables.
4. For covariate analyses, prepare the feature table, run the R matching search, then inspect/plot its exported tables. The launcher retains historical src/r_scripts/ input paths, which must be pointed at the prepared tables.

Data availability

Please see the data availability statement in the manuscript for details on how to access the datasets used in this study.

Contact

Please email vogulcan@sabanciuniv.edu or raise an issue in the github repository with any questions about installation or usage.