Python API¶

The HiGlass python API provides a functionality for starting a lightweight server, creating viewconfs and displaying a HiGlass component within Jupyter.

higlass.api¶

class higlass.api.CombinedTrack(*, type, uid=None, width=None, height=None, options=None, contents, position=None)[source]¶

Represents a track combining multiple tracks.

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'ignore', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'contents': FieldInfo(annotation=List[Union[EnumTrack, CombinedTrack, HeatmapTrack, IndependentViewportProjectionTrack, BaseTrack]], required=True), 'height': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'options': FieldInfo(annotation=Union[Dict[str, Any], NoneType], required=False, default=None), 'position': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'type': FieldInfo(annotation=Literal['combined'], required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class higlass.api.EnumTrack(*, tilesetUid=None, server=None, type, uid=None, width=None, height=None, options=None, data=None, chromInfoPath=None, fromViewUid=None, x=None, y=None)[source]¶

Represents a generic track.

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'ignore', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'chromInfoPath': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'data': FieldInfo(annotation=Union[Data, NoneType], required=False, default=None), 'fromViewUid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'height': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'options': FieldInfo(annotation=Union[Dict[str, Any], NoneType], required=False, default=None), 'server': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'tilesetUid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'type': FieldInfo(annotation=Union[Literal['viewport-projection-center', 'viewport-projection-vertical', 'viewport-projection-horizontal'], Literal['multivec', '1d-heatmap', 'line', 'point', 'bar', 'divergent-bar', 'stacked-interval', 'gene-annotations', 'linear-2d-rectangle-domains', 'chromosome-labels', 'linear-heatmap', '1d-value-interval', '2d-annotations', '2d-chromosome-annotations', '2d-chromosome-grid', '2d-chromosome-labels', '2d-rectangle-domains', '2d-tiles', 'arrowhead-domains', 'bedlike', 'cross-rule', 'dummy', 'horizontal-1d-annotations', 'horizontal-1d-heatmap', 'horizontal-1d-tiles', 'horizontal-1d-value-interval', 'horizontal-2d-rectangle-domains', 'horizontal-bar', 'horizontal-chromosome-grid', 'horizontal-chromosome-labels', 'horizontal-divergent-bar', 'horizontal-gene-annotations', 'horizontal-heatmap', 'horizontal-line', 'horizontal-multivec', 'horizontal-point', 'horizontal-rule', 'horizontal-vector-heatmap', 'image-tiles', 'left-axis', 'left-stacked-interval', 'mapbox-tiles', 'osm-2d-tile-ids', 'osm-tiles', 'raster-tiles', 'simple-svg', 'square-markers', 'top-axis', 'top-stacked-interval', 'vertical-1d-annotations', 'vertical-1d-heatmap', 'vertical-1d-tiles', 'vertical-1d-value-interval', 'vertical-2d-rectangle-domains', 'vertical-bar', 'vertical-bedlike', 'vertical-chromosome-grid', 'vertical-chromosome-labels', 'vertical-gene-annotations', 'vertical-heatmap', 'vertical-line', 'vertical-multivec', 'vertical-point', 'vertical-rule', 'vertical-vector-heatmap']], required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'x': FieldInfo(annotation=Union[float, NoneType], required=False, default=None), 'y': FieldInfo(annotation=Union[float, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class higlass.api.HeatmapTrack(*, tilesetUid=None, server=None, type, uid=None, width=None, height=None, options=None, data=None, position=None, transforms=None)[source]¶

Represets a specialized heatmap track.

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'ignore', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'data': FieldInfo(annotation=Union[Data, NoneType], required=False, default=None), 'height': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'options': FieldInfo(annotation=Union[Dict[str, Any], NoneType], required=False, default=None), 'position': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'server': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'tilesetUid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'transforms': FieldInfo(annotation=Union[List, NoneType], required=False, default=None), 'type': FieldInfo(annotation=Literal['heatmap'], required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class higlass.api.IndependentViewportProjectionTrack(*, type, uid=None, width=None, height=None, options=None, fromViewUid=None, projectionXDomain=None, projectionYDomain=None, transforms=None, x=None, y=None)[source]¶

Represents a view-independent viewport projection track.

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'ignore', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'fromViewUid': FieldInfo(annotation=NoneType, required=False, default=None), 'height': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'options': FieldInfo(annotation=Union[Dict[str, Any], NoneType], required=False, default=None), 'projectionXDomain': FieldInfo(annotation=Union[Tuple[float, float], NoneType], required=False, default=None), 'projectionYDomain': FieldInfo(annotation=Union[Tuple[float, float], NoneType], required=False, default=None), 'transforms': FieldInfo(annotation=Union[List, NoneType], required=False, default=None), 'type': FieldInfo(annotation=Literal['viewport-projection-center', 'viewport-projection-vertical', 'viewport-projection-horizontal'], required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'x': FieldInfo(annotation=Union[float, NoneType], required=False, default=None), 'y': FieldInfo(annotation=Union[float, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class higlass.api.PluginTrack(*, type, uid=None, width=None, height=None, options=None, **extra_data)[source]¶

Represents an unknown plugin track.

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'allow', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'height': FieldInfo(annotation=Union[int, NoneType], required=False, default=None), 'options': FieldInfo(annotation=Union[Dict[str, Any], NoneType], required=False, default=None), 'type': FieldInfo(annotation=TypeVar, required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'width': FieldInfo(annotation=Union[int, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

class higlass.api.View(*, layout, tracks, uid=None, autocompleteSource=None, chromInfoPath=None, genomePositionSearchBox=None, genomePositionSearchBoxVisible=None, initialXDomain=None, initialYDomain=None, overlays=None, selectionView=None, zoomFixed=None, zoomLimits=(1, None))[source]¶

Represets a HiGlass View that is generic over the inner tracks.

clone()[source]¶

Clone the the View instance.

Inserts a unique uuid so the view can be uniquely identified in the front end.

Returns:: view
Return type:: A copy of the original view with a new uuid

domain(x=None, y=None, inplace=False)[source]¶

Configures the view x and/or y domain(s).

Parameters:

x (tuple[float, float], optional) – The x domain for the view (default: None)
y (tuple[float, float], optional) – The y domain for the view (default: None)
inplace (bool, optional) – Whether to modify this view inplace. If False (default), a new view is created and returned with the domains applied (default: False)

Returns:

view

Return type:

a View with the updated x & y domains

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'ignore', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'autocompleteSource': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'chromInfoPath': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'genomePositionSearchBox': FieldInfo(annotation=Union[GenomePositionSearchBox, NoneType], required=False, default=None), 'genomePositionSearchBoxVisible': FieldInfo(annotation=Union[bool, NoneType], required=False, default=None), 'initialXDomain': FieldInfo(annotation=Union[Tuple[float, float], NoneType], required=False, default=None), 'initialYDomain': FieldInfo(annotation=Union[Tuple[float, float], NoneType], required=False, default=None), 'layout': FieldInfo(annotation=Layout, required=True), 'overlays': FieldInfo(annotation=Union[List[Overlay], NoneType], required=False, default=None), 'selectionView': FieldInfo(annotation=Union[bool, NoneType], required=False, default=None), 'tracks': FieldInfo(annotation=Tracks[TypeVar], required=True), 'uid': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'zoomFixed': FieldInfo(annotation=Union[bool, NoneType], required=False, default=None), 'zoomLimits': FieldInfo(annotation=Tuple[float, Union[float, NoneType]], required=False, default=(1, None))}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

project(view, on='center', inplace=False, **kwargs)[source]¶

Project a different viewport onto this view.

Creates a viewport-projection track whos bounds are synchonrized with an existing, separate view.

Parameters:

view (View) – The view with the desired viewport to project.
on (Literal["center", "top", "bottom", "left", "right"], optional) – Where to project the viewport on this view (default: “center”).
inplace (bool) – Whether to modify this view inplace, or alternatively return a new view (default: False).
**kwargs (dict) – Additional parameters for the created viewport-projection track.

Returns:

view

Return type:

A view with a new viewport-projection track.

viewconf(**kwargs)[source]¶

Consumes the current View into a top-level view config.

Returns:: viewconf
Return type:: A top-level HiGlass Viewconf.

widget(**kwargs)[source]¶

Create a Jupyter Widget display for this view.

Casts the view into a top-level view config which can be displayed.

Returns:: widget
Return type:: A HiGlassWidget instance

class higlass.api.Viewconf(*, editable=True, viewEditable=True, tracksEditable=True, zoomFixed=None, compactLayout=None, exportViewUrl=None, trackSourceServers=None, views=None, zoomLocks=None, locationLocks=None, valueScaleLocks=None, chromInfoPath=None)[source]¶

Represents a top-level viewconfig, or a complete HiGlass visualization.

classmethod from_url(url, **kwargs)[source]¶

Load a viewconf via URL and construct a Viewconf.

Makes an HTTP request.

Parameters:

url (str) – The URL for a JSON HiGlass view config.
**kwargs (dict) – Options for the urllib.Request instance.

Returns:

viewconf

Return type:

The parsed view config

locks(*locks, zoom=None, location=None, value_scale=None, inplace=False)[source]¶

Specify view locks.

Parameters:

*locks (hgs.Lock | hgs.ValueScaleLock, optional) – A set of either zoom/location or value scale locks to add. Instances of hgs.Lock will synchronize _both_ zoom and location for the views included in the lock. If you’d like to synchronize just zoom or location, use the explicit keyword arguments below.
zoom (hgs.Lock | list[hgs.Lock], optional) – A lock or set of locks to synchronize only the zoom.
location (hgs.Lock | list[hgs.Lock], optional) – A lock or set of locks to synchronize only the location.
value_scale (hgs.ValueScaleLock | list[hgs.ValueScaleLock], optional) – A single or set of value-scale locks.
inplace (bool, optional) – Whether to modify the viewconf in place or return a new viewconf with the locks applied (default: False)

Returns:

viewconf

Return type:

A Viewconf with the synchronized views.

Examples

>>> view1 = hg.view(hg.track("heatmap"))
>>> view2 = hg.view(hg.track("heatmap"))
>>> # create an abstract lock for two views
>>> view_lock = hg.lock(view1, view2)
>>> # lock location & zoom
>>> (view1 | view2).lock(view_lock)
>>> # lock only zoom
>>> (view1 | view2).lock(zoom=view_lock)
>>> # lock only location
>>> (view1 | view2).lock(location=view_lock)

model_computed_fields = {}¶: A dictionary of computed field names and their corresponding ComputedFieldInfo objects.

model_config = {'extra': 'forbid', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_fields = {'chromInfoPath': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'compactLayout': FieldInfo(annotation=Union[bool, NoneType], required=False, default=None), 'editable': FieldInfo(annotation=Union[bool, NoneType], required=False, default=True), 'exportViewUrl': FieldInfo(annotation=Union[str, NoneType], required=False, default=None), 'locationLocks': FieldInfo(annotation=Union[LocationLocks, NoneType], required=False, default=None), 'trackSourceServers': FieldInfo(annotation=Union[List[str], NoneType], required=False, default=None), 'tracksEditable': FieldInfo(annotation=Union[bool, NoneType], required=False, default=True), 'valueScaleLocks': FieldInfo(annotation=Union[ValueScaleLocks, NoneType], required=False, default=None), 'viewEditable': FieldInfo(annotation=Union[bool, NoneType], required=False, default=True), 'views': FieldInfo(annotation=Union[Annotated[List[View], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=1)])], NoneType], required=False, default=None), 'zoomFixed': FieldInfo(annotation=Union[bool, NoneType], required=False, default=None), 'zoomLocks': FieldInfo(annotation=Union[ZoomLocks, NoneType], required=False, default=None)}¶

Metadata about the fields defined on the model, mapping of field names to [FieldInfo][pydantic.fields.FieldInfo] objects.

This replaces Model.__fields__ from Pydantic V1.

widget(**kwargs)[source]¶: Create a Jupyter Widget display for this view config.

higlass.api.combine(t1, t2, uid=None, **kwargs)[source]¶

A utility to create a CombinedTrack from two other tracks.

Parameters:

t1 (hg.Track) – The first of two tracks to combine.
t2 (hg.Track) – The second of two tracks to combine.
uid (str, optional) – A unique id for the newly created CombinedTrack.
**kwargs (dict) – Additional properties to pass to the CombinedTrack constructor.

Returns:

combined_track

Return type:

An CombinedTrack with two children tracks.

higlass.api.concat(method, a, b)[source]¶

Concatenate two views or separate viewconfs together.

Uses the layout of one view or the total bounds of all views in one viewconf to offset the other view/viewconf.

Parameters:

method (Literal["horizontal", "vertical"]) – How to concatenate views/viewconfs.
a (View | Viewconf) – A view or viewconf to combine.
b (View | Viewconf) – The other view or viewconf to combine.

Returns:

viewconf

Return type:

A combined viewconf containing multiple views.

higlass.api.divide(t1, t2, **kwargs)[source]¶

A utility to create a divided track.

Tracks must the the same type.

Parameters:

t1 (hg.EnumTrack | hg.HeatmapTrack) – The first track to divide by the other.
t2 (hg.EnumTrack | hg.HeatmapTrack) – The other track.
**kwargs (dict) – Additional properties to pass to the newly created track.

Returns:

divided_track

Return type:

An identical track with “divided” data sources.

higlass.api.hconcat(a, b)¶

Concatenate two views or separate viewconfs together.

Uses the layout of one view or the total bounds of all views in one viewconf to offset the other view/viewconf.

Parameters:

method (Literal["horizontal", "vertical"]) – How to concatenate views/viewconfs.
a (View | Viewconf) – A view or viewconf to combine.
b (View | Viewconf) – The other view or viewconf to combine.

Returns:

viewconf

Return type:

A combined viewconf containing multiple views.

higlass.api.lock(*data, uid=None, **kwargs)[source]¶

Create an abstract lock or value-scale lock.

Overloaded to either return a hgs.Lock or hgs.ValueScaleLock depending on the arguments. See Viewconf.locks for how to use the created locks in your top-level view config.

Examples

Create an abstract lock linking two or more separate views.

>>> view1 = hg.view(hg.track("heatmap"))
>>> view2 = hg.view(hg.track("heatmap"))
>>> lock = hg.lock(view1, view2)

Create a value-scale lock, scaling two views by the values of a particular track.

>>> t1 = hg.track("heatmap")
>>> t2 = hg.track("heatmap")
>>> view1 = hg.view(t1, t2)
>>> view2 = hg.view(t1, t2)
>>> value_scale_lock = hg.lock((view1, t2), (view2, t2))

higlass.api.track(type_, uid=None, **kwargs)[source]¶

Create a HiGlass track.

Parameters:

type (str) – The track type to create
uid (str, optional) – A unique id for the track. If unspecified (default), a unique id is given internally.
**kwargs (dict) – Other top-level track properties.

Returns:

track

Return type:

An instance of an hg.Track

higlass.api.vconcat(a, b)¶

Concatenate two views or separate viewconfs together.

Uses the layout of one view or the total bounds of all views in one viewconf to offset the other view/viewconf.

Parameters:

method (Literal["horizontal", "vertical"]) – How to concatenate views/viewconfs.
a (View | Viewconf) – A view or viewconf to combine.
b (View | Viewconf) – The other view or viewconf to combine.

Returns:

viewconf

Return type:

A combined viewconf containing multiple views.

higlass.api.view(*_tracks, x=0, y=0, width=12, height=6, tracks=None, layout=None, uid=None, **kwargs)[source]¶

Create a HiGlass view from multiple tracks.

Parameters:

*_tracks (Track | tuple[Track, str] | hgs.Tracks[Track]) – The tracks to include in the view. Can be 1) separate track objects (position inferred), 2) explicit (Track, position) tuples, or 3.) a higlass_schema.Tracks Object specifying all tracks and positions.
x (int, optional) – The x position of the view in the HiGlass grid (default: 0). Used to created a Layout if none is provided.
y (int, optional) – The y position of the view in the HiGlass grid (default: 0). Used to created a Layout if none is provided.
width (int, optional) – The width of the view (default: 12). Used to created a Layout if none is provided.
height (int, optional) – The height of the view (default: 6). Used to created a Layout if none is provided.
layout (hgs.Layout, optional) – An explicit layout for the view (default: None). If provided the x, y, width, and height parameters are ignored.
uid (str, optional) – A unique id for the view. If unspecified (default), a unique id is automatically generated internally.
**kwargs (dict) – Other top-level view properties.

Returns:

view

Return type:

An instance of an hg.View