Loader

PhysiCellSequence

A sequence of PhysiCell snapshots.

By default, only the simulation ID, index, and time are recorded for each PhysiCellSnapshot in the sequence. To include any of cells, substrates, mesh, attachments, spring_attachments, or neighbors, pass in the corresponding keyword argument as true (see below).

Fields

• simulation_id::Int: The ID of the simulation.
• snapshots::Vector{PhysiCellSnapshot}: A vector of PhysiCell snapshots.
• cell_type_to_name_dict::Dict{Int, String}: A dictionary mapping cell type IDs to cell type names.
• labels::Vector{String}: A vector of cell data labels.
• substrate_names::Vector{String}: A vector of substrate names.

Examples

sequence = PhysiCellSequence(1; include_cells=true, include_substrates=true) # loads cell and substrate data for simulation ID 1
sequence = PhysiCellSequence(simulation; include_attachments=true, include_spring_attachments=true) # loads attachment data for a Simulation object
sequence = PhysiCellSequence(1; include_mesh=true, include_neighbors=true) # loads mesh and neighbor data for simulation ID 1

PhysiCellSnapshot(simulation_id::Int, index::Union{Integer, Symbol}, labels::Vector{String}=String[], substrate_names::Vector{String}=String[]; kwargs...)

Creates a snapshot of the PhysiCell simulation with optional parameters to include various data types.

Arguments

• simulation_id::Int: The ID of the simulation. Can also be a Simulation object.
• index::Union{Integer, Symbol}: The index of the snapshot. Can be an integer or a symbol (:initial or :final).

Optional Arguments

• labels::Vector{String}=String[]: A vector of cell data labels.
• substrate_names::Vector{String}=String[]: A vector of substrate names.

Keyword Arguments

• include_cells::Bool=false: Whether to load cell data.
• cell_type_to_name_dict::Dict{Int, String}=Dict{Int, String}(): A dictionary mapping cell type IDs to cell type names.
• include_substrates::Bool=false: Whether to load substrate data.
• include_mesh::Bool=false: Whether to load mesh data.
• include_attachments::Bool=false: Whether to load attachment data.
• include_spring_attachments::Bool=false: Whether to load spring attachment data.
• include_neighbors::Bool=false: Whether to load neighbor data.

PhysiCellSnapshot

A single snapshot of a PhysiCell simulation.

The cells, substrates, mesh, and graphs (attachments, spring_attachments, neighbors) fields may remain empty until they are needed for analysis.

Fields

• simulation_id::Int: The ID of the simulation.
• index::Union{Int,Symbol}: The index of the snapshot. Can be an integer or a symbol (:initial or :final).
• time::Float64: The time of the snapshot (in minutes).
• cells::DataFrame: A DataFrame containing cell data.
• substrates::DataFrame: A DataFrame containing substrate data.
• mesh::Dict{String, Vector{Float64}}: A dictionary containing mesh data.
• attachments::MetaGraph: A graph of cell attachment data with vertices labeled by cell IDs.
• spring_attachments::MetaGraph: A graph of spring attachment data with vertices labeled by cell IDs.
• neighbors::MetaGraph: A graph of cell neighbor data with vertices labeled by cell IDs.

Examples

simulation_id = 1
index = 3 # index of the snapshot in the output folder
snapshot = PhysiCellSnapshot(simulation_id, index)

simulation = Simulation(simulation_id)
index = :initial # :initial or :final are the accepted symbols
snapshot = PhysiCellSnapshot(simulation, index)

cellDataSequence(simulation_id::Integer, labels::Vector{String}; include_dead::Bool=false, include_cell_type_name::Bool=false)

Return an AgentDict where the keys are cell IDs from the PhysiCell simulation and the values are NamedTuples containing the time and the values of the specified labels for that cell.

For scalar values, such as volume, the values are in a length N vector, where N is the number of snapshots in the simulation. In the case of a label that has multiple columns, such as position, the values are concatenated into a length(snapshots) x number of columns array. Note: If doing multiple calls to this function, it is recommended to use the PhysiCellSequence object so that all the data is loaded one time instead of once per call.

Arguments

• simulation_id::Integer: The ID of the PhysiCell simulation. Alternatively, can be a Simulation object or a PhysiCellSequence object.
• labels::Vector{String}: The labels to extract from the cell data. If a label has multiple columns, such as position, the columns are concatenated into a single array. Alternatively, a single label string can be passed.
• include_dead::Bool=false: Whether to include dead cells in the data.
• include_cell_type_name::Bool=false: Whether to include the cell type name in the data. Equivalent to including "cell_type_name" in labels.

Examples

data = cellDataSequence(sequence, ["position", "elapsed_time_in_phase"]; include_dead=true, include_cell_type_name=true)
data[1] # the data for cell with ID 1
data[1].position # an Nx3 array of the cell's position over time
data[1].elapsed_time_in_phase # an Nx1 array of the cell's elapsed time in phase over time
data[1].cell_type_name # an Nx1 array of the cell type name of the first cell over time

getCellDataSequence(args...; kwargs...)

Deprecated alias for cellDataSequence. Use cellDataSequence instead.

loadCells!(S::AbstractPhysiCellSequence[, cell_type_to_name_dict::Dict{Int, String}=Dict{Int, String}(), labels::Vector{String}=String[]])

Load the cell data for a PhysiCell simulation into an AbstractPhysiCellSequence object.

If the cell_type_to_name_dict and labels are not provided, they will be loaded from the XML file. Users do not need to compute and pass these in.

Arguments

• S::AbstractPhysiCellSequence: The sequence or snapshot to load the cell data into.
• cell_type_to_name_dict::Dict{Int, String}=Dict{Int, String}(): A dictionary mapping cell type IDs to cell type names. If not provided, it will be loaded from the XML file.
• labels::Vector{String}=String[]: A vector of cell data labels. If not provided, they will be loaded from the XML file.

Examples

simulation = Simulation(1)
sequence = PhysiCellSequence(simulation) # does not load cell data without setting `PhysiCellSequence(simulation; include_cells=true)`
loadCells!(sequence)

loadGraph!(S::AbstractPhysiCellSequence, graph::Symbol)

Load a graph for a snapshot or sequence into a MetaGraph(s).

Arguments

• S::AbstractPhysiCellSequence: The AbstractPhysiCellSequence object to load the graph into.
• graph: The type of graph to load (must be one of :attachments, :spring_attachments, or :neighbors). Can also be a string.

loadMesh!(S::AbstractPhysiCellSequence)

Load the mesh data for a PhysiCell simulation into an AbstractPhysiCellSequence object.

Arguments

• S::AbstractPhysiCellSequence: The sequence or snapshot to load the mesh data into.

loadSubstrates!(S::AbstractPhysiCellSequence[, substrate_names::Vector{String}=String[]])

Load the substrate data for a PhysiCell simulation into an AbstractPhysiCellSequence object.

If the substrate_names are not provided, they will be loaded from the XML file. Users do not need to compute and pass these in.

Arguments

• S::AbstractPhysiCellSequence: The sequence or snapshot to load the substrate data into.
• substrate_names::Vector{String}=String[]: The names of the substrates to load. If not provided, they will be loaded from the XML file.

AbstractPhysiCellSequence

Abstract type representing either a single snapshot or a sequence of snapshots from a PhysiCell simulation.

AgentDict{T} <: AbstractDict{AgentID,T}

A dictionary-like structure that maps AgentIDs to values of type T. Integers can be passed as keys and they will be converted to AgentIDs.

AgentID

A wrapper for the agent ID used in PhysiCell.

The purpose of this struct is to make it easier to interpret the data in the MetaGraphs loaded from PhysiCell. The MetaGraphs use Ints to index the vertices, which could cause confusion when looking at the mappings to the agent ID metadata if also using Ints.

_loadCells!(cells::DataFrame, filepath_base::String, cell_type_to_name_dict::Dict{Int, String}=Dict{Int, String}(), labels::Vector{String}=String[])

Internal function to load cell data into a DataFrame associated with an AbstractPhysiCellSequence object.

_loadGraph!(G::MetaGraph, path_to_txt_file::String)

Load a graph from a text file into a MetaGraph.

Users should use loadGraph! with an AbstractPhysiCellSequence object instead of this function directly.`

_loadMesh!(mesh::Dict{String, Vector{Float64}}, xml_doc::XMLDocument)

Internal function to load mesh data into a dictionary associated with an AbstractPhysiCellSequence object.

_loadSubstrates!(substrates::DataFrame, filepath_base::String, substrate_names::Vector{String}=String[])

Internal function to load substrate data into a DataFrame associated with an AbstractPhysiCellSequence object.

cellLabels(simulation::Simulation)

Return the labels from the XML file for a PhysiCell simulation, i.e., the names of the cell data fields.

Arguments

• simulation: The simulation object. Can also use the simulation ID, an AbstractPhysiCellSequence, XMLDocument, or the path to the XML file (String).

cellTypeToNameDict(simulation::Simulation)

Return a dictionary mapping cell type IDs to cell type names from the simulation.

Arguments

• simulation: The simulation object. Can also use the simulation ID, an AbstractPhysiCellSequence, XMLDocument, or the path to the XML file (String).

graphInfo(g::MetaGraph)

Return a string describing the graph.

Used for printing the graph information in the show function.

indexToFilename(index)

Convert an index to a filename in the output folder.

The index can be an integer or a symbol (:initial or :final).

julia> pcvct.indexToFilename(0)
"output00000000"

julia> pcvct.indexToFilename(:initial)
"initial"

meshInfo(S::AbstractPhysiCellSequence)

Return a string describing the mesh for an AbstractPhysiCellSequence object.

pathToOutputFileBase(simulation_id::Integer, index::Union{Integer,Symbol})

Return the path to the output files for a snapshot of a PhysiCell simulation, i.e., everything but the file extension.

pathToOutputFileBase(snapshot::PhysiCellSnapshot)

Return the path to the output files for a snapshot of a PhysiCell simulation, i.e., everything but the file extension.

pathToOutputFolder(simulation_id::Integer)

Return the path to the output folder for a PhysiCell simulation.

pathToOutputXML(simulation_id::Integer, index::Union{Integer,Symbol}=:initial)

Return the path to the XML output file for a snapshot of a PhysiCell simulation. Can also pass in a Simulation object for the first argument.

pathToOutputXML(snapshot::PhysiCellSnapshot)

Return the path to the XML output file for a snapshot of a PhysiCell simulation.

physicellEmptyGraph()

Create an empty graph for use with PhysiCell.

For all PhysiCell graphs, the vertices are labeled with AgentIDs and the vertices carry no other information. The edges also carry no extra information other than that the edge exists.

readPhysiCellGraph!(g::MetaGraph, path_to_txt_file::String)

Read a PhysiCell graph from a text file into a MetaGraph.

Users should use loadGraph! instead of this function directly.

substrateNames(simulation::Simulation)

Return the names of the substrates from the simulation.

Arguments

• simulation: The simulation object. Can also use the simulation ID, an AbstractPhysiCellSequence, XMLDocument, or the path to the XML file (String).