simulariumio package

Subpackages

Submodules

simulariumio.constants module

class simulariumio.constants.BINARY_BLOCK_TYPE(value)[source]

Bases: Enum

The types of data saved in a block

PLOT_DATA_JSON = 2
SPATIAL_DATA_BINARY = 3
SPATIAL_DATA_JSON = 0
TRAJ_INFO_JSON = 1
class simulariumio.constants.BINARY_SETTINGS[source]

Bases: object

BLOCK_HEADER_N_VALUES: int = 2
BLOCK_OFFSET_BYTE_ALIGNMENT: int = 4
BYTES_PER_VALUE: int = 4
DEFAULT_BLOCK_TYPES: List[int] = [1, 3, 2]
FILE_IDENTIFIER: str = 'SIMULARIUMBINARY'
FRAME_HEADER_N_VALUES: int = 3
HEADER_CONSTANT_N_VALUES: int = 3
HEADER_N_INT_VALUES: int = 12
HEADER_N_VALUES_PER_BLOCK: int = 3
MAX_BYTES: int = 4000000000
N_BLOCKS: int = 3
SPATIAL_BLOCK_HEADER_CONSTANT_N_VALUES: int = 2
SPATIAL_BLOCK_HEADER_N_VALUES_PER_FRAME: int = 2
VERSION: int = 2
class simulariumio.constants.CURRENT_VERSION[source]

Bases: object

PLOT_DATA: int = 1
SPATIAL_DATA: int = 1
TRAJECTORY_INFO: int = 3
class simulariumio.constants.DEFAULT_CAMERA_SETTINGS[source]

Bases: object

CAMERA_POSITION: ndarray = array([  0.,   0., 120.])
FOV_DEGREES: float = 75.0
LOOK_AT_POSITION: ndarray = array([0., 0., 0.])
UP_VECTOR: ndarray = array([0., 1., 0.])
class simulariumio.constants.DISPLAY_TYPE(value)[source]

Bases: Enum

These values are required for file I/O, changing them requires a version bump

FIBER = 'FIBER'
NONE = None
OBJ = 'OBJ'
PDB = 'PDB'
SPHERE = 'SPHERE'
SPHERE_GROUP = 'SPHERE_GROUP'
simulariumio.constants.JMOL_COLORS() → DataFrame[source]

Get a dataframe with Jmol colors for atomic element types

simulariumio.constants.SUBPOINT_VALUES_PER_ITEM(display_type: DISPLAY_TYPE) → int[source]

How many values per item saved in subpoints? given the display type of the agent

class simulariumio.constants.V1_SPATIAL_BUFFER_STRUCT[source]

Bases: object

MIN_VALUES_PER_AGENT: int = 11
NSP_INDEX: int = 10
POSX_INDEX: int = 3
POSY_INDEX: int = 4
POSZ_INDEX: int = 5
ROTX_INDEX: int = 6
ROTY_INDEX: int = 7
ROTZ_INDEX: int = 8
R_INDEX: int = 9
SP_INDEX: int = 11
TID_INDEX: int = 2
UID_INDEX: int = 1
VIZ_TYPE_INDEX: int = 0
class simulariumio.constants.VIEWER_DIMENSION_RANGE[source]

Bases: object

MAX = 64
MIN = 4
class simulariumio.constants.VIZ_TYPE[source]

Bases: object

DEFAULT: float = 1000.0
FIBER: float = 1001.0

simulariumio.exceptions module

exception simulariumio.exceptions.DataError(issue, **kwargs)[source]

Bases: Exception

This exception is intended to communicate that something is wrong with the data provided.

exception simulariumio.exceptions.InputDataError(issue, **kwargs)[source]

Bases: Exception

This exception is intended to communicate that an error occurred while the input files were being read or parsed.

exception simulariumio.exceptions.MissingDataError(field_name, **kwargs)[source]

Bases: Exception

This exception is intended to communicate that the data provided is missing a field needed to parse it.

exception simulariumio.exceptions.UnsupportedPlotTypeError(plot_type, **kwargs)[source]

Bases: Exception

This exception is intended to communicate that the requested plot type is not one of the supported types and cannot be parsed with simulariumio.

simulariumio.file_converter module

class simulariumio.file_converter.FileConverter(input_file: InputFileData, display_data: Dict[int, DisplayData] | None = None)[source]

Bases: TrajectoryConverter

This object loads data from the input file in .simularium format.

Parameters:
input_file: InputFileData

A InputFileData object containing .simularium data to load

static update_trajectory_info_version(data: Dict[str, Any]) → Dict[str, Any][source]

Update the trajectory info block to match the current version

Parameters:
data: Dict[str, Any]

A .simularium JSON file loaded in memory as a Dict. This object will be mutated, not copied.

simulariumio.trajectory_converter module

class simulariumio.trajectory_converter.TrajectoryConverter(input_data: TrajectoryData, progress_callback: Callable[[float], None] | None = None, callback_interval: float = 10)[source]

Bases: object

This object reads simulation trajectory outputs and plot data and writes them in the JSON format used by the Simularium viewer

Parameters:
input_dataTrajectoryData

An object containing simulation trajectory outputs and plot data

progress_callbackCallable[[float], None] (optional)

Callback function that accepts 1 float argument and returns None which will be called at a given progress interval, determined by callback_interval requested, providing the current percent progress Default: None

callback_intervalfloat (optional)

If a progress_callback was provided, the period between updates to be sent to the callback, in seconds Default: 10

add_number_of_agents_plot(plot_title: str = 'Number of agents over time', yaxis_title: str = 'Number of agents')[source]

Add a scatterplot of the number of each type of agent over time

Parameters:
plot_title: str

The title for the plot Default: “Number of agents over time”

yaxis_title: str

The title for the y-axis of the plot Default: “Number of agents”

add_plot(data: [<class 'simulariumio.data_objects.scatter_plot_data.ScatterPlotData'>], plot_type: str = 'scatter')[source]

Add data to be rendered in a plot

Parameters:
data: ScatterPlotData or HistogramPlotData

Loaded data for a plot.

plot_type: str

A string specifying which type of plot to render. Current options:

‘scatter’a scatterplot with y-trace(s) dependent

on an x-trace

‘histogram’a histogram with bars drawn at intervals

over the range(s) of the data, with their height corresponding to the number of values in each interval

Default: ‘scatter’

static calculate_scale_factor(agent_data: AgentData) → float[source]

Return a scale factor, using the given position, radii, and subpoints, data from AgentData, so that the final range of agent locations is within the dimensions defined by VIEWER_DIMENSION_RANGE.

center_and_scale_agent_data(input_scale_factor: float | None = None) → Tuple[AgentData, float][source]

Center the provided agent_data at the origin, based on the range of XYZ position data and subpoint data. In addition, scale position and radii data based on the input_scale_factor if provided, otherwise calculate the scale factor using calculate_scale_factor(). Returns the centered and scaled AgentData, and the scale factor that was applied

static center_fiber_positions(agent_data: AgentData) → AgentData[source]

For each agent with fiber subpoints, calculate the center of the fiber positions, and adjust the agent position to be at the center. Adjust the subpoint positions accordingly. Returns an AgentData object with updates reflected.

check_report_progress(percent_complete: float) → None[source]
filter_data(filters: List[Filter]) → TrajectoryData[source]

Return the simularium data with the given filter applied

static get_min_max_positions(agent_data: AgentData) → Tuple[array, array][source]
static get_subpoints_xyz(subpoints: array, n_subpoints: array) → array[source]

Given AgentData subpoints (shape = [timesteps, agents, subpoints]), and a list of n_subpoints per agent per timestep (shape = [timesteps, agents]) extract all subpoint data, skipping the zeros which represent no data. Reshape resulting subpoint data into a 2D array of XYZ coordinate data

static get_xyz_max(data: array, n_agents: array | None = None) → array[source]

Given AgentData position data (shape = [timesteps, agents, 3]), and corresponding n_agents data, indicating agents per timestamp, extract all position data, skipping the zeros that represent no data. Provide maximum X, Y, and Z values from remaining data

static get_xyz_min(data: array, n_agents: array | None = None) → array[source]

Given AgentData position data (shape = [timesteps, agents, 3]), and corresponding n_agents data, indicating agents per timestamp, extract all position data, skipping the zeros that represent no data. Provide minimum X, Y, and Z values from remaining data

save(output_path: str, binary: bool = True, validate_ids: bool = True)[source]

Save the current simularium data in .simularium JSON format at the output path

Parameters:
output_path: str

where to save the file

binary: bool (optional)

save in binary format? otherwise use JSON Default: True

validate_ids: bool

additional validation to check agent ID size? Default = True

save_plot_data(output_path: str)[source]

Save the current plot data in JSON format at the output path

Parameters:
output_path: str

where to save the file

static scale_agent_data(agent_data: AgentData, input_scale_factor: float | None = None) → Tuple[AgentData, float][source]

Return a scaled AgentData object, either using a provided scale factor if input_scale_factor is given, or using a calculated scale factor using calculate_scale_factor() with the provided agent data. Also returns the scale factor that was used on the AgentData object.

to_JSON()[source]

Return the current simularium data in JSON format

simulariumio.utils module

simulariumio.utils.translate_agent_positions(data: AgentData, default_translation: ndarray, translation_per_type: Dict[str, ndarray] = {}) → AgentData[source]

Translate all spatial data for each frame of simularium trajectory data

Parameters:
dataAgentData

Trajectory data, containing the spatial data to be traslated

default_translationnp.ndarray (shape = [3])

XYZ translation for all agents not specified in translation_per_type

translation_per_typeDict[str, int]

translation for agents of each type Default: {}

simulariumio.utils.unpack_display_data(data_dict: Dict[str, Any]) → Dict[str, DisplayData][source]

Create dict [str, DisplayData] mapping agent names to display data from a JSON dict

simulariumio.utils.unpack_position_vector(vector_dict: Dict[str, str], defaults: ndarray) → ndarray[source]

Takes a vector dict describing x, y, z coordinates and default values and returns a numpy array representing the 3 coordintes

Parameters:
vector_dictDict[str, str]

Dict representing values of X, Y, and/or Z coordinates Keys should be {‘x’,’y’,’z’}

defaults: np.ndarray

Numpy array representing default XYZ coordinates. For any coordinates not provided in vector_dict, these default values will be used in the result vector

Module contents

Top-level package for simulariumio.