dna/neuron/README.md

0001 \page Exampleneuron Example neuron
0002
0003 \authors M. Batmunkh *(a,b), L. Bayarchimeg (a) \n
0004 (a) Laboratory of Radiation Biology, Joint Institute for Nuclear Research (JINR),
0005 6 Joliot-Curie St., 141980 Dubna, Moscow Region, Russia  \n
0006 (b) Division of Natural Sciences, National University of Mongolia (NUM),
0007 1 University St., 210646 Ulaanbaatar, Mongolia \n
0008 * Corresponding author, email to batmunkh@jinr.ru \n
0009
0010 Any report or published results obtained using the Geant4-DNA software shall
0011 cite the following Geant4-DNA collaboration publications:\n
0012 Phys. Med. 31 (2015) 861-874                             \n
0013 Med. Phys. 37 (2010) 4692-4708                           \n\n
0014
0015 We also suggest these other references related to this example:\n
0016 Phys. Part. Nucl. 56 (2025) 1030-1058                          \n
0017 Phys. Part. Nucl. Lett. 16 (2019) 54–62                        \n
0018 Physica Medica. 57 (2019) 88-94                                \n
0019 EPJ Web Conf. 173 (2018) 05005                                 \n
0020 Physica Medica. 32 (2016) 1510-1520                            \n
0021 Radiat Res Appl Sci. V (2015) 498-507                          \n\n
0022
0023 ## INTRODUCTION
0024
0025 The NEURON example allows for the modelling of neuron cell irradiation, including physical,
0026 physico-chemical and chemical processes (eg. production of oxidative radical species in the
0027 vicinity of neurons). It uses realistic geometrical models of neurons generated from a
0028 standardized SWC file representing neuron morphology.
0029
0030 A typical neuron cell is composed of a cell body (soma), a single axon, a dendritic tree,
0031 and thousands of dendritic spines. In the example, individual compartments of a neuron cell
0032 are simulated by spherical and cylindrical voxels.
0033 The soma is represented by combination of several spheres, while the dendritic tree is described with combinations of cylinders.
0034 Each voxel is represented as interconnection of two tracing points of the neuron model.
0035
0036 A standardized neuromorphometric format (SWC) is an output file representing individual neuron
0037 morphology generated by digitally tracing tools based on 3D confocal microscopy images.
0038 In the SWC file, different numerical markers (e.g. from 1 to 6) describe different types of tracing points:
0039 - 1 - soma
0040 - 2 - axon
0041 - 3 - apical dendrite
0042 - 4 - basal dendrite
0043 - 5+ - custom (5 – spines, 6 – terminals, etc.).
0044 Details are available in the NeuronLoadDataFile class.
0045
0046 In order to simulate a neural network, user can create his own file containing
0047 a combination of several individual neurons (see NeuralNETWORK.dat sample file
0048 describing a network of 10 pyramidal neurons).
0049
0050 Geant4-DNA models are activated in the neuron model, which is declared as a G4Region.
0051 Geant4 condensed EM models are used outside the neuron structure.
0052
0053 The example package contains:
0054 - source files (src, include, neuron.cc)
0055 - README
0056 - .in, plotDend.C and visualization macro files
0057 - GranuleCell-Nr2.CNG.swc (Sample file describing a single granule neuron is loaded by default)
0058 - NeuralNETWORK.dat (Sample file describing a network of 10 pyramidal neurons)
0059
0060 To run the example: see section HOW TO RUN THE EXAMPLE of this README. \n
0061 To simulation output: see section SIMULATION OUTPUT AND RESULT ANALYSIS of this README.
0062
0063 The code can be compiled with cmake.
0064 It works in MT mode.
0065
0066 ## GEOMETRY SET-UP
0067
0068 The geometry is cube (World) made of galactic material.
0069 Before computation, user loads a standardized SWC file of a neuron and generates
0070 a bounding volume and a homogeneous spherical medium of liquid water.
0071 Dimensions of the target volume are automatically extrapolated using SWC file describing
0072 3D coordinates of a neuron. The homogeneous medium contains volumes of neuronal cell and a bounding slice.
0073 The side cube (World) is again represented as overall dimensions of neuronal cell
0074 that is equal to the diameter of the homogeneous medium.
0075
0076 The construction of whole geometry of neuron morphology is set in the
0077 DetectorConstruction class.
0078
0079 User can choose between single-neuron simulation and modelling a neural network. Single-neuron
0080 simulation is set by default. To switch simulation to neural network, the following command should be used:
0081 > ./neuron -network FileName.dat
0082
0083 ## EVENT: THE PRIMARY GENERATOR
0084
0085 The primary kinematic consists of a single particle starting at the random positions
0086 on the sphere surface. Then, the particle beam is directed towards the bounding slice volume,
0087 and traverses the individual neurons (default option). The type of the particle and its energy are set in the
0088 PrimaryGeneratorAction class, and can be changed via the G4 build-in commands of G4ParticleGun class.
0089 We included the following options for particle directions:
0090
0091 a) Particles are directed to "square" on the XY plane of bounding slice (or YZ, XZ)
0092 > ./neuron -mac myMacro.mac -sXY
0093
0094 b) Particles are directed to "disk" on the XY plane of bounding slice (or YZ, XZ)
0095 > ./neuron -mac myMacro.mac -dXY
0096
0097 c) Particles are directed towards the bounding slice (default option)
0098 > ./neuron -mac myMacro.mac
0099
0100 ## PHYSICS
0101
0102 The following options of physical and chemical processes are included:
0103 Default Livermore physics
0104 > ./neuron -mac myMacro.mac
0105
0106 a) Livermore + DNAphysics when use DNARegion in myMacro.mac file
0107 > ./neuron -mac myMacro.mac
0108
0109 b) Livermore + DNAPhysics + DNAChemistry
0110 > ./neuron -mac myMacro.mac -dnachemON
0111
0112 c) Combination of DNA- and Livermore- physics with hadronic physics.
0113 > ./neuron -mac myMacro.mac -dnahad
0114
0115 NOTE, that it requires more memory or computing resources when chemistry is ON (b) and
0116 also long computational time when dnaphysics activated. Conversely, it can works faster when default.
0117
0118 Look at the src/PhyscisList.cc files.
0119
0120 ## HOW TO RUN THE EXAMPLE
0121
0122 To get help, run:
0123
0124 > ./neuron -h
0125
0126 In visualization and interactive mode, run:
0127 > ./neuron -gui
0128 ( OGL used by default)
0129
0130 or you may use your own visualization driver, for instance:
0131 > ./neuron -vis "DAWNFILE"
0132
0133 "GranuleCell-Nr2.CNG.swc" is the default file and it should be placed into same directory as the executable.
0134 You can download it here:
0135 http://neuromorpho.org/neuron_info.jsp?neuron_name=GranuleCell-Nr2
0136 You can change neuron`s file name using the following command:
0137
0138 > ./neuron -gui -swc newFileName.swc
0139
0140 In batch mode , run:
0141
0142 > ./neuron(.exe) [-mac neuron.in] [-mt numberofThreads]
0143 > ./neuron -mac ../neuron.in -mt 3 > neuron.out
0144
0145 To get visualization, make sure to uncomment the #/control/execute vis.mac line in the macro.
0146 User can start a visualization of the chemical track evolution in time and space
0147 using SetEndTime (default-10 ps) and SetVerbose setting in src/ActionInitialization.cc file.
0148
0149 ## SIMULATION OUTPUT AND RESULT ANALYSIS
0150
0151 The simulation outputs appears in terminal display.
0152 - the energy deposit in the bounding slice and each structure of neuron (in kiloelectronVolt)
0153 - the scored energy deposit within hitting compartment of neuron structure (in kiloelectronVolt)
0154 - the number of particles inside and outside neuron
0155 - the number of radiolytic species inside neuron when chemistry is activated
0156
0157 The main output results are stored in OutputPerEvent.out file, containing for each event.
0158 Dend3DEdep.out, Axon3DEdep.out and Soma3DEdep.out files for given dose:
0159 - the position (x, y, z in micrometre) of compartments traversed by particle track.
0160 - the Axon and Dendrite (basal and apical) distance of compartments from Soma (in micrometre).
0161 - the energy deposition in compartments (in kiloelectronVolt).
0162 - the dose deposition in compartments (in Gray).
0163
0164 This file can be easily analysed using for example the provided ROOT macro
0165 file plotDend.C; to do so:
0166 - be sure to have ROOT installed on your machine
0167 - be sure to be in the neuron directory
0168 - launch ROOT by typing root
0169 - under your ROOT session, type in : .X plotDend.C to execute the macro file
0170 - alternatively you can type directly under your session : root plotDend.C
0171
0172 ---------------------------------------------------------------------------
0173
0174 If you have any questions or wish to notify of updates and/or modification please contact:
0175 batmunkh@jinr.ru \n