Package: py-ard
py-ardSwiss army knife ofHLANomenclaturepy-ardis ARD reduction for HLA in PythonHuman leukocyte antigen (HLA) genes encode cell surface proteins that are important for immune regulation. Exons
encoding the Antigen Recognition Domain (ARD) are the most polymorphic region of HLA genes and are important for
donor/recipientHLA matching.
The history of allele typing methods has played a major role in determining resolution and ambiguity of reported HLA
values. Although
HLAnomenclaturehas not
always conformed to the same standard, it is now defined
byThe WHO Nomenclature Committee for Factors of the HLA System.py-ardis aware of the variation in historical resolutions and grouping and is able to translate from one representation to
another based on alleles published quarterly byIPD/IMGT-HLA.Table of ContentsInstallationInstall From PyPiInstall With HomebrewInstall From SourceUsingpy-ardUsingpy-ardfrom PythonUsingpy-ardfrom RPerform ReduxtionDRBX blendingExpand/Lookup MACCommand Line Toolspyard-importImport Reference Datapyard-statusShow Statuses of DatabasespyardReduxpyard-csv-reduceBatch Mode Reduxpy-ardREST WebserviceDocker DeploymentInstallationpy-ardworks with Python 3.8 and higher.Install from PyPipipinstallpy-ardNote: Withpy-ardversion1.0.0and higher, the redux API has changed. If your use requires the older API, please
install withpip install py-ard==0.9.2Install With HomebrewOn macOS,py-ardcan be installed using Homebrew package manager.
This is very handy for using the command line versions of the tool without having to create virtual environments.First time, you'd need to tap thenmdp-bioinformaticstap.brewtapnmdp-bioinformatics/tapInstallpy-ardbrewinstallpy-ardHomebrew will notify you as new versions ofpy-ardare released.Install from sourcepython3-mvenvvenvsourcevenv/bin/activate

pythonsetup.pyinstallSeeOur Contribution Guidefor open source contribution topy-ard.Usingpy-ardUsingpy-ardfrom Python codepy-ardcan be used in a program to reduce/expand HLA GL String representation. If pyard discovers an invalid Allele,
it'll throw an Invalid Exception, not silently return an empty result.Initializepy-ardImportpyardpackage.importpyardInitializeARDobject with a version of IMGT HLA databaseimportpyardard=pyard.init('3510')When processing a large numbers of typings, it's helpful to have a cache of previously calculated reductions to make
similar typings reduce faster. The cache size of pre-computed reductions can be changed from the default of 1,000 by
settingcache_sizeargument. This increases the memory footprint but will significantly increase the processing times
for large number of reductions.importpyardmax_cache_size=1_000_000ard=pyard.init('3510',cache_size=max_cache_size)By default, the IPD-IMGT/HLA data is stored locally in$TMPDIR/pyard. This may be removed when your computer restarts.
You can specify a different, more permanent directory for the cached data.importpyard.ardard=pyard.init('3510',data_dir='/tmp/py-ard')As MAC data changes frequently, you can choose to refresh the MAC code for current IMGT HLA database version.ard.refresh_mac_codes()The default initialization is to use the latest version of IPD-IMGT/HLA database.importpyardard=pyard.init()You can check the current version of IPD-IMGT/HLA database.ard.get_db_version()Reduce TypingsNote: Previous to version of 1.0.0 release ofpy-ard, there wasreduxandredux_glmethods onard. They have
been consolidated so thatreduxhandles both GL Strings and individual alleles.Reduce a single locus HLA Typing by specifying the allele/MAC/XX code and the reduction method toreduxmethod.allele="A*01:01:01"ard.redux(allele,'G')# >>> 'A*01:01:01G'ard.redux(allele,'lg')# >>> 'A*01:01g'ard.redux(allele,'lgx')# >>> 'A*01:01'Reduce an ambiguous GL String# Reduce GL String#ard.redux("A*01:01/A*01:01N+A*02:AB^B*07:02+B*07:AB","G")# 'B*07:02:01G+B*07:02:01G^A*01:01:01G+A*02:01:01G/A*02:02'You can also reduce serology based typings.ard.redux('B14','lg')# >>> 'B*14:01g/B*14:02g/B*14:03g/B*14:04g/B*14:05g/B*14:06g/B*14:08g/B*14:09g/B*14:10g/B*14:11g/B*14:12g/B*14:13g/B*14:14g/B*14:15g/B*14:16g/B*14:17g/B*14:18g/B*14:19g/B*14:20g/B*14:21g/B*14:22g/B*14:23g/B*14:24g/B*14:25g/B*14:26g/B*14:27g/B*14:28g/B*14:29g/B*14:30g/B*14:31g/B*14:32g/B*14:33g/B*14:34g/B*14:35g/B*14:36g/B*14:37g/B*14:38g/B*14:39g/B*14:40g/B*14:42g/B*14:43g/B*14:44g/B*14:45g/B*14:46g/B*14:47g/B*14:48g/B*14:49g/B*14:50g/B*14:51g/B*14:52g/B*14:53g/B*14:54g/B*14:55g/B*14:56g/B*14:57g/B*14:58g/B*14:59g/B*14:60g/B*14:62g/B*14:63g/B*14:65g/B*14:66g/B*14:68g/B*14:70Qg/B*14:71g/B*14:73g/B*14:74g/B*14:75g/B*14:77g/B*14:82g/B*14:83g/B*14:86g/B*14:87g/B*14:88g/B*14:90g/B*14:93g/B*14:94g/B*14:95g/B*14:96g/B*14:97g/B*14:99g/B*14:102g'Valid Reduction TypesReduction TypeDescriptionGReduce to G Group LevelPReduce to P Group LevellgReduce to 2 field ARD level (appendg)lgxReduce to 2 field ARD levelWReduce/Expand to full field(4,3,2) WHO nomenclature levelexonReduce/Expand to 3 field levelU2Reduce to 2 field unambiguous levelSReduce to Serological levelPerform DRB1 blending with DRB3, DRB4 and DRB5importpyardpyard.dr_blender(drb1='HLA-DRB1*03:01+DRB1*04:01',drb3='DRB3*01:01',drb4='DRB4*01:03')# >>> 'DRB3*01:01+DRB4*01:03'MAC Codespy-ardsupports not only reducing to various types but helps in expanding and
looking up MAC representation. SeeMAC Service UIfor detail.Expand MACYou can also usepy-ardto expand MAC codes. Useexpand_macmethod onard.ard.expand_mac('HLA-A*01:BC')# 'HLA-A*01:02/HLA-A*01:03'Lookup MACFind the corresponding MAC code for an allele list GL String.ard.lookup_mac('A*01:02/A*01:01/A*01:03')# A*01:MNCWD ReductionReduce a MAC code or an allele list GL String to CWD reduced list.ard.cwd_redux("B*15:01:01/B*15:01:03/B*15:04/B*15:07/B*15:26N/B*15:27")# => B*15:01/B*15:07The above 2 methods can be chained to get back a MAC code that has a CWD reduced version.ard.lookup_mac(ard.cwd_redux("B*15:01:01/B*15:01:03/B*15:04/B*15:07/B*15:26N/B*15:27"))# 'B*15:AH'Usingpy-ardfrom R codepy-ardworks well fromRas well. Please
seeUsing pyard from R languagepage for detailed walkthrough.Command Line ToolsVarious command line interface (CLI) tools are available to use for managing local IPD-IMGT/HLA cache database, running
impromptu reduction queries and batch processing of CSV files.For all tools, use--imgt-versionand--data-dirto specify the IPD-IMGT/HLA database version and the directory
where the SQLite files are created.pyard-importImport the latest IPD-IMGT/HLA databasepyard-importhelps with importing and reinstalling of prepared IPD-IMGT/HLA and MAC data.Usepyard-import -hto see all the options available.$pyard-import-h
usage:pyard-import[-h][--list][-iIMGT_VERSION][-dDATA_DIR][--v2-to-v3-mappingV2_V3_MAPPING][--refresh-mac][--re-install][--skip-mac]py-ardtooltogeneratereferenceSQLitedatabase.AllowsupdatingdbwithcustomV2toV3mappings.DisplaysthelistofavailableIMGTdatabase
versions.

options:-h,--helpshowthishelpmessageandexit--listShowVersionsofavailableIMGTDatabases-iIMGT_VERSION,--imgt-versionIMGT_VERSIONImportsuppliedIMGT_VERSIONDBVersion-dDATA_DIR,--data-dirDATA_DIRDatadirectorytostoreimporteddata--v2-to-v3-mappingV2_V3_MAPPINGV2toV3mappingCSVfile--refresh-macOnlyrefreshMACdata--re-installreinstallafreshversionofdatabase--skip-macSkipcreatingMACmappingRunpyard-importwithout any option to download and prepare the latest version of IPD-IMGT/HLA and MAC data.$pyard-import
CreatedLatestpy-arddatabaseImport particular version of IMGT database$pyard-import--db-version3.29.0
Createdpy-ardversion3290databaseImport particular version of IMGT database and replace the v2 to v3 mapping
table from a CSV file.$pyard-import--imgt-version3.29.0--v2-to-v3-mappingmap2to3.csv
Createdpy-ardversion3290database
Updatedv2_mappingtablewith'map2to3.csv'mappingfile.Reinstall a particular IMGT databasepyard-import--imgt-version3340--re-installReplace the Latest IMGT database with V2 mappings$pyard-import--v2-to-v3-mappingmap2to3.csvRefresh the MAC for the specified version$pyard-import--imgt-version3450--refresh-macSkip MAC loadingYou can skip loading MAC if you don't need by using--skip-mac$pyard-import--imgt-version3150--skip-macpyard-statusShow database statusShow the statuses of allpy-arddatabasespyard-statusgoes through all the available databases and checks all the tables that should be available. This is very
helpful to show all the databases, number of rows in each table, any missing tables and the stored IPD-IMGT/HLA version.$pyard-statusUse--data-dirto specify an alternate directory for cached database files.$pyard-status--data-dir~/.pyard/
IMGTDBVersion:Latest(3440)ThereisanewerIMGTreleasethanversion3440Upgradetolatestversion'3510'with'pyard-import --re-install'File:/Users/pbashyal/.pyard/pyard-Latest.sqlite3
Size:533.37MB
-------------------------------------------|TableName|Rows||-----------------------------------------||dup_g|59||dup_lgx|1||g_group|14223||p_group|18872||lgx_group|14223||exon_group|12934||p_not_g|1681||xx_codes|1517||who_group|30785||alleles|32504||exp_alleles|60||who_alleles|30523||mac_codes|1089379|-------------------------------------------pyardRedux quicklypyardcommand can be used for quick reductions from the command line. Use--helpoption to see all the available
options.$pyard--help
usage:pyard[-h][-v][-dDATA_DIR][-iIMGT_VERSION][-gGL_STRING][-r{G,P,lg,lgx,W,exon,U2}][--splitsSPLITS]py-ardtooltoreduxGLString

options:-h,--helpshowthishelpmessageandexit-v,--versionIPD-IMGT/HLADBVersionnumber-dDATA_DIR,--data-dirDATA_DIRDatadirectorytostoreimporteddata-iIMGT_VERSION,--imgt-versionIMGT_VERSIONIPD-IMGT/HLAdbtouseforredux-gGL_STRING,--glGL_STRINGGLStringtoreduce-r{G,P,lg,lgx,W,exon,U2},--redux-type{G,P,lg,lgx,W,exon,U2}ReductionMethod--splitsSPLITSFindBroadandSplitsReduce from command line by specifying any typing with-gor--gloption and the reduction method with-ror--redux-typeoption.$pyard-g'A*01:AB'-rlgx
A*01:01/A*01:02

$pyard--gl'DRB1*08:XX'-rG
DRB1*08:01:01G/DRB1*08:02:01G/DRB1*08:03:02G/DRB1*08:04:01G/DRB1*08:05/...

$pyard-i3290--gl'A1'-rlgx# For a particular version of DBA*01:01/A*01:02/A*01:03/A*01:06/A*01:07/A*01:08/A*01:09/A*01:10/A*01:12/...If the-roption is left out,pyardwill print out the result of all reduction methods.$pyard-g'A*01:01:01:01'ReductionMethod:G
-------------------
A*01:01:01G

ReductionMethod:P
-------------------
A*01:01P

ReductionMethod:lg
--------------------
A*01:01g

ReductionMethod:lgx
---------------------
A*01:01

ReductionMethod:W
-------------------
A*01:01:01:01

ReductionMethod:exon
----------------------
A*01:01:01

ReductionMethod:U2
--------------------
A*01:01py-ardknows about the broad/splits of serology and DNA, you can find by using--splitsoption topyardcommand.$pyard--splits"A*10"A*10=A*25/A*26/A*34/A*66

$pyard--splitsB14B14=B64/B65pyard-csv-reduceBatch Reduce a CSV filepyard-csv-reducecan be used to batch process a CSV file with HLA typings. Seedocumentationfor
detailed information about all the options.py-ardREST Web ServiceRunpy-ardas a service so that it can be accessed as a REST service endpoint.To start in debug mode, you can run theapp.pyscript. The endpoint should then be available
atlocalhost:8080$pythonapp.py*ServingFlaskapp'app'*Debugmode:on
WARNING:Thisisadevelopmentserver.Donotuseitinaproductiondeployment.UseaproductionWSGIserverinstead.*Runningonalladdresses(0.0.0.0)*Runningonhttp://127.0.0.1:8080*Runningonhttp://10.0.1.37:8080
PressCTRL+CtoquitDocker deployment of py-ard REST Web ServiceFor deploying to production, build a Docker image and use that image for deploying to a server.Build the docker image:makedocker-buildbuilds a Docker image namedpyard-service:latestBuild the docker and run it with:makedockerThe endpoint should then be available atlocalhost:8080