PHi-C v2.2.1

🔄 Workflow Restructuring

optimization and plot-optimization have been reorganized:

• optimization now also produces C_optimized.npz and P_optimized.npz, which were previously generated by plot-optimization
• Downstream analyses (msd, losstangent) no longer require running plot-optimization first
• plot-optimization now only renders figures by reading the pre-computed arrays from optimization
• The --res option of plot-optimization has been removed (the resolution is now read from P_normalized.npz)

---

⚙️ Auto-determined Spectrum Ranges

msd and losstangent now automatically determine the exponent range from the eigenvalues of the Laplacian matrix induced from the optimized polymer network interaction matrix:

• The --upper and --lower options have been removed
• This eliminates manual tuning and ensures the range covers all relaxation modes

---

📊 Structured Analysis Log (experimental)

Most subcommands (fetch-fileinfo, preprocessing, optimization, plot-optimization, msd, losstangent) now accept --json, --json-path, and --run-uuid options to append a structured analysis log to
phic.json in the workspace:

• Records Hi-C file metadata, runtime profile (host, OS, CPU/GPU, Python environment, package versions), per-subcommand parameters, elapsed time, output file paths, and numerical summaries
• Intended for internal pipeline integration; the schema and detailed usage will be documented in a future release

---

✨ New Options

• preprocessing: --name option to set the output directory name directly
• plot-optimization: --no-figures flag to skip matplotlib figure generation (faster when only the .npz outputs are needed)

---

📦 New Dependencies

• psutil
• hictkpy

---

📖 Documentation

• README updated with descriptions of .npz keys (shape and content) for all outputs, and a description of the columns in optimization.log
• Mol* added as a browser-based alternative to VMD for visualizing the .psf / .dcd outputs

---

PHi-C v2.2.0

⚡ Performance Improvements

Dramatically faster optimization
The optimization algorithm has been completely overhauled:

• Replaced fixed-step gradient descent with a backtracking line search, enabling adaptive step sizes and robust convergence
• Replaced the eigh-based pseudoinverse with a Cholesky decomposition, significantly reducing computation time per step
• New options: --backtracking-factor and --gradient-degree; --learning-rate has been removed

Vectorized MSD and loss tangent computation

• msd and losstangent now use fully vectorized matrix operations instead of per-bead for loops, resulting in orders-of-magnitude speedup for large matrices
• Results are stored in a single compressed .npz file instead of per-bead .txt files

---

🔄 Subcommand Changes

Consolidated rheology subcommands

• Removed: rheology, plot-tangent, plot-compliance, plot-modulus
• Added: losstangent, plot-losstangent

The new losstangent subcommand focuses on the loss tangent (tan δ) spectrum, which is the most informative quantity for characterizing local chromatin dynamics.

---

📁 Output Format Changes

All data output files have been changed from plain text (.txt) to NumPy compressed format (.npz):

• C_normalized.npz, P_normalized.npz
• K_optimized.npz, C_optimized.npz
• MSD_matrix.npz, losstangent_matrix.npz

---

✨ New Features

• dynamics and sampling now additionally output .dcd trajectory files (via MDAnalysis)
• plot-optimization now outputs Eta.svg showing the learning rate trajectory
• Progress bars added to dynamics and sampling via tqdm

---

📦 New Dependencies

• MDAnalysis
• tqdm

---

PHi-C v2.1.3

• Optimized convert_K_into_C and calc_diff_cost functions.
• Improved performance was achieved without using numba, ensuring compatibility and reducing external dependencies.

PHi-C v2.1.2

✨ New Features
Added fetch-fileinfo subcommand
A new utility to inspect the input Hi-C file (.hic or .mcool) and list available chromosomes and resolutions.
This helps users verify file content before running downstream analysis.

🆕 Input Format Support
Support for both .hic and .mcool formats
The following subcommands now accept either .hic or .mcool files:

• fetch-fileinfo
• preprocessing

PHi-C v2.1.0

v2.1.0 – Support for .hic format in preprocessing
✨ New Features
Changed input format to .hic in the preprocessing subcommand.
In version 2.1.0 and later, the input data format must be a .hic file.

🧹 Deprecated / Changed
.txt format inputs used in previous versions are no longer supported in preprocessing.

PHi-C v2.0.13

Add two subcommands msd and plot-msd to calculate and plot the MSD spectrum.

PHi-C v2.0.12

Numba works on nopython=True mode.

PHi-C v2.0.11

Add an option to phic preprocessing for high-resolution case (ex. 1-kb, 500-bp, 200-bp).
phic rheology outputs the 1st normalized frequency ω1.

PHi-C v2.0.10

Update for v2.0.10

PHi-C v2.0.8

Update for v2.0.8