dna/wholeNuclearDNA/README.md

0001 \page ExampleWholeNuclearDNA Example wholeNuclearDNA
0002
0003 \author For any question, please contact: \n
0004 C. Villagrasa \n
0005 email: carmen.villagrasa@irsn.fr
0006
0007 This example is provided by the Geant4-DNA collaboration
0008 Any report or published results obtained using the Geant4-DNA software
0009 and the DNA geometry given in the Geom_DNA example
0010 shall cite the following Geant4-DNA collaboration publications: \n
0011 [1] NIM B 298 (2013) 47-54 \n
0012 [2] Med. Phys. 37 (2010) 4692-4708 \n
0013 [3] Phys. Med. 31 (2015) 861-874
0014
0015 ## INTRODUCTION
0016
0017 The wholenucleardna example offers the basic tools to simulate the track structure
0018 of different charge particles within a
0019 simplified geometrical model of the DNA molecule contained in a cell nucleus.
0020 In this example, the DetectorConstruction file contains the placement of the
0021 6 Gbp (base-pairs) of a human cell respecting five compaction levels in the
0022 structure of the DNA molecule: double helix, nucleosome, chromatin fiber,
0023 simple chromatin fiber loop and complex chromatin fiber loops.
0024 These complex chromatin fiber loops are then used to fill the chromosome
0025 territories using a constant density (~30-31 kbp/µm3.
0026 Even though this geometry defines different volumes for the DNA base, the
0027 back-bone region or the histone proteins, the material filling all these volumes
0028 in the simulation is liquid water ("G4_WATER")
0029
0030 In order to simulate all the energy transfer points of the track at nanometric
0031 level, the Geant4-DNA physics processes and models are used.
0032 These processes and models are further described at:
0033 http://geant4-dna.org
0034
0035 ## GEOMETRY SET-UP
0036
0037 As indicated in the introduction, the whole DNA molecule contained in a human
0038 cell with 5 different compaction levels is described in this geometry. In order
0039 to place the complex chromatin loops in each of the 43 chromosome territories,
0040 the files called "chromo-number.dat" are needed.
0041 These 43 chromosome territories are then placed in an ellipsoid that has the
0042 typical dimensions of a human fibroblast cell nucleus.
0043 All the volumes in the geometry are made of liquid water (G4_WATER
0044 material) despite of what they geometrically represent.
0045 Particles are shot from a random (x,y)position covering the main central part of
0046 the cell nucleus and at z=2.99 µm from the center of the nucleus. This value
0047 allows the primary particle to be either inside the cell nucleus, either not far
0048 from the entrance surface so its energy loss before the cell nucleus entrance is
0049 negligible.
0050
0051 WARNING: By default, the bases are not built. To build the whole geometry, set the
0052 flag fBuildBases in DetectorConstruction to true.
0053
0054 ## SET-UP
0055
0056 Make sure G4LEDATA points to the low energy electromagnetic data files.
0057
0058 The variable G4ANALYSIS_USE must be set to 1.
0059
0060 The code can be compiled with gmake.
0061
0062 ## HOW TO RUN THE EXAMPLE
0063
0064 In normal mode, without interactivity:
0065
0066 ```
0067 ./wholeNuclearDNA
0068 ```
0069
0070 In interactive mode, run:
0071 ```
0072 wholeNuclearDNA -gui -out
0073 ```
0074
0075 The -gui option launches a user interface for interactivity
0076 The -out option create a root file (can be changed for other format). This option may also take argument to set the name of the file (name of the application by default):
0077 ```
0078 wholeNuclearDNA -gui -out MyFile
0079 ```
0080
0081 The macro wholenucleardna.in is executed by default. A proton of 0.1 MeV is shot. This energy has been chosen because only a few minutes are needed for the proton to lose all its energy and thus the event to finish. Nevertheless, one should keep in mind that for this energy, protons do not traverse the whole cell nucleus width.
0082
0083 Visualization (DAWN) is not activated by default in wholenucleardna.mac. To get visualization, make sure to uncomment the #/control/execute vis.mac.
0084 We would like to warn the users that the time to visualize the whole DNA structure is extremely long.
0085
0086 To build the whole geometry, set the flag fBuildBases in DetectorConstruction to true.
0087
0088 ## PHYSICS
0089
0090 This example uses the Geant4-DNA processes, using the G4EmDNAPhysics constructor
0091 as in the dnaphysics example.
0092
0093 ## SIMULATION OUTPUT AND RESULT ANALYSIS
0094
0095 The output results consist in a wholenucleardna.root file, containing only the
0096 information about the energy transfers located in the backbone region of the DNA
0097 double helix. Both strands are distinguished with different flags (1 or 2):
0098 - the type of particle for the current step
0099 - the type of process for the current step
0100 - the flag of the strand (1 or 2)
0101 - the track position of the current energy transfer (in nanometers)
0102 - the energy deposit corresponding to the energy transfer (in eV)
0103 - the total energy loss along the current step (in eV)
0104 - the step length (in nm)
0105
0106
0107 This file can be easily analyzed using for example the provided ROOT macro
0108 file plot.C; to do so :
0109 * be sure to have ROOT installed on your machine
0110 * be sure to be in the directory containing the ROOT files created by
0111 * wholenucleardna
0112 * copy plot.C into this directory
0113 * from there, launch ROOT by typing root
0114 * under your ROOT session, type in : .X plot.C to execute the macro file
0115 * alternatively you can type directly under your session : root plot.C
0116
0117 The naming scheme on the displayed ROOT plots can be seen in the
0118 SteppingAction.cc file.
0119
0120