Package: py-graph-match
py-graph-matchMatching with Graph`grma`` is a package for finding HLA matches using graphs approach.
The matching is based ongrim'simputation.Pre-requisitesData Directory Structuredata
├── donors_dir
│   └── donors.txt
├── hpf.csv
└── patients.txtconf Directory Structureconf
└── minimal-configuration.jsonFollow these steps for finding matches:Setup a virtual environment (venv) and run:make installQuick Getting StartedGet Started with a built-in example.Build 'Donors Graph'python test_build_donors_graph.pyFind MatchesUse grma algorthm for finding matches efficiently. You can run the filetest_matching.pypython test_matching.pyFind the match results inresultsdirectory.Full Walk throughBuilding The Donors' Graph:The donors' graph is a graph which contains all the donors (the search space). It implemented using a LOL (List of Lists) representation written in cython for better time and memory efficiency.
The building might take a lot of memory and time, so it's recommended to save the graph in a pickle file.Before building the donors' graph, all the donors' HLAs must be imputed usinggrim.
Then all the imputation files must be saved under the same directory.importosfromgrma.donorsgraph.build_donors_graphimportBuildMatchingGraphPATH_TO_DONORS_DIR="data/donors_dir"PATH_TO_DONORS_GRAPH="output/donors_graph.pkl"os.makedirs(f"output",exist_ok=True)build_matching=BuildMatchingGraph(PATH_TO_DONORS_DIR)graph=build_matching.graph# access the donors' graphbuild_matching.to_pickle(PATH_TO_DONORS_GRAPH)# save the donors' graph to pickleSearch & Match before imputation to patientsThe functionmatchingfinds matches up to 3 mismatches and return apandas.DataFrameobject of the matches sorted by number of mismatches and their score.The function get these parameters:match_graph: a grma donors' graph object -grma.match.Graphgrim_config_file: a path togrimconfiguration filefromgrma.matchimportGraph,matchingPATH_TO_DONORS_GRAPH="output/donors_graph.pkl"PATH_CONGIF_FILE="conf/minimal-configuration.json"# The donors' graph we built earlierdonors_graph=Graph.from_pickle(PATH_TO_DONORS_GRAPH)# matching_results is a dict - {patient_id: the patient's result dataframe}matching_results=matching(donors_graph,PATH_CONGIF_FILE,search_id=1,donors_info=[],threshold=0.1,cutoff=100,save_to_csv=True,output_dir="results")matchingtakes some optional parameters, which you might want to change:search_id: An integer identification of the search. default is 0.donors_info: An iterable of fields from the database to include in the results. default is None.threshold: Minimal score value for a valid match. default is 0.1.cutof: Maximum number of matches to return. default is 50.verbose: A boolean flag for whether to print the documentation. default is Falsesave_to_csv: A boolean flag for whether to save the matching results into a csv file. default is False.  If the field is set to True, upon completion of the function, it will generate a directory namedsearch_1output_dir: output directory to write match results file toSearch & Match after imputation to patientsThe functionfind_mathcesfind matches up to 3 mismatches and return apandas.DataFrameobject of the matches
sorted by number of mismatches and their score.They get these parameters:imputation_filename: a path to the file of the patients' typing.match_graph: a grma donors' graph object -grma.match.Graphfromgrma.matchimportGraph,find_matchesPATH_TO_PATIENTS_FILE="data/patients_file.txt"PATH_TO_DONORS_GRAPH="output/donors_graph.pkl"# The donors' graph we built earlierdonors_graph=Graph.from_pickle(PATH_TO_DONORS_GRAPH)matching_results=find_matches(PATH_TO_PATIENTS_FILE,donors_graph)# matching_results is a dict - {patient_id: the patient's result dataframe}forpatient,dfinmatching_results.items():# Use here the dataframe 'df' with the results for 'patient'print(patient,df)find_matchestakes some optional parameters, which you might want to change:search_id: An integer identification of the search. default is 0.donors_info: An iterable of fields from the database to include in the results. default is None.threshold: Minimal score value for a valid match. default is 0.1.cutof: Maximum number of matches to return. default is 50.verbose: A boolean flag for whether to print the documentation. default is Falsesave_to_csv: A boolean flag for whether to save the matching results into a csv file. default is False.
If the field is set to True, upon completion of the function, it will generate a directory namedMatching_Result s_1.calculate_time: A boolean flag for whether to return the matching time for patient. default is False.
In casecalculate_time=Truethe output will be dict like this:{patient_id: (results_dataframe, time)}output_dir: output directory to write match results file toSet DatabaseIn order to get in the matching results more information about the donors than the matching information,
one can set a database that has all the donors' information in it.
The database must be apandas.DataFramethat its indexes are the donors' IDs.After setting the database, when calling one of the matching functions,
you may set in thedonor_infovariable alistwith the names of the columns you want to join to the result dataframe from the database.Example of setting the database:importpandasaspdfromgrma.matchimportset_databasedonors=[0,1,2]database=pd.DataFrame([[30],[32],[25]],columns=["Age"],index=donors)set_database(database)How to contribute:Fork the repository:https://github.com/nmdp-bioinformatics/py-graph-match.gitClone the repository locallygitclonehttps://github.com/<Your-Github-ID>/py-graph-match.gitcdpy-graph-matchMake a virtual environment and activate it, runmake venv>makevenvpython3-mvenvvenv--prompturban-potato-venv=====================================================================Toactivatethenewvirtualenvironment,executethefollowingfromyourshellsourcevenv/bin/activateSource the virtual environmentsourcevenv/bin/activateDevelopment workflow is driven throughMakefile. Usemaketo list show all targets.> make
 clean                remove all build, test, coverage and Python artifacts
 clean-build          remove build artifacts
 clean-pyc            remove Python file artifacts
 clean-test           remove test and coverage artifacts
 lint                 check style with flake8
 behave               run the behave tests, generate and serve report
 pytest               run tests quickly with the default Python
 test                 run all(BDD and unit) tests
 coverage             check code coverage quickly with the default Python
 dist                 builds source and wheel package
 docker-build         build a docker image for the service
 docker               build a docker image for the service
 install              install the package to the active Python's site-packages
 venv                 creates a Python3 virtualenv environment in venv
 activate             activate a virtual environment. Run `make venv` before activating.Install all the development dependencies. Will install packages from allrequirements-*.txtfiles.makeinstallThe Gherkin Feature files, step files and pytest files go intestsdirectory:tests
|-- features
|   |-- algorithm
|   |   `-- SLUG\ Match.feature
|   `-- definition
|       `-- Class\ I\ HLA\ Alleles.feature
|-- steps
|   |-- HLA_alleles.py
|   `-- SLUG_match.py
`-- unit
    `-- test_py-graph-match.pyPackage Module files go in thepy-graph-matchdirectory.py-graph-match
|-- __init__.py
|-- algorithm
|   `-- match.py
|-- model
|   |-- allele.py
|   `-- slug.py
`-- py-graph-match.pyRun all tests withmake testor different tests withmake behaveormake pytest.make behavewill generate report files and open the browser to the report.Usepython app.pyto run the Flask service app in debug mode. Service will be available athttp://localhost:8080/Usemake docker-buildto build a docker image using the currentDockerfile.make dockerwill build and run the docker image with the service.  Service will be available athttp://localhost:8080/=======
History0.0.1 (2021-08-25)First release on PyPI.