simulariumio.data_objects package

Submodules

simulariumio.data_objects.agent_data module

class simulariumio.data_objects.agent_data.AgentData(times: ndarray | List[float], n_agents: ndarray | List[int], viz_types: ndarray | List[List[float]], unique_ids: ndarray | List[List[int]], types: List[List[str]], positions: ndarray | List[List[List[float]]], radii: ndarray | List[List[float]], rotations: ndarray | List[List[List[float]]] | None = None, n_subpoints: ndarray | List[List[int]] | None = None, subpoints: ndarray | List[List[List[float]]] | None = None, display_data: Dict[str, DisplayData] | None = None, draw_fiber_points: bool = False, n_timesteps: int = -1)

Bases: object

This object contains spatial simulation data

Parameters:

timesnp.ndarray or List[float] (shape = [timesteps])

A numpy ndarray or list containing the elapsed simulated time at each timestep (in the units specified by TrajectoryData.time_units)

n_agentsnp.ndarray or List[int] (shape = [timesteps])

A numpy ndarray or list containing the number of agents that exist at each timestep

viz_typesnp.ndarray or List[List[float]] (shape = [timesteps, agents])s

A numpy ndarray or list containing the viz type for each agent at each timestep. Current options:

1000 : default, 1001 : fiber (which will require subpoints)

unique_idsnp.ndarray or List[List[int]] (shape = [timesteps, agents])

A numpy ndarray or list containing the unique ID for each agent at each timestep

typesList[List[str]] (list of shape [timesteps, agents])

A list containing timesteps, for each a list of the string name for the type of each agent

positionsnp.ndarray or List[List[List[float]]]

(shape = [timesteps, agents, 3])

A numpy ndarray or list containing the XYZ position for each agent at each timestep (in the units specified by TrajectoryData.spatial_units)

radiinp.ndarray or List[List[float]] (shape = [timesteps, agents])

A numpy ndarray or list containing the radius for each agent at each timestep

rotationsnp.ndarray or List[List[List[float]]]

(shape = [timesteps, agents, 3]) (optional)

A numpy ndarray or list containing the XYZ euler angles representing the rotation for each agent at each timestep in degrees Default: [0, 0, 0] for each agent

n_subpointsnp.ndarray or List[List[int]]

(shape = [timesteps, agents]) (optional)

A numpy ndarray or list containing the number of subpoints belonging to each agent at each timestep. Required if subpoints are provided Default: None

subpointsnp.ndarray or List[List[List[float]]]

(shape = [timesteps, agents, subpoints]) (optional)

A numpy ndarray or list containing a list of subpoint data for each agent at each timestep. These values are currently used for fiber and sphere group agents Default: None

display_data: Dict[str,DisplayData] (optional)

A dictionary mapping agent type name to DisplayData to use for that type Default: None

draw_fiber_points: bool (optional)

Draw spheres at every other fiber point for fibers? Default: False

n_timestepsint (optional)

Use the first n_timesteps frames of data Default: -1 (use the full length of the buffer)

check_increase_buffer_size(next_index: int, axis: int = 1, buffer_size_inc: ~simulariumio.data_objects.dimension_data.DimensionData = <simulariumio.data_objects.dimension_data.DimensionData object>) → AgentData

If needed for the next_index to fit in the arrays, create a copy of this object with the size of the numpy arrays increased by the buffer_size_inc

display_data: Dict[str, DisplayData]

display_type_for_agent(time_index: int, agent_index: int) → DISPLAY_TYPE

Get the DISPLAY_TYPE for the agent at the given time and agent indices

draw_fiber_points: bool

classmethod from_buffer_data(buffer_data: Dict[str, Any], display_data: Dict[int, DisplayData] | None = None)

Create AgentData from a simularium JSON dict containing buffers

classmethod from_dataframe(traj: DataFrame)

Create AgentData from a pandas DataFrame with columns: time, unique_id, type, positionX, positionY, positionZ, radius (only for default agents, no fibers)

classmethod from_dimensions(dimensions: DimensionData, default_viz_type: float = 1000.0)

Create AgentData with empty numpy arrays of the required dimensions

get_copy_with_increased_buffer_size(added_dimensions: DimensionData, axis: int = 1) → AgentData

Create a copy of this object with the size of the numpy arrays increased by the given added_dimensions

get_dimensions() → DimensionData

Get the dimensions of this object’s numpy arrays

static get_display_data(type_mapping: Dict[str, Any], display_data: Dict[int, DisplayData] | None = None) → Dict[str, DisplayData]

Generate the display_data mapping using a type_mapping from a simularium JSON dict containing buffers

get_type_ids_and_mapping() → Tuple[ndarray, Dict[str, Any]]

Generate a type_ids array from the type_names list

static get_type_names(type_ids: ndarray, type_mapping: Dict[str, Any]) → List[List[str]]

Generate the type_names list from a type_ids array and a type_mapping

n_agents: ndarray | List[int]

n_subpoints: ndarray | List[List[float]]

n_timesteps: int

positions: ndarray | List[List[List[float]]]

radii: ndarray | List[List[float]]

rotations: ndarray | List[List[List[float]]]

subpoints: ndarray | List[List[List[float]]]

times: ndarray | List[float]

total_timesteps() → int

Get number of timesteps Use n_timesteps to limit times if it has been provided

types: List[List[str]]

unique_ids: ndarray | List[List[int]]

viz_types: ndarray | List[List[float]]

simulariumio.data_objects.binary_data module

class simulariumio.data_objects.binary_data.BinaryData(file_contents: bytes)

Bases: SimulariumFileData

This object holds binary encoded simulation trajectory file’s data while staying close to the original file format

Parameters:

file_contentsbytes

A byte array containing the data of an open .simularium file

get_file_contents() → bytes

Return raw file data, as bytes

get_frame_at_index(frame_number: int) → FrameData

Return frame data for frame at index. If there is no frame at the index, return None.

get_index_for_time(time: float) → int

Return index for frame closest to a given timestamp

get_num_frames() → int

Return number of frames in the trajectory

get_plot_data() → Dict

Return plot data block for trajectory, as dict

get_trajectory_data_object() → TrajectoryData

Return the data of the trajectory, as a TrajectoryData object

get_trajectory_info() → Dict

Return trajectory info block for trajectory, as dict

class simulariumio.data_objects.binary_data.FrameMetadata(offset: int, length: int, frame_number: int, time: float)

Bases: object

This object holds metadata for a single frame of simularium data

Parameters:

offsetint

Number of bytes the block is offset from the start of the byte array

lengthint

Number of bytes in the block

frame_numberint

Index of frame in the simulation

timefloat

Elapsed simulation time of the frame

get_start_end_indices() → Tuple[int, int]

Return the start and end indicies for the data block

simulariumio.data_objects.camera_data module

class simulariumio.data_objects.camera_data.CameraData(position: ndarray = array([0., 0., 120.]), look_at_position: ndarray = array([0., 0., 0.]), up_vector: ndarray = array([0., 1., 0.]), fov_degrees: float = array(75.))

Bases: object

This object holds parameters that define a camera view of the 3D scene

Parameters:

positionnp.ndarray (shape = [3]) (optional)

3D position of the camera itself Default: np.array([0.0, 0.0, 120.0])

look_at_positionnp.ndarray (shape = [3]) (optional)

position the camera looks at Default: np.zeros(3)

up_vectornp.ndarray (shape = [3]) (optional)

the vector that defines which direction is “up” in the camera’s view Default: np.array([0.0, 1.0, 0.0])

fov_degreesfloat (optional)

the angle defining the extent of the 3D world that is seen from bottom to top of the camera view Default: 75.0

fov_degrees: float

classmethod from_dict(camera_info: Dict[str, Any])

Create CameraData object from a simularium JSON dict

look_at_position: ndarray

position: ndarray

up_vector: ndarray

simulariumio.data_objects.dimension_data module

class simulariumio.data_objects.dimension_data.DimensionData(total_steps: int, max_agents: int, max_subpoints: int = 0)

Bases: object

This object contains dimension data

Parameters:

total_stepsint

The total number of timesteps in a trajectory

max_agentsint

The number of agents at the timestep with the most agents

max_subpointsint (optional)

The number of subpoints on the agent at any timestep with the most subpoints Default: 0

add(added_dimensions: DimensionData, axis: int = 1) → DimensionData

Add the given dimensions with this object’s and return a copy

max_agents: int

max_subpoints: int

total_steps: int

simulariumio.data_objects.display_data module

class simulariumio.data_objects.display_data.DisplayData(name: str, display_type: DISPLAY_TYPE, radius: float | None = None, url: str = '', color: str = '')

Bases: object

This object contains info about how to display an agent

Parameters:

namestr

A string display name for this type of agent Default: use names from simulator data if possible

display_type: DISPLAY_TYPE

the type of geometry to display Options: SPHERE, FIBER, PDB, OBJ, or SPHERE_GROUP

radiusfloat (optional)

A float radius for rendering this agent. For fibers, this is the thickness of the line For default agents, this is the scale of the representation Default : 1.0

url: str (optional)

local path or web URL for the geometry file to display, web URLs are required for streaming or loading the trajectory by URL Default: None

color: str (optional)

the hex value for the color to display, e.g “#FFFFFF” Default: Use default colors from Simularium Viewer

color: str

display_type: DISPLAY_TYPE

classmethod from_dict(display_info: Dict[str, Any], default_display_type: DISPLAY_TYPE = DISPLAY_TYPE.SPHERE)

Create DisplayData from a simularium JSON dict containing buffers.

name: str

radius: float

url: str

simulariumio.data_objects.frame_data module

class simulariumio.data_objects.frame_data.FrameData(frame_number: int, n_agents: int, time: float, data: bytes | Dict)

Bases: object

This object holds frame data for a single frame of simularium data

Parameters:

frame_numberint

Index of frame in the simulation

n_agentsint

Number of agents included in the frame

timefloat

Elapsed simulation time of the frame

databytes or dict

Spatial data for the frame, as a byte array for binary encoded .simularium files or as a dict for JSON .simularium files

simulariumio.data_objects.histogram_plot_data module

class simulariumio.data_objects.histogram_plot_data.HistogramPlotData(title: str, xaxis_title: str, traces: Dict[str, ndarray])

Bases: object

This object contains data for a scatterplot

Parameters:

title: str

A string display title for the plot

xaxis_title: str

A string label (with units) for the x-axis

traces: Dict[str, np.ndarray] (shape = [values])]

A dictionary with trace display names as keys, each mapped to a numpy ndarray of values

title: str

traces: Dict[str, ndarray]

xaxis_title: str

xtrace: ndarray

simulariumio.data_objects.input_file_data module

class simulariumio.data_objects.input_file_data.InputFileData(file_path: str = '', file_contents: str | bytes = '')

Bases: object

This object contains data about a file

Parameters:

file_path: str (optional)

A string path to the file Default: use file_contents instead

file_contents: str or bytes (optional)

A string of data from an opened file Default: use file_path instead

file_contents: str

file_path: str

get_contents()

Return the contents of the file.

If file_contents is not empty, return that. Otherwise try to open the file at file_path and return the data inside as a string or as bytes, for binary files.

simulariumio.data_objects.json_data module

class simulariumio.data_objects.json_data.JsonData(file_contents: str)

Bases: SimulariumFileData

This object holds JSON encoded simulation trajectory file’s data while staying close to the original file format

Parameters:

file_contentsstr

A string of the data of an open .simularium file

get_file_contents() → Dict

Return raw file data, as a dict

get_frame_at_index(frame_number: int) → FrameData

Return frame data for frame at index. If there is no frame at the index, return None.

get_index_for_time(time: float) → int

Return index for frame closest to a given timestamp

get_num_frames() → int

Return number of frames in the trajectory

get_plot_data() → Dict

Return plot data block for trajectory, as dict

get_trajectory_data_object() → TrajectoryData

Return the data of the trajectory, as a TrajectoryData object

get_trajectory_info() → Dict

Return trajectory info block for trajectory, as dict

simulariumio.data_objects.meta_data module

class simulariumio.data_objects.meta_data.MetaData(box_size: ndarray | None = None, camera_defaults: CameraData | None = None, scale_factor: float | None = None, trajectory_title: str = '', model_meta_data: ModelMetaData | None = None)

Bases: object

This object holds metadata for simulation trajectories

Parameters:

box_sizenp.ndarray (shape = [3]) (optional)

A numpy ndarray containing the XYZ dimensions of the simulation bounding volume Default: np.array([100, 100, 100])

camera_defaults: CameraData (optional)

camera’s initial settings which it also returns to when reset Default: CameraData()

scale_factorfloat (optional)

A multiplier for the scene, use if visualization is too large or small. If none is provided, one will be calculated based on the position data. Default: None

trajectory_titlestr (optional)

A title for this run of the model

model_meta_data: ModelMetaData (optional)

Metadata for the model that produced this trajectory

box_size: ndarray

camera_defaults: CameraData

classmethod from_dict(meta_info: Dict[str, Any])

Create MetaData from a simularium JSON dict containing buffers

model_meta_data: ModelMetaData

scale_factor: float

trajectory_title: str

simulariumio.data_objects.model_meta_data module

class simulariumio.data_objects.model_meta_data.ModelMetaData(title: str = '', version: str = '', authors: str = '', description: str = '', doi: str = '', source_code_url: str = '', source_code_license_url: str = '', input_data_url: str = '', raw_output_data_url: str = '')

Bases: object

This object holds metadata for a model that generates simulation trajectories Parameters ———- title : str (optional)

Display title for this model

versionstr (optional)

Version number of the model that produced this trajectory

authorsstr (optional)

Modelers name(s)

descriptionstr (optional)

Comments to display with the trajectories generated by this model

doistr (optional)

The DOI of the publication accompanying this model Note: if the URL for a DOI is provided,

the ID from the URL will be used

source_code_urlstr (optional)

If the code that generated this model is posted publicly, a link to the repository of source code

source_code_license_urlstr (optional)

A link to the license for the source code

input_data_urlstr (optional)

A link to any model configuration or parameter files posted publicly

raw_output_data_urlstr (optional)

A link to any raw outputs from the source code posted publicly

authors: str

description: str

doi: str

classmethod from_dict(model_info: Dict[str, Any])

Create ModelMetaData from a simularium JSON dict containing buffers

input_data_url: str

is_default()

Check if this ModelMetaData is only holding default data

raw_output_data_url: str

source_code_license_url: str

source_code_url: str

title: str

version: str

simulariumio.data_objects.scatter_plot_data module

class simulariumio.data_objects.scatter_plot_data.ScatterPlotData(title: str, xaxis_title: str, yaxis_title: str, xtrace: ndarray, ytraces: Dict[str, ndarray], render_mode: str = 'markers')

Bases: object

This object contains data for a scatterplot

Parameters:

title: str

A string display title for the plot

xaxis_title: str

A string label (with units) for the x-axis

yaxis_title: str

A string label (with units) for the y-axis

xtrace: np.ndarray (shape = [x values])

A numpy ndarray of values for x, the independent variable

ytraces: Dict[str, np.ndarray] (shape = [x values])]

A dictionary with y-trace display names as keys, each mapped to a numpy ndarray of values for y, the dependent variable

render_mode: str (optional)

A string specifying how to draw the datapoints. Options:

“markers” : draw as points “lines” : connect points with line

Default: “markers”

render_mode: str

title: str

xaxis_title: str

xtrace: ndarray

yaxis_title: str

ytraces: Dict[str, ndarray]

simulariumio.data_objects.simularium_file_data module

class simulariumio.data_objects.simularium_file_data.SimulariumFileData(file_contents: str | bytes)

Bases: ABC

abstract get_file_contents() → Dict | bytes

abstract get_frame_at_index(frame_number: int) → FrameData | None

abstract get_index_for_time(time: float) → int

abstract get_num_frames() → int

abstract get_plot_data() → Dict

abstract get_trajectory_data_object() → TrajectoryData

abstract get_trajectory_info() → Dict

simulariumio.data_objects.trajectory_data module

class simulariumio.data_objects.trajectory_data.TrajectoryData(meta_data: MetaData, agent_data: AgentData, time_units: UnitData | None = None, spatial_units: UnitData | None = None, plots: List[Dict[str, Any]] | None = None)

Bases: object

This object holds simulation trajectory outputs and plot data

Parameters:

meta_dataMetaData

An object containing metadata for the trajectory including box size, scale factor, and camera defaults

agent_dataAgentData

An object containing data for each agent at each timestep

time_units: UnitData (optional)

multiplier and unit name for time values Default: 1.0 second

spatial_units: UnitData (optional)

multiplier and unit name for spatial values Default: 1.0 meter

plotsList[Dict[str, Any]] (optional)

An object containing plot data already in Simularium format

agent_data: AgentData

append_agents(new_agents: AgentData)

Concatenate the new AgentData with the current data, generate new unique IDs and type IDs as needed

classmethod from_buffer_data(buffer_data: Dict[str, Any], display_data: Dict[int, DisplayData] | None = None)

Create TrajectoryData from a simularium JSON dict containing buffers

meta_data: MetaData

plots: List[Dict[str, Any]]

spatial_units: UnitData

time_units: UnitData

simulariumio.data_objects.unit_data module

class simulariumio.data_objects.unit_data.UnitData(name: str, magnitude: float = 1.0)

Bases: object

This object contains data for units

Parameters:

name: str

unit name for values (we support this list https://github.com/hgrecco/pint/blob/master/pint/default_en.txt)

magnitude: float (optional)

multiplier for values (in case they are not given in whole units) Default: 1.0

classmethod from_dict(unit_data: Dict[str, Any], default_name: str | None = None, default_mag: float = 1.0)

Create UnitData object from a simularium JSON dict

magnitude: float

multiply(multiplier: float)

multiply quantity and simplify

name: str

Module contents