ipaapi

Stable — in daily production use against live IPA

pip install ipaapi

01 / Problem

Why it exists

02 / Use

Check the mapping, then submit

Say your file has a comment line, then a header, then data:

# generated by pipeline v3
Gene,Common_name,Control_mean,Treatment_mean,Fold_change,P-value
ENSG00000229807,XIST,4.21,2.88,-1.33,0.001

validate contacts nothing and uploads nothing — it reads the file, applies your column choices, and shows you what IPA would receive:

ipaapi validate results.csv --ID 1:hugo --FC 4:logratio --skip-rows 1

results: 2,338 rows
gene id: 'Common_name' (hugo)
observations: 1
  results:
    'Fold_change' -> Log Ratio

When it looks right, submit — and if it is a folder, submit all of it:

ipaapi submit ~/experiment --pattern _DEG --ID 1:hugo --FC 4:logratio \
    --skip-rows 1 --reference-set ipkb --project MyStudy

Column positions are counted from the header row and are zero-based. Columns can be in any order, named anything, with anything you don't need in between.

03 / Behavior

What it handles so you don't have to

Most of what follows is undocumented. All of it was found by submitting real data and working backwards from the results.

• Values silently discarded. IPA expects each measurement type to fall in a particular range — fold change never lies between −1 and 1, for instance. Values outside the range are dropped without comment, so a log₂ column declared as linear fold change produces an analysis built on the handful of genes that happened to qualify. It looks like it worked. ipaapi checks every value against its declared type before uploading and tells you what is wrong, and usually what you meant instead.
• Identifier types that aren't what you'd guess. Human gene symbols are hugo. Not genesymbol, not hgnc, not Gene Symbol — all of which are rejected. There are 33 accepted values; ipaapi --list-id-types prints them. Species is carried by the identifier type rather than set separately.
• Errors that arrive as a web page. IPA answers a failed submission with HTTP 200 and an HTML page reading "The page you are looking for is currently unavailable." At least three unrelated problems produce that exact page: a duplicate dataset name, an observation name past about 65 characters, and an actual outage. ipaapi tells them apart, prevents the first two before you hit them, and says which one it thinks you have.
• Analysis allowances that run out mid-batch. IPA licenses cap how many analyses you may run. Hit the limit twenty files into a run of forty and ipaapi stops, files what succeeded into submitted/, and leaves the rest where they are. Re-run the same command tomorrow and it picks up exactly where it stopped.
• No way to list your own analyses. The API offers no query for the analyses you have submitted, so an ID you didn't write down is gone. ipaapi keeps a timestamped log of every submission — ipaapi history gives them back, with current status.
• Column layouts that don't match the demo. QIAGEN's example code assumes the identifier sits in column 0 followed by value columns in a strict repeating order. ipaapi replaces that with a declaration, so real pipeline output works unmodified. A second identifier column can fill rows where the first is blank.

04 / Install

Getting it running

pip install ipaapi
ipaapi --help

05 / Status

What is settled and what is not

• Interpret links (ipaapi report) have returned HTTP 500 for analyses that completed successfully. Cause unconfirmed — possibly a commercial add-on license.
• Programmatic result retrieval needs that same add-on and is largely untested.
• The documented rule for choosing a reference set does not match observed behavior. Set --reference-set explicitly rather than relying on the default.

Bug reports and pull requests are welcome on GitHub. If IPA rejects something and the message doesn't explain why, that is worth reporting — most of what this package knows was learned that way.

06 / Citation

License, citation and source

ipaapi is an independent project. It is not affiliated with, endorsed by, or supported by QIAGEN. Ingenuity Pathway Analysis is QIAGEN's product and requires a license from them. This package builds on their published python-api-demo example code.