Usage
The tool is designed to generate interaction network’s hierarchy based on a list of embedding or coembedding files. Embedding or coembedding directories, containing coembedding files in TSV format should be provided to generate several interactomes, which are used to create a structured hierarchy.
It can be also used to uppload hierarchy and its parent to NDEx and convert hierarchy in HCCX to HiDeF .nodes and .edges files.
In a project
To use cellmaps_generate_hierarchy in a project:
import cellmaps_generate_hierarchy
Needed files
The output directory for co-embedding (see Cell Maps Coembedding), ppi embedding (see Cell Maps PPI Embedding), or image embedding (see Cell Maps Image Embedding) is required
On the command line
For information invoke cellmaps_generate_hierarchycmd.py -h
Usage
In run mode (hierarchy generation):
cellmaps_generate_hierarchycmd.py [outdir] [--coembedding_dirs COEMBEDDINGDIRS [COEMBEDDINGDIRS ...]] [OPTIONS]
In ndexsave mode (saving hierarchy to NDEx):
cellmaps_generate_hierarchycmd.py [outdir] [--mode ndexsave] [--ndexuser NDEXUSER] [--ndexpassword NDEXPASSWORD]
In convert mode (converting hierarchy to HiDeF files)
cellmaps_generate_hierarchycmd.py [outdir] [--mode convert] [--hcx_dir DIRECTORY_WITH_HCX_FILE]
Arguments
outdir
The directory where the output will be written to or directory where hierarchy.cx2 and parent_hierarchy.cx2 was saved.
Possible modes
--mode ['run', 'ndexsave', 'convert']
Processing mode. If set to
run
then hierarchy is generated. If set tondexsave
, it is assumes hierarchy has been generated (named hierarchy.cx2 and parent_hierarchy.cx2) and put inoutdir
passed in via the command line and this tool will save the hierarchy to NDEx using--ndexserver
,--ndexuser
, and--ndexpassword
credentials. If set to convert, it is assumes hierarchy has been generated (named hierarchy.cx2) and it converts the hierarchy to HiDeF .nodes and .edges files.
Required in ‘run’ mode
--coembedding_dirs COEMBEDDINGDIRS [COEMBEDDINGDIRS ...]
Directories where coembedding, ppi embedding or image embedding was run. This is a required argument and multiple directories can be provided. Can be also paths to specific TSV files with embeddings.
Required in ‘ndexsave’ mode
--ndexuser NDEXUSER
NDEx user account.
--ndexpassword NDEXPASSWORD
NDEx password. This can either be the password itself or a path to a file containing the password.
Required in ‘convert’ mode
--hcx_dir DIRECTORY_WITH_HCX_FILE
Input directory for convert mode with hierarchy in hcx to be converted to HiDeF .nodes and .edges files
Optional
--ndexserver NDEXSERVER
Server where the hierarchy can be converted to HCX and saved. Default is
idekerlab.ndexbio.org
.
--name NAME
Name of this run, needed for FAIRSCAPE. If unset, the name value from the directory specified by
--coembedding_dir
will be used.
--organization_name ORGANIZATION_NAME
Name of the organization running this tool. If unset, the organization name specified in
--coembedding_dir
directory will be used.
--project_name PROJECT_NAME
Name of the project running this tool. If unset, the project name specified in
--coembedding_dir
directory will be used.
--k K
HiDeF stability parameter. Default is 10.
--algorithm ALGORITHM
HiDeF clustering algorithm parameter. Default algorithm is leiden.
--maxres MAXRES
HiDeF max resolution parameter. Default value is 80.
--containment_threshold
Containment index threshold for pruning hierarchy. Default is
0.75
.
--jaccard_threshold
Jaccard index threshold for merging similar clusters. Default is
0.9
.
--min_diff
Minimum difference in number of proteins for every parent-child pair. Default is
1
.
--min_system_size
Minimum number of proteins each system must have to be kept. Default is
4
.
--ppi_cutoffs PPI_CUTOFFS [PPI_CUTOFFS ...]
Cutoffs used to generate PPI input networks. Default cutoffs are provided in the code.
--skip_layout
If set, skips the layout of hierarchy step.
--visibility
If set, the Hierarchy and interactome network loaded onto NDEx will be publicly visible.
--logconf LOGCONF
Path to python logging configuration file. Setting this overrides
-v
parameter which uses the default logger.
--verbose
or-v
Increases verbosity of logger. Multiple levels of verbosity can be set.
--version
Shows the version of the program.
Example usage
Hierarchy generation
To generate hierarchy, use embeddings or co-embeddings, in the format specified in Inputs section.
cellmaps_generate_hierarchycmd.py ./cellmaps_generate_hierarchy_outdir --coembedding_dirs ./cellmaps_coembedding_outdir -vvvv
To generate hierarchy with a custom name use --name
flag.
cellmaps_generate_hierarchycmd.py ./cellmaps_generate_hierarchy_outdir --coembedding_dirs ./cellmaps_coembedding_outdir --name my_hierarchy -vvvv
Uploading hierarchy to NDEx
To upload network to NDEx, NDEx account is necessary. See here on how to create account on NDEx.
With command line:
# Example hierarchy and its interactome in examples directory in cellmaps_generate_hierarchy repository
cellmaps_generate_hierarchycmd.py ./examples/ --mode ndexsave --ndexuser example_user_name --ndexpassword -
Programmatically:
import os
import ndex2
from ndex2.cx2 import RawCX2NetworkFactory
from cellmaps_generate_hierarchy.ndexupload import NDExHierarchyUploader
#Specify NDEx server
ndexserver = 'idekerlab.ndexbio.org''
ndexuser = '<USER>'
ndexpassword = '<PASSWORD>'
# Specify paths to hierarchy and its parent (you can find example files in examples directory in cellmaps_generate_hierarchy_repo)
hierarchy_path = './examples/hierarchy.cx2'
parent_network_path = './examples/hierarchy_parent.cx2'
# Load the hierarchy and parent network CX2 files into network objects
factory = RawCX2NetworkFactory()
hierarchy_network = factory.get_cx2network(hierarchy_path)
parent_network = factory.get_cx2network(parent_network_path)
# Initialize NDExHierarchyUploader with the specified NDEx server and credentials
uploader = NDExHierarchyUploader(ndexserver, ndexuser, ndexpassword, visibility=True)
# Upload the hierarchy and parent network to NDEx
parent_uuid, parenturl, hierarchy_uuid, hierarchyurl = uploader.save_hierarchy_and_parent_network(hierarchy_network, parent_network)
print(f"Parent network UUID is {parent_uuid} and its URL in NDEx is {parenturl}")
print(f"Hierarchy network UUID is {hierarchy_uuid} and its URL in NDEx is {hierarchyurl}")
# Another option is to just specify the directory where the files are placed
_, _, _, hierarchyurl = uploader.upload_hierary_and_parent_network_from_files('./examples/')
print(f'Hierarchy uploaded. To view the hierarchy, paste this URL in your browser: {hierarchyurl}')
Convert hierarchy to HiDeF
cellmaps_generate_hierarchycmd.py ./output_dir --mode convert --hcx_dir ./examples/
Via Docker
Example usage
Coming soon...