tpcisotope.h File Reference

Header file for library libtpcisotope. More...

#include "tpcclibConfig.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <strings.h>
#include <ctype.h>
#include <math.h>
#include "tpcextensions.h"

Go to the source code of this file.

Macros
#define	MAX_ATOMIC_NUMBER   118
	Max atomic number, and the size of element_symbol and element_name lists.
#define	M_LN2   0.69314718055994530942
	Defined ln(2) for faster computations.
#define	MAX_ISOTOPE_LEN   16
	Max string length for PET isotope.

Enumerations
enum	isotope {   ISOTOPE_UNKNOWN , ISOTOPE_BR_75 , ISOTOPE_BR_76 , ISOTOPE_CU_62 ,   ISOTOPE_CU_64 , ISOTOPE_FE_52 , ISOTOPE_GA_68 , ISOTOPE_GE_68 ,   ISOTOPE_NA_22 , ISOTOPE_RB_82 , ISOTOPE_SC_44 , ISOTOPE_TB_152 ,   ISOTOPE_ZN_62 , ISOTOPE_ZR_89 , ISOTOPE_C_11 , ISOTOPE_F_18 ,   ISOTOPE_I_124 , ISOTOPE_N_13 , ISOTOPE_O_15 , ISOTOPE_O_14 }
enum	decaycorrection {   DECAY_UNKNOWN , DECAY_NOTCORRECTED , DECAY_CORRECTED , DECAY_CORRECTED_START ,   DECAY_CORRECTED_ADMIN }

Functions
char *	elementName (unsigned short int z)
char *	elementSymbol (unsigned short int z)
unsigned short int	elementIdentify (const char *str)
double	isotopeHalflife (int isotope)
double	isotopeBranching (int isotope)
char *	isotopeName (int isotope)
int	isotopeIdentifyHalflife (double halflife)
int	isotopeIdentify (const char *isotope)
char *	decayDescr (decaycorrection d)
double	lambdaFromHalflife (double halflife)
double	lambdaFromIsotope (int isotope)
double	decayCorrectionFactorFromLambda (double lambda, double starttime, double duration)
double	decayCorrectionFactorFromIsotope (int isotope, double starttime, double duration)
double	noiseSD4Frame (double y, double t1, double dt, int isotope, double a)

Detailed Description

Header file for library libtpcisotope.

Isotope half-lives and branching fractions are based on the following references, except isotopes Br-75, Br-76, Cu-62, Cu-64, Fe-52, O-14, Rb-82, Zn-62, I-124, which thus should be treated with caution.
References:

1. Table of Isotopes, Sixth edition, edited by C.M. Lederer, J.M. Hollander, I. Perlman. WILEY, 1967.
2. Monographie BIPM-5, Table of Radionuclides, Vol. 6, 2011, http://www.bipm.org/en/publications/monographies-ri.html.

Author

Vesa Oikonen

Definition in file tpcisotope.h.

Macro Definition Documentation

M_LN2

#define M_LN2   0.69314718055994530942

Defined ln(2) for faster computations.

Definition at line 37 of file tpcisotope.h.

Referenced by lambdaFromHalflife(), and lambdaFromIsotope().

MAX_ATOMIC_NUMBER

#define MAX_ATOMIC_NUMBER   118

Max atomic number, and the size of element_symbol and element_name lists.

Definition at line 33 of file tpcisotope.h.

Referenced by elementIdentify(), elementName(), and elementSymbol().

MAX_ISOTOPE_LEN

#define MAX_ISOTOPE_LEN   16

Max string length for PET isotope.

Definition at line 41 of file tpcisotope.h.

Referenced by tacGetHeaderIsotope(), tacGetIsotope(), tacReadSIF(), and tacWriteSIF().

Enumeration Type Documentation

decaycorrection

enum decaycorrection

Is data corrected for physical decay or not?

See also

decay.c, decayDescr

Enumerator
DECAY_UNKNOWN	Not known; usually assumed that data is corrected.
DECAY_NOTCORRECTED	Data is not corrected for physical decay.
DECAY_CORRECTED	Data is corrected for physical decay.
DECAY_CORRECTED_START	Data is corrected for physical decay to scan start time.
DECAY_CORRECTED_ADMIN	Data is corrected for physical decay to radioligand administration time.

Definition at line 78 of file tpcisotope.h.

             {
  DECAY_UNKNOWN,         
  DECAY_NOTCORRECTED,    
  DECAY_CORRECTED,       
  DECAY_CORRECTED_START, 
  DECAY_CORRECTED_ADMIN  
} decaycorrection;

isotope

enum isotope

isotope_code, same as isotopes position in isotope table (table can not be accessed directly outside the c file).

See also

isotope.c, isotopeName, isotopeIdentify

Enumerator
ISOTOPE_UNKNOWN	Unknown.
ISOTOPE_BR_75	Br-75.
ISOTOPE_BR_76	Br-76.
ISOTOPE_CU_62	Cu-62.
ISOTOPE_CU_64	Cu-64.
ISOTOPE_FE_52	Fe-52.
ISOTOPE_GA_68	Ga-68.
ISOTOPE_GE_68	Ge-68.
ISOTOPE_NA_22	Na-22.
ISOTOPE_RB_82	Rb-82.
ISOTOPE_SC_44	Sc-44.
ISOTOPE_TB_152	Tb-152.
ISOTOPE_ZN_62	Zn-62.
ISOTOPE_ZR_89	Zr-89.
ISOTOPE_C_11	C-11.
ISOTOPE_F_18	F-18.
ISOTOPE_I_124	I-124.
ISOTOPE_N_13	N-13.
ISOTOPE_O_15	O-15.
ISOTOPE_O_14	O-14.

Definition at line 50 of file tpcisotope.h.

             {
  ISOTOPE_UNKNOWN, 
  ISOTOPE_BR_75,   
  ISOTOPE_BR_76,   
  ISOTOPE_CU_62,   
  ISOTOPE_CU_64,   
  ISOTOPE_FE_52,   
  ISOTOPE_GA_68,   
  ISOTOPE_GE_68,   
  ISOTOPE_NA_22,   
  ISOTOPE_RB_82,   
  ISOTOPE_SC_44,   
  ISOTOPE_TB_152,  
  ISOTOPE_ZN_62,   
  ISOTOPE_ZR_89,   
  ISOTOPE_C_11,    
  ISOTOPE_F_18,    
  ISOTOPE_I_124,   
  ISOTOPE_N_13,    
  ISOTOPE_O_15,    
  ISOTOPE_O_14     
} isotope;

Function Documentation

decayCorrectionFactorFromIsotope()

double decayCorrectionFactorFromIsotope ( int isotope, double starttime, double duration )

extern

Calculate the correction factor for physical decay from measurement time to time zero.

Returns

Factor for decay correction (>1), or NaN if input is invalid.

See also

lambdaFromIsotope, isotopeIdentify, decayCorrectionFactorFromLambda, isotopeName

Author

Vesa Oikonen

Parameters

isotope	isotope_code as enum or the index of isotope in isotope table.
starttime	Radioactivity measurement start time, or middle time, if measurement duration is not known. Unit must be min.
duration	Radioactivity measurement duration; if not known, then set to zero, and put measurement middle time for starttime. Unit must be min.

Definition at line 107 of file decay.c.

  {
  double lambda=lambdaFromIsotope(isotope); if(isnan(lambda)) return nan("");
  return decayCorrectionFactorFromLambda(lambda, starttime, duration);
}

Referenced by noiseSD4Frame(), and sifWeight().

decayCorrectionFactorFromLambda()

double decayCorrectionFactorFromLambda ( double lambda, double starttime, double duration )

extern

Calculate the correction factor for physical decay from measurement time to time zero.

Returns

Factor for decay correction (>1 when lambda>0) or for simulating decay (<1 when lambda<0), or NaN if input is invalid.

See also

lambdaFromIsotope, isotopeIdentify, decayCorrectionFactorFromIsotope

Author

Vesa Oikonen

Parameters

lambda	Positive or negative lambda for the isotope. Note that time unit must be 1/timeunit of the starttime and duration.
starttime	Radioactivity measurement start time, or middle time, if measurement duration is not known.
duration	Radioactivity measurement duration; if not known, then set to zero, and put measurement middle time for starttime.

Definition at line 79 of file decay.c.

  {
  if(starttime<0.0) return nan("");
  if(duration<0.0) duration=0.0;
  if(fabs(lambda)<1.0E-100) return nan("");
  double cf=exp(lambda*starttime);
  if(duration>1.0E-10) {
    double ff=fabs(lambda)*duration/(1.0-exp(-fabs(lambda)*duration));
    if(lambda<0.0) cf/=ff; else cf*=ff;
  }
  return(cf);
}

Referenced by decayCorrectionFactorFromIsotope(), tacDecayCorrection(), and tacWByFreq().

decayDescr()

char * decayDescr ( decaycorrection d )

extern

Return pointer to string describing the status of decay correction.

See also

isotopeName

Returns

pointer to the name string.

Parameters

d	Enum decaycorrection.

Definition at line 32 of file decay.c.

  {
  if(d>4) return(decay_correction[0]);
  return(decay_correction[d]);
}

Referenced by dcmImgIsotope(), and imgReadDICOM().

elementIdentify()

unsigned short int elementIdentify ( const char * str )

extern

Identify the given string representation of element name or symbol.

See also

elementName, elementSymbol, isotopeIdentify

Returns

Element atomic number Z, or 0 if not identified.

Parameters

str	Name or symbol of element, for example 'Carbon' or 'C'.

Definition at line 298 of file elements.c.

  {
  if(str==NULL || strnlen(str, 5)<1) return(0); 
 
  /* First, search string from the list of element names */
  for(unsigned short int z=1; z<MAX_ATOMIC_NUMBER; z++)
    if(strcasecmp(str, element_name[z])==0) return(z);
 
  /* Then, search string from the list of element symbols */
  for(unsigned short int z=1; z<MAX_ATOMIC_NUMBER; z++)
    if(strcasecmp(str, element_symbol[z])==0) return(z);
 
  /* Not yet successful; then try to find element name as part of the string */
  for(unsigned short int z=1; z<MAX_ATOMIC_NUMBER; z++)
    if(strcasestr(str, element_name[z])!=NULL) return(z);
 
  /* Then try to find two-char element symbol as part of the string */
  for(unsigned short int z=1; z<MAX_ATOMIC_NUMBER; z++)
    if(strlen(element_symbol[z])>1 && strstr(str, element_symbol[z])!=NULL) return(z);
  /* Desperate last step... try to find one-char element symbol as part of the string */
  for(unsigned short int z=1; z<MAX_ATOMIC_NUMBER; z++)
    if(strlen(element_symbol[z])==1 && strstr(str, element_symbol[z])!=NULL) return(z);
 
  return(0);
}

Referenced by isotopeIdentify().

elementName()

char * elementName ( unsigned short int z )

extern

Return pointer to element name.

See also

elementSymbol, elementIdentify

Returns

pointer to the name string.

Parameters

z	Atomic number (Z) of the element.

Definition at line 270 of file elements.c.

  {
  if(z>MAX_ATOMIC_NUMBER) return(element_name[0]);
  return(element_name[z]);
}

elementSymbol()

char * elementSymbol ( unsigned short int z )

extern

Return pointer to element symbol.

See also

elementName, elementIdentify

Returns

pointer to the symbol string.

Parameters

z	Atomic number (Z) of the element.

Definition at line 284 of file elements.c.

  {
  if(z>MAX_ATOMIC_NUMBER) return(element_name[0]);
  return(element_symbol[z]);
}

isotopeBranching()

double isotopeBranching ( int isotope_code )

extern

Get the branching ratio (fraction) of an isotope spcecified with its isotope_code.

See also

isotopeHalflife, isotopeName, lambdaFromIsotope, decayCorrectionFactorFromIsotope

Returns

branching ratio of the isotope, or NaN if not identified.

Author

Vesa Oikonen

Parameters

isotope_code

isotope_code as enum or the index of isotope in isotope table

Definition at line 81 of file isotope.c.

  {
  int n=0;
  
  while(strlen(tpc_isotope[n].name)>1) n++;
  if(isotope_code<1 || isotope_code>n-1) return nan("");
  else if(tpc_isotope[isotope_code].br<1.0E-10) return nan("");
  else return(tpc_isotope[isotope_code].br);
}

isotopeHalflife()

double isotopeHalflife ( int isotope_code )

extern

Get the half-life (in minutes) of an isotope specified with its isotope_code.

See also

isotopeBranching, isotopeName, lambdaFromIsotope, decayCorrectionFactorFromIsotope

Returns

halflife of the isotope in minutes, or NaN if not identified.

Author

Vesa Oikonen

Parameters

isotope_code

isotope_code as enum or the index of isotope in isotope table.

Definition at line 62 of file isotope.c.

  {
  int n=0;
  
  while(strlen(tpc_isotope[n].name)>1) n++;
  if(isotope_code<1 || isotope_code>n-1) return nan("");
  else return(tpc_isotope[isotope_code].hl);
}

Referenced by abssWrite(), imgWriteDICOM(), lambdaFromIsotope(), and tacDecayCorrection().

isotopeIdentify()

int isotopeIdentify ( const char * isotope )

extern

Identify the given string representation of isotope, whether it is in format like 'C-11', '11C', '^11^C', or '^11^Carbon'. Even a one-letter symbol like 'C' may be accepted for the most common PET isotopes.

See also

isotopeHalflife, isotopeName, lambdaFromIsotope, decayCorrectionFactorFromIsotope, elementIdentify

Returns

Isotope code, or 0 (enum ISOTOPE_UNKNOWN) if not identified.

Author

Vesa Oikonen

Parameters

isotope

Name of isotope to identify.

Definition at line 145 of file isotope.c.

  {
  if(isotope==NULL || strnlen(isotope, 5)<1) return ISOTOPE_UNKNOWN; 
 
  unsigned short int i, n=0;
  while(strlen(tpc_isotope[n].name)>1) n++;
 
  /* Check, if isotope can be found directly in the table */
  for(i=0; i<n; i++) {
    if(strcasecmp(tpc_isotope[i].name, isotope)==0) return(i);
  }
 
  /* Ok it was not that easy... try to figure out what it is */
  char *cptr;
  int mass_nr=0, ic_mass_nr=0;
  /* Find the element */
  unsigned short int z=elementIdentify(isotope);
  if(z==0) return(ISOTOPE_UNKNOWN);
  /* Now find the mass number */
  cptr=strpbrk(isotope, "123456789"); // mass cannot start with zero
  if(cptr!=NULL) {
    mass_nr=atoi(cptr);
  }
  //printf("fixed isotope: %s-%d\n", elementSymbol(z), mass_nr);
 
  /* Check if element and mass matches any of the isotopes in our table */
  for(i=1; i<n; i++) {
    /* check the element */
    if(elementIdentify(tpc_isotope[i].name)!=z) continue;
    /* check the mass, if found */
    cptr=strchr(tpc_isotope[i].name, '-'); if(cptr==NULL) continue;
    ic_mass_nr=atoi(cptr+1);
    if(mass_nr>0 && ic_mass_nr!=mass_nr) continue;
    /* Match was found! */
    return(i);
  }
 
  return(ISOTOPE_UNKNOWN);
}

Referenced by abssWrite(), dcmImgIsotope(), tacGetIsotope(), tacRead4DM(), and tacReadSIF().

isotopeIdentifyHalflife()

int isotopeIdentifyHalflife ( double halflife )

extern

Identify the isotope based on halflife.

Returns

Isotope code, or 0 (enum ISOTOPE_UNKNOWN) if not identified.

See also

isotopeName, lambdaFromIsotope, decayCorrectionFactorFromIsotope

Author

Vesa Oikonen

Parameters

halflife

Halflife in minutes

Definition at line 121 of file isotope.c.

  {
  if(halflife<=0.01) return ISOTOPE_UNKNOWN;
  int i, n=0;
  while(strlen(tpc_isotope[n].name)>1) n++;
  /* Check, if halflife can be found in the table */
  for(i=1; i<n; i++) {
    if(fabs(halflife/tpc_isotope[i].hl-1.0)<0.05 ) return i;
  }
  return ISOTOPE_UNKNOWN;
}

Referenced by dcmImgIsotope().

isotopeName()

char * isotopeName ( int isotope_code )

extern

Get the string representation of an isotope specified with its isotope_code.

See also

isotopeBranching, isotopeHalflife, elementName, elementSymbol

Returns

pointer to string representation of the isotope, "unknown" if not identified.

Author

Vesa Oikonen

Parameters

isotope_code

isotope_code as enum or the index of isotope in isotope table.

Definition at line 101 of file isotope.c.

  {
  int n=0;
  
  while(strlen(tpc_isotope[n].name)>1) n++;
  if(isotope_code<1 || isotope_code>n-1)
    return tpc_isotope[ISOTOPE_UNKNOWN].name;
  else
    return(tpc_isotope[isotope_code].name);
}

Referenced by dcmImgIsotope(), imgContents(), imgFillOHeader(), imgReadDICOM(), sifWeight(), tacRead4DM(), tacReadSIF(), tacSetIsotope(), tacSetWeights(), and tacWByFreq().

lambdaFromHalflife()

double lambdaFromHalflife ( double halflife )

extern

Calculate lambda based on specified halflife.

Returns

Lambda (=ln(2)/halflife), or NaN if halflife is NaN or <=0.

See also

isotopeIdentifyHalflife, isotopeName, lambdaFromIsotope

Author

Vesa Oikonen

Parameters

halflife

Halflife of the isotope; if halflife is in minutes, then the unit of lambda will be 1/min, if seconds, then lambda will be in units 1/sec, etc.

Definition at line 47 of file decay.c.

  {
  if(halflife>0.0) return(M_LN2/halflife);  // M_LN2=log(2.0)
  else return nan("");
}

Referenced by tacDecayCorrection().

lambdaFromIsotope()

double lambdaFromIsotope ( int isotope )

extern

Calculate lambda for specified isotope.

Returns

Lambda (=ln(2)/halflife) in units 1/min, or NaN if isotope is not identified.

See also

decayCorrectionFactorFromLambda, isotopeName, isotopeIdentify, decayCorrectionFactorFromIsotope

Author

Vesa Oikonen

Parameters

isotope

isotope_code as enum or the index of isotope in isotope table.

Definition at line 63 of file decay.c.

  {
  double hl=isotopeHalflife(isotope); if(isnan(hl) || hl<=0.0) return nan("");
  return(M_LN2/hl);
}

Referenced by decayCorrectionFactorFromIsotope(), and tacWByFreq().

noiseSD4Frame()

double noiseSD4Frame ( double y, double t1, double dt, int isotope, double a )

extern

Calculate the standard deviation (SD) of noise for PET radioactivity concentration.

SD of noise can be used in simulations. Reference: Varga & Szabo. J Cereb Blood Flow Metab 2002;22(2):240-244.

See also

isotopeIdentify, drandGaussian, simC3s, simC3p, simRTCM

Returns

Returns the SD, or NaN in case of an error.

Parameters

y	Sample radioactivity concentration (decay corrected to zero time).
t1	Radioactivity measurement (frame) start time in minutes.
dt	Radioactivity measurement (frame) duration in minutes.
isotope	Isotope code as enum or index of isotope in isotope table; enter ISOTOPE_UNKNOWN if not to be considered.
a	Proportionality factor. Note that it should be in relation to the unit of y.

Definition at line 26 of file ranoise.c.

  {
  /* Frame start time must be >=0 and frame duration must be >0 */
  if(isnan(y) || !(t1>=0.0) || !(dt>0.0) || !(a>=0.0)) return(nan(""));
  /* If concentration is not positive, then its SD is zero */
  if(!(y>0.0)) return(0.0);
 
  /* Calculate decay factor (<=1) */
  double df;
  if(isotope==ISOTOPE_UNKNOWN) {
    df=1.0;
  } else {
    df=1.0/decayCorrectionFactorFromIsotope(isotope, t1, dt);
    if(!(df>0.0 && df<=1.0)) return(nan(""));
  }
 
  /* Calculate SD */
  return(sqrt((a*y)/(dt*df)));
}