|
492
|
1 # Troubleshooting
|
|
|
2
|
|
|
3 Common issues and solutions when using COBRAxy.
|
|
|
4
|
|
|
5 ## Installation Issues
|
|
|
6
|
|
542
|
7 ### Missing Build Tools
|
|
|
8
|
|
|
9 **Problem**: `gcc: command not found` or compilation errors (Linux/macOS)
|
|
|
10 ```bash
|
|
|
11 # Ubuntu/Debian
|
|
|
12 sudo apt-get install build-essential cmake pkg-config
|
|
|
13
|
|
|
14 # macOS
|
|
|
15 xcode-select --install
|
|
|
16 brew install cmake pkg-config
|
|
|
17 ```
|
|
|
18
|
|
|
19 **Problem**: `CMake not found`
|
|
|
20 ```bash
|
|
|
21 # Ubuntu/Debian
|
|
|
22 sudo apt-get install cmake
|
|
|
23
|
|
|
24 # macOS
|
|
|
25 brew install cmake
|
|
|
26
|
|
|
27 # Or via conda
|
|
|
28 conda install -c conda-forge cmake
|
|
|
29 ```
|
|
|
30
|
|
492
|
31 ### Python Import Errors
|
|
|
32
|
|
|
33 **Problem**: `ModuleNotFoundError: No module named 'cobra'`
|
|
|
34 ```bash
|
|
542
|
35 # Solution: Reinstall COBRAxy with dependencies
|
|
|
36 cd COBRAxy/src
|
|
|
37 pip install .
|
|
492
|
38
|
|
542
|
39 # Or install missing dependency directly
|
|
|
40 pip install cobra
|
|
492
|
41 ```
|
|
|
42
|
|
|
43 **Problem**: `ImportError: No module named 'cobraxy'`
|
|
|
44 ```python
|
|
542
|
45 # Solution: Ensure COBRAxy is installed
|
|
|
46 pip install /path/to/COBRAxy/src/
|
|
|
47
|
|
|
48 # Or add to Python path temporarily
|
|
492
|
49 import sys
|
|
542
|
50 sys.path.insert(0, '/path/to/COBRAxy/src')
|
|
492
|
51 ```
|
|
|
52
|
|
|
53 ### System Dependencies
|
|
|
54
|
|
|
55 **Problem**: GLPK solver not found
|
|
|
56 ```bash
|
|
|
57 # Ubuntu/Debian
|
|
|
58 sudo apt-get install libglpk40 glpk-utils
|
|
|
59 pip install swiglpk
|
|
|
60
|
|
|
61 # macOS
|
|
|
62 brew install glpk
|
|
|
63 pip install swiglpk
|
|
|
64
|
|
|
65 # Windows (using conda)
|
|
|
66 conda install -c conda-forge glpk swiglpk
|
|
|
67 ```
|
|
|
68
|
|
|
69 **Problem**: SVG processing errors
|
|
|
70 ```bash
|
|
|
71 # Install libvips for image processing
|
|
|
72 # Ubuntu/Debian: sudo apt-get install libvips
|
|
|
73 # macOS: brew install vips
|
|
|
74 ```
|
|
|
75
|
|
|
76 ## Data Format Issues
|
|
|
77
|
|
|
78 ### Gene Expression Problems
|
|
|
79
|
|
|
80 **Problem**: "No computable scores" error
|
|
|
81 ```
|
|
|
82 Cause: Gene IDs don't match between data and model
|
|
|
83 Solution:
|
|
|
84 1. Check gene ID format (HGNC vs symbols vs Ensembl)
|
|
|
85 2. Verify first column contains gene identifiers
|
|
|
86 3. Ensure tab-separated format
|
|
|
87 4. Try different built-in model
|
|
|
88 ```
|
|
|
89
|
|
|
90 **Problem**: Many "gene not found" warnings
|
|
|
91 ```python
|
|
|
92 # Check gene overlap with model
|
|
|
93 import pickle
|
|
542
|
94 genes_dict = pickle.load(open('src/local/pickle files/ENGRO2_genes.p', 'rb'))
|
|
492
|
95 model_genes = set(genes_dict['hugo_id'].keys())
|
|
|
96
|
|
|
97 import pandas as pd
|
|
|
98 data_genes = set(pd.read_csv('expression.tsv', sep='\t').iloc[:, 0])
|
|
|
99
|
|
|
100 overlap = len(model_genes.intersection(data_genes))
|
|
|
101 print(f"Gene overlap: {overlap}/{len(data_genes)} ({overlap/len(data_genes)*100:.1f}%)")
|
|
|
102 ```
|
|
|
103
|
|
|
104 **Problem**: File format not recognized
|
|
|
105 ```tsv
|
|
|
106 # Correct format - tab-separated:
|
|
|
107 Gene_ID Sample_1 Sample_2
|
|
|
108 HGNC:5 10.5 11.2
|
|
|
109 HGNC:10 3.2 4.1
|
|
|
110
|
|
|
111 # Wrong - comma-separated or spaces will fail
|
|
|
112 ```
|
|
|
113
|
|
|
114 ### Model Issues
|
|
|
115
|
|
|
116 **Problem**: Custom model not loading
|
|
|
117 ```
|
|
|
118 Solution:
|
|
|
119 1. Check TSV format with "GPR" column header
|
|
|
120 2. Verify reaction IDs are unique
|
|
|
121 3. Test GPR syntax (use 'and'/'or', proper parentheses)
|
|
|
122 4. Check file permissions and encoding (UTF-8)
|
|
|
123 ```
|
|
|
124
|
|
|
125 ## Tool Execution Errors
|
|
|
126
|
|
|
127
|
|
|
128
|
|
|
129 ### File Path Problems
|
|
|
130
|
|
|
131 **Problem**: "File not found" errors
|
|
|
132 ```python
|
|
|
133 # Use absolute paths
|
|
|
134 from pathlib import Path
|
|
|
135
|
|
|
136 tool_dir = str(Path('/path/to/COBRAxy').absolute())
|
|
|
137 input_file = str(Path('expression.tsv').absolute())
|
|
|
138
|
|
|
139 args = ['-td', tool_dir, '-in', input_file, ...]
|
|
|
140 ```
|
|
|
141
|
|
|
142 **Problem**: Permission denied
|
|
|
143 ```bash
|
|
|
144 # Check write permissions
|
|
|
145 ls -la output_directory/
|
|
|
146
|
|
|
147 # Fix permissions
|
|
|
148 chmod 755 output_directory/
|
|
|
149 chmod 644 input_files/*
|
|
|
150 ```
|
|
|
151
|
|
|
152 ### Galaxy Integration Issues
|
|
|
153
|
|
|
154 **Problem**: COBRAxy tools not appearing in Galaxy
|
|
|
155 ```xml
|
|
|
156 <!-- Check tool_conf.xml syntax -->
|
|
|
157 <section id="cobraxy" name="COBRAxy">
|
|
|
158 <tool file="cobraxy/ras_generator.xml" />
|
|
|
159 </section>
|
|
|
160
|
|
|
161 <!-- Verify file paths are correct -->
|
|
|
162 ls tools/cobraxy/ras_generator.xml
|
|
|
163 ```
|
|
|
164
|
|
|
165 **Problem**: Tool execution fails in Galaxy
|
|
|
166 ```
|
|
|
167 Check Galaxy logs:
|
|
|
168 - main.log: General Galaxy issues
|
|
|
169 - handler.log: Job execution problems
|
|
|
170 - uwsgi.log: Web server issues
|
|
|
171
|
|
|
172 Common fixes:
|
|
|
173 1. Restart Galaxy after adding tools
|
|
|
174 2. Check Python environment has COBRApy installed
|
|
|
175 3. Verify file permissions on tool files
|
|
|
176 ```
|
|
|
177
|
|
|
178
|
|
|
179
|
|
|
180 **Problem**: Flux sampling hangs
|
|
|
181 ```bash
|
|
|
182 # Check solver availability
|
|
|
183 python -c "import cobra; print(cobra.Configuration().solver)"
|
|
|
184
|
|
|
185 # Should show: glpk, cplex, or gurobi
|
|
|
186 # Install GLPK if missing:
|
|
|
187 pip install swiglpk
|
|
|
188 ```
|
|
|
189
|
|
|
190 ### Large Dataset Handling
|
|
|
191
|
|
|
192 **Problem**: Cannot process large expression matrices
|
|
|
193 ```python
|
|
|
194 # Process in chunks
|
|
|
195 def process_large_dataset(expression_file, chunk_size=1000):
|
|
|
196 df = pd.read_csv(expression_file, sep='\t')
|
|
|
197
|
|
|
198 for i in range(0, len(df), chunk_size):
|
|
|
199 chunk = df.iloc[i:i+chunk_size]
|
|
|
200 chunk_file = f'chunk_{i}.tsv'
|
|
|
201 chunk.to_csv(chunk_file, sep='\t', index=False)
|
|
|
202
|
|
|
203 # Process chunk
|
|
|
204 ras_generator.main(['-in', chunk_file, ...])
|
|
|
205 ```
|
|
|
206
|
|
|
207 ## Output Validation
|
|
|
208
|
|
|
209 ### Unexpected Results
|
|
|
210
|
|
|
211 **Problem**: All RAS values are zero or null
|
|
|
212 ```python
|
|
|
213 # Debug gene mapping
|
|
|
214 import pandas as pd
|
|
|
215 ras_df = pd.read_csv('ras_output.tsv', sep='\t', index_col=0)
|
|
|
216
|
|
|
217 # Check data quality
|
|
|
218 print(f"Null percentage: {ras_df.isnull().sum().sum() / ras_df.size * 100:.1f}%")
|
|
|
219 print(f"Zero percentage: {(ras_df == 0).sum().sum() / ras_df.size * 100:.1f}%")
|
|
|
220
|
|
|
221 # Check expression data preprocessing
|
|
|
222 expr_df = pd.read_csv('expression.tsv', sep='\t', index_col=0)
|
|
|
223 print(f"Expression range: {expr_df.min().min():.2f} to {expr_df.max().max():.2f}")
|
|
|
224 ```
|
|
|
225
|
|
|
226 **Problem**: RAS values seem too high/low
|
|
|
227 ```
|
|
|
228 Possible causes:
|
|
|
229 1. Expression data not log-transformed
|
|
|
230 2. Wrong normalization method
|
|
|
231 3. Incorrect gene ID mapping
|
|
|
232 4. GPR rule interpretation issues
|
|
|
233
|
|
|
234 Solutions:
|
|
|
235 1. Check expression data preprocessing
|
|
|
236 2. Validate against known control genes
|
|
|
237 3. Compare with published metabolic activity patterns
|
|
|
238 ```
|
|
|
239
|
|
|
240 ### Missing Pathway Maps
|
|
|
241
|
|
|
242 **Problem**: MAREA generates no output maps
|
|
|
243 ```
|
|
|
244 Debug steps:
|
|
|
245 1. Check RAS input has non-null values
|
|
|
246 2. Verify model choice matches RAS generation
|
|
|
247 3. Check statistical significance thresholds
|
|
|
248 4. Look at log files for specific errors
|
|
|
249 ```
|
|
|
250
|
|
|
251 ## Environment Issues
|
|
|
252
|
|
|
253 ### Conda/Virtual Environment Problems
|
|
|
254
|
|
|
255 **Problem**: Tool import fails in virtual environment
|
|
|
256 ```bash
|
|
|
257 # Activate environment properly
|
|
|
258 source venv/bin/activate # Linux/macOS
|
|
|
259 # or
|
|
|
260 venv\Scripts\activate # Windows
|
|
|
261
|
|
|
262 # Verify COBRAxy installation
|
|
|
263 pip list | grep cobra
|
|
|
264 python -c "import cobra; print('COBRApy version:', cobra.__version__)"
|
|
|
265 ```
|
|
|
266
|
|
|
267 **Problem**: Version conflicts
|
|
|
268 ```bash
|
|
|
269 # Create clean environment
|
|
|
270 conda create -n cobraxy python=3.9
|
|
|
271 conda activate cobraxy
|
|
|
272
|
|
|
273 # Install COBRAxy fresh
|
|
542
|
274 cd COBRAxy/src
|
|
492
|
275 pip install -e .
|
|
|
276 ```
|
|
|
277
|
|
|
278 ### Cross-Platform Issues
|
|
|
279
|
|
|
280 **Problem**: Windows path separator issues
|
|
|
281 ```python
|
|
|
282 # Use pathlib for cross-platform paths
|
|
|
283 from pathlib import Path
|
|
|
284
|
|
|
285 # Instead of: '/path/to/file'
|
|
|
286 # Use: str(Path('path') / 'to' / 'file')
|
|
|
287 ```
|
|
|
288
|
|
|
289 **Problem**: Line ending issues (Windows/Unix)
|
|
|
290 ```bash
|
|
|
291 # Convert line endings if needed
|
|
|
292 dos2unix input_file.tsv # Unix
|
|
|
293 unix2dos input_file.tsv # Windows
|
|
|
294 ```
|
|
|
295
|
|
|
296 ## Debugging Strategies
|
|
|
297
|
|
|
298 ### Enable Detailed Logging
|
|
|
299
|
|
|
300 ```python
|
|
|
301 import logging
|
|
|
302 logging.basicConfig(level=logging.DEBUG)
|
|
|
303
|
|
|
304 # Many tools accept log file parameter
|
|
|
305 args = [..., '--out_log', 'detailed.log']
|
|
|
306 ```
|
|
|
307
|
|
|
308 ### Test with Small Datasets
|
|
|
309
|
|
|
310 ```python
|
|
|
311 # Create minimal test case
|
|
|
312 test_data = """Gene_ID Sample1 Sample2
|
|
|
313 HGNC:5 10.0 15.0
|
|
|
314 HGNC:10 5.0 8.0"""
|
|
|
315
|
|
|
316 with open('test_input.tsv', 'w') as f:
|
|
|
317 f.write(test_data)
|
|
|
318
|
|
|
319 # Test basic functionality
|
|
|
320 ras_generator.main(['-td', tool_dir, '-in', 'test_input.tsv',
|
|
|
321 '-ra', 'test_output.tsv', '-rs', 'ENGRO2'])
|
|
|
322 ```
|
|
|
323
|
|
|
324 ### Check Dependencies
|
|
|
325
|
|
|
326 ```python
|
|
|
327 # Verify all required packages
|
|
|
328 required_packages = ['cobra', 'pandas', 'numpy', 'scipy']
|
|
|
329
|
|
|
330 for package in required_packages:
|
|
|
331 try:
|
|
|
332 __import__(package)
|
|
|
333 print(f"✓ {package}")
|
|
|
334 except ImportError:
|
|
|
335 print(f"✗ {package} - MISSING")
|
|
|
336 ```
|
|
|
337
|
|
|
338 ## Getting Help
|
|
|
339
|
|
|
340 ### Information to Include in Bug Reports
|
|
|
341
|
|
|
342 When reporting issues, include:
|
|
|
343
|
|
|
344 1. **System information**:
|
|
|
345 ```bash
|
|
|
346 python --version
|
|
|
347 pip list | grep cobra
|
|
|
348 uname -a # Linux/macOS
|
|
|
349 ```
|
|
|
350
|
|
|
351 2. **Complete error messages**: Copy full traceback
|
|
|
352 3. **Input file format**: First few lines of input data
|
|
|
353 4. **Command/parameters used**: Exact command or Python code
|
|
|
354 5. **Expected vs actual behavior**: What should happen vs what happens
|
|
|
355
|
|
|
356 ### Community Resources
|
|
|
357
|
|
542
|
358 - **GitHub Issues**: [Report bugs and ask questions](https://github.com/CompBtBs/COBRAxy/issues)
|
|
492
|
359 - **COBRApy Community**: [General metabolic modeling help](https://github.com/opencobra/cobrapy)
|
|
|
360
|
|
|
361 ### Self-Help Checklist
|
|
|
362
|
|
|
363 Before reporting issues:
|
|
|
364
|
|
|
365 - ✅ Checked this troubleshooting guide
|
|
|
366 - ✅ Verified installation completeness
|
|
|
367 - ✅ Tested with built-in example data
|
|
|
368 - ✅ Searched existing GitHub issues
|
|
|
369 - ✅ Tried alternative models/parameters
|
|
|
370 - ✅ Checked file formats and permissions
|
|
|
371
|
|
|
372 ## Prevention Tips
|
|
|
373
|
|
|
374 ### Best Practices
|
|
|
375
|
|
|
376 1. **Use virtual environments** to avoid conflicts
|
|
|
377 2. **Validate input data** before processing
|
|
|
378 3. **Start with small datasets** for testing
|
|
|
379 4. **Keep backups** of working configurations
|
|
|
380 5. **Document successful workflows** for reuse
|
|
|
381 6. **Test after updates** to catch regressions
|
|
|
382
|
|
|
383 ### Data Quality Checks
|
|
|
384
|
|
|
385 ```python
|
|
|
386 def validate_expression_data(filename):
|
|
|
387 """Validate gene expression file format."""
|
|
|
388 df = pd.read_csv(filename, sep='\t')
|
|
|
389
|
|
|
390 # Check basic format
|
|
|
391 assert df.shape[0] > 0, "Empty file"
|
|
|
392 assert df.shape[1] > 1, "Need at least 2 columns"
|
|
|
393
|
|
|
394 # Check numeric data
|
|
|
395 numeric_cols = df.select_dtypes(include=[np.number]).columns
|
|
|
396 assert len(numeric_cols) > 0, "No numeric expression data"
|
|
|
397
|
|
|
398 # Check for missing values
|
|
|
399 null_pct = df.isnull().sum().sum() / df.size * 100
|
|
|
400 if null_pct > 50:
|
|
|
401 print(f"Warning: {null_pct:.1f}% missing values")
|
|
|
402
|
|
|
403 print(f"✓ File valid: {df.shape[0]} genes × {df.shape[1]-1} samples")
|
|
|
404 ```
|
|
|
405
|
|
|
406 This troubleshooting guide covers the most common issues. For tool-specific problems, check the individual tool documentation pages. |
