Functions of JCAMPDXir

JCAMPDXir.JCAMPDXirModule

This JCAMP-DX (infrared) file format was developed for the exchange of infrared spectra between different laboratories. For general description of format refer to UIPAC.ORG (pdf file) In addition to the spectra themselves, the file also stores metadata containing information about the units of measurement and the conditions under which the spectra were acquired. A detailed specification of the format is provided via the link.

JCAMP file content example:

        ##TITLE=1 
        ##JCAMP-DX=4.24
        ##DATATYPE=INFRARED SPECTRUM
        ##DATE=2021/10/17
        ##TIME=11:30
        ##XUNITS=1/CM
        ##YUNITS=TRANSMITTANCE
        ##XFACTOR=1
        ##YFACTOR=0.00699183
        ##FIRSTX=0
        ##LASTX=15801.4671743
        ##FIRSTY=11746.3412893072
        ##MAXX=15801.4671743
        ##MINX=0
        ##MAXY=3.75371e+006
        ##MINY=4040.25
        ##NPOINTS=16384
        ##XYDATA=(X++(Y..Y))
        0 1680010 821286 2148133 1505245 1537124 1367661 1147725 1134981
        7.71603 1166853 1213186 1029828 1067595 1135904 1195128 1157134 1150556
        15.4321 1266743 1164401 1014224 1022338 999780 1138781 1208950 1161258
        .
        .
        ##END=
source
Core.TypeMethod
(::Type{SQZ})(s::AbstractString)

All types are callable, when calling on a string

source
Core.TypeMethod
(::Type{T})(s::AbstractString) where T<:Decoding

By default, all chunks and line decoding do nothing to the string line

source
JCAMPDXir.DecodingType
Types for decoding of both lines and chunks, line and chunk typisation is used 
to dispath during parsing
source
JCAMPDXir.addline!Method
addline!( jdx::JDXblock, 
                    data_buffer::DataBuffer{DataLineType,B,LD,ChunkDecoding},
                    current_line::String; # index of current data chunk
                    delimiter=DEFAULT_DELIMITER(DataLineType),
                    validate_data::Bool=true) where {DataLineType<:XYYline,B,LD,ChunkDecoding}

This function parses current_line string of file and fills the parsed data to the y-vector of jdx object number_of_y_point_per_chunk - the number of data point (excluding the x-coordinate) in the line chunk_index index of chunk delimiter data points delimiter used in split function

source
JCAMPDXir.addline!Method
addline!(jdx::JDXblock, 
                    data_buffer::DataBuffer{DataLineType},
                    current_line::String; # index of current data chunk
                    delimiter=r"[,;]",
                    validate_data::Bool=true) where DataLineType<:XYXYline

Adds line to XY...XY data

source
JCAMPDXir.convert!Method
convert!(x::AbstractArray,::sUnits{T},::sUnits{T}) where T

This functions can be used convert y and x units

supported x-units names: NANOMETERS,NM,CM-1,MKM,MICROMETERS,1/CM,WAVELENGTH (NM)),CM^-1,WAVELENGTH (UM))

supported y-units names: ABSORBANCE,A,T,A.U.,TRANSMITTANCE,R,KUBELKA-MUNK,ARBITRARY UNITS,REFLECTANCE

Example

julia> convert!([1,2,3],xUnits("MKM"),xUnits("1/cm"))) 
source
JCAMPDXir.fill_data_buffer!Method
fill_data_buffer!(data_buffer::Vector{Float64},current_line,delimiter,chunk_counter::Int=1)

Appends data to vector, initial chunk can be of zero size

source
JCAMPDXir.find_blocksMethod
find_blocks(file_name)

Counts blocks in file file_name, fills coordinates of blocks start and finish in file lines, returns the vector of JDXblock blocks or a singe block.

source
JCAMPDXir.parse_headers!Method
parse_headers!(jdx::JDXblock,headers::Vector{String})

internal function fills headers dictionary from a vector of strings

source
JCAMPDXir.read!Method
read!(jdx::JDXblock; delimiter=nothing,
                           only_headers::Bool=false,
                           fixed_columns_number::Bool=true,
                           fixed_line_decoding::Bool = false,
                           fixed_chunk_decoding::Bool = false,
                           validate_data::Bool = true)

fills precreated JDXblock object see JDXblock.

`delimiter` - data chunk delimiters
`only_headers`  - if true parses only block headers
`fixed_columns_number`  if true, all lines are supposed to have the same number of chunks
`fixed_line_decoding` if true, data line decoding (No_Line_Decoding, SQZ,PAC) is supposed  to be the same for all lines (parser obtains decoding from the first line of data)
`fixed_chunk_decoding` if true, all data chunks decoding (No_Chunk_Decoding,DIF,DUP) is supposed  to be the same for all lines (parser obtains decoding from the first line of data)
`validate_data` if false: we don't need no validation
source
JCAMPDXir.read_jdx_fileMethod
read_jdx_file(file_name::String;
            fixed_columns_number::Bool=false,
            delimiter = nothing,
            fixed_line_decoding::Bool = false,
            fixed_chunk_decoding::Bool = false,
            validate_data::Bool=true)

Reads JCAMP-DX file file_name

Input arguments:

`file_name` - full file name
(optional keyword args) 
`fixed_columns_number` - if it is known that each line in file has the same number of data chunks, this flag 
`delimiter`  - data chunks delimiter (default value is space)
`fixed_line_decoding` if `true` line decoding type ( PAC,SQZ or no line decoding) is taken only once from the first line of data, otherwise new type is obtained for each line
`fixed_chunk_decoding` if `true` chunk decoding type ( DIF, DUP, mixed DIFDUP or no chunk decoding) is taken from the first line of data, otherwise new type is obtained for each line    
`validate_data` turns on internal data checks

returns namedtuple (or a vector of namedtuples in the case of multiple blocks) with fields:

x - coordinate (wavelength, wavenumber or other)

y - data

headers - dictionary in "String => value" format with headers values 

data_validation, which is the named tuple with
source
JCAMPDXir.write_jdx_fileFunction
write_jdx_file(file_name,x::Vector{Float64},y::Vector{Float64},x_units::String="1/CM",
    y_units::String="TRANSMITTANCE"; kwargs...)

Saves infrared spectrum given as two vectors x and y to JCAMP-DX file file_name. Input vector should be of the same size. Currently the package suppots only (X++(Y..Y)) table data format. JCAMP-DX 4.24 demands 80 symbols per file line of Y-data and 88 total symbols per line. The y-vector is stored in eight columns, thus the total number of points should be a multiple of eight. All last mod(length(y),8) points of y dtaa will not be written to the file. It is preferable that all x-data is sorted in ascending order and spaced uniformly. If it is not the case, or if the units conversion is envolved, function will automatically interpolate and sort the data on uniformly spaced grid.

x_units - units of x data, must be one of NANOMETERS,NM,CM-1,MKM,MICROMETERS,1/CM,WAVELENGTH (NM)),CM^-1,WAVELENGTH (UM))

y_units - units of y data, must be one of ABSORBANCE,A,T,A.U.,TRANSMITTANCE,R,KUBELKA-MUNK,ARBITRARY UNITS,REFLECTANCE

Further any keword arguments can be provided, all of them will be written to the head of the file. All keyword arguments appear in the file in uppercase.

Most impostant keywords are

TITLE - the title of the file (it is always on top of the file)
XUNITS - x data units saved to file,  must be one of  NANOMETERS,NM,CM-1,MKM,MICROMETERS,1/CM,WAVELENGTH (NM)),CM^-1,WAVELENGTH (UM))
YUNITS - y data units saved to file, must be one of ABSORBANCE,A,T,A.U.,TRANSMITTANCE,R,KUBELKA-MUNK,ARBITRARY UNITS,REFLECTANCE

If x_units (function's fourth argument) are not equal to the key-word argument XUNITS than the function converts x-values before saving to file see xconvert!

If y_units (function's fifth argument) are not equal to the key-word argument XUNITS than the function converts y-values before saving to file see yconvert!

Example

julia> using JCAMPDXir
julia> filename = joinpath(@__DIR__,"test.jdx")
julia> write_jdx_file(filename,[1,2,3,4,5,6,7,8],rand(8),"MKM","T",title = "new file",XUNIT="1/CM",YUNITS="KUBELKA-MUNK") 
source
JCAMPDXir.xconvert!Method
xconvert!(x::AbstractArray,input_units::String,output_units::String)

Converts the values of `x` from `input_units` to `output_units`.
supported x-units names: NANOMETERS,NM,CM-1,MKM,MICROMETERS,1/CM,WAVELENGTH (NM)),CM^-1,WAVELENGTH (UM))

Example

julia> xconvert!([1,2,3],"MKM",xUnits"1/cm")) 
source
JCAMPDXir.yconvert!Method
yconvert!(y::AbstractArray,input_units::String,output_units::String)

Converts the values of y from input_units to output_units. supported x-units names: NANOMETERS,NM,CM-1,MKM,MICROMETERS,1/CM,WAVELENGTH (NM)),CM^-1,WAVELENGTH (UM)) All units can be written both in lower- and in uppercase, T,R and A stay for a shorthand for TRANSMITTANCE,REFLECTANCE and ABSORBANCE

Example

julia> yconvert!([1,2,3],"R","KUBELKA-MUNK")) 
source