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 to ndexsave, it is assumes hierarchy has been generated (named hierarchy.cx2 and parent_hierarchy.cx2) and put in outdir 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...