\documentclass{article}
\usepackage[usenames,dvipsnames]{xcolor}
\usepackage{fullpage}
\usepackage[utf8]{inputenc}
\usepackage[russian]{babel}
\usepackage{array}
\usepackage{booktabs}
\usepackage[section]{placeins}
\usepackage[flushleft]{threeparttable}
\usepackage{tcolorbox}
\usepackage{multirow}
\usepackage{hyperref}
\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,      
    urlcolor=cyan,
    pdftitle={Overleaf Example},
    pdfpagemode=FullScreen,
    linktocpage=true,
    }
\urlstyle{same}

\usepackage{tocloft}
% \renewcommand{\cftpartleader}{\cftdotfill{\cftdotsep}}
% \renewcommand{\cftchapleader}{\cftdotfill{\cftdotsep}} % for chapters
\renewcommand{\cftsecleader}{\cftdotfill{\cftdotsep}}

\usepackage{fancyvrb}
\usepackage{fvextra}
\usepackage{stackengine}
\usepackage{scalerel}
\newcommand\dangersign[1][2ex]{%
  \renewcommand\stacktype{L}%
  \scaleto{\stackon[1.3pt]{\color{black}$\triangle$}{\tiny !}}{#1}%
}

\newcommand{\art}{\textit{СРГ/АРТ-XC}}
\newcommand{\artf}{\textit{АРТ-XC им. М.~Н.~Павлинского}}
\newcommand{\srgart}{\textit{СРГ/АРТ-XC}}
\newcommand{\pipe}{\textsc{artpipeline}}
\newcommand{\prods}{\textsc{artproducts}}
\newcommand{\artim}{\textsc{artimage}}
\newcommand{\artev}{\textsc{artevlist}}
\newcommand{\artarf}{\textsc{artmkarf}}
\newcommand{\artax}{\textsc{artskyaxis}}
\newcommand{\artcoord}{\textsc{artskycoord}}
\newcommand{\artsp}{\textsc{artxspec}}
\newcommand{\artlc}{\textsc{artlcurve}}

% \hypertarget{thesentence}{this sentence}
% \hyperlink{thesentence}{any sentence}

\renewcommand\arraystretch{1.2}

\title{Краткое руководство по обработке данных телескопа \srgart\ им. М.~Н.~Павлинского}
\author{
    Кузнецова Екатерина (ИКИ РАН, eakuznetsova@cosmos.ru) \\
    Штыковский Андрей (ИКИ РАН, sht.job@gmail.com) \\
}
\date{Версия 2.1 beta от \today}

\begin{document}

\maketitle
\tableofcontents
\newpage
\section{Требования к рабочему окружению}
\label{sec:env}

Для работы конвейера обработки требуются установленные:

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
  \begin{itemize}
    \item \textbf{HEASOFT версии 6.28} и старше (см. \href{https://heasarc.gsfc.nasa.gov/docs/software/heasoft/}{здесь})
    \item \textbf{Python версии 3.8} и старше (см. \href{https://www.python.org/downloads/}{здесь})
  \end{itemize}
\end{tcolorbox}

\section{Подготовка рабочего окружения на серверах СРГ}
\label{sec:prep}

\noindent
Файлы конвейера обработки и калибровочные файлы лежат на серверах СРГ в директории: \\
\verb*|/srg/work/srg/artxc|.

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\noindent
Для того чтобы проинициализировать рабочее окружение необходимо подгрузить переменные окружения при помощи файла artinit.csh, который который лежит в этой же директории. Пример вызова команды: 

\begin{verbatim} 
source /srg/work/srg/artxc/artinit.csh
\end{verbatim} 

\noindent
Чтобы каждый раз не писать длинную команду можно создать \verb*|alias|, прописав в файле $\sim$/.tcshrc:

\begin{verbatim} 
alias artinit "source /srg/work/srg/artxc/artinit.csh"
\end{verbatim} 
и выполнив \verb*|source|~\verb*|~/.tcshrc|. После этого в терминале можно инициализировать окружение командой \verb*|artinit|.
\end{tcolorbox}

% На серверах СРГ установлено несколько разных версий программного обеспечения \textsc{heasoft}, которые нужно по-разному инициализировать для каждого сервера. В будущем планируется обновить программное обеспечение на серверах и привести к единой системе инициализации необходимого окружения. На 18-м сервере программное обеспечение \textsc{HEASOFT v.6.29} и все необходимые библиотеки можно инициализировать, прописав в файле \verb*|~\.tcshrc| следующее:
% \begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
%     \begin{Verbatim}[breaklines=true,  breakanywhere=true]
%     setenv LD_LIBRARY_PATH ""
%     setenv LD_LIBRARY_PATH /opt/soft/heasoft-6.24/x86_64-pc-linux-gnu-libc2.17/lib/:/opt/soft/psoft/libpng/lib/:$LD_LIBRARY_PATH
%     setenv PATH /opt/soft/bin/:$PATH
    
%     setenv CALDB /srg/work/srg/artxc/caldb
%     alias cdbinit "source $CALDB/software/tools/caldbinit.csh"

%     setenv HEADAS /opt/soft/psoft/heasoft-6.29/x86_64-pc-linux-gnu-libc2.17
%     alias heainit "source $HEADAS/headas-init.csh"

%     alias artinit "source /srg/work/srg/artxc/artinit.csh"
%     \end{Verbatim}
% \end{tcolorbox}

На серверах СРГ установлено несколько разных версий программного обеспечения \textsc{heasoft}, которые нужно по-разному инициализировать для каждого сервера. В будущем планируется обновить программное обеспечение на серверах и привести к единой системе инициализации необходимого окружения. На 10-14 серверах программное обеспечение \textsc{HEASOFT v.6.29} и все необходимые библиотеки можно инициализировать, прописав в файле \verb*|~\.tcshrc| следующее:
\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
    \begin{Verbatim}[breaklines=true,  breakanywhere=true]
alias artinit "source /srg/work/srg/artxc/artinit.csh"
setenv LD_LIBRARY_PATH ""
setenv LD_LIBRARY_PATH /opt/soft/psoft/gcc-9.3.0/lib64/:/opt/soft/psoft/lib/:$LD_LIBRARY_PATH

setenv PATH /opt/soft/psoft/bin:$PATH
setenv PYTHONPATH /opt/soft/psoft/bin
source /opt/soft/psoft/python_venv/bin/activate.csh

setenv HEADAS /opt/soft/psoft/heasoft-6.29/x86_64-pc-linux-gnu-libc2.17
alias heainit "source $HEADAS/headas-init.csh"

setenv CALDB /srg/work/srg/artxc/caldb
alias cdbinit "source $CALDB/software/tools/caldbinit.csh"
    \end{Verbatim}
\end{tcolorbox}


\section{Уровни данных}
\label{sec:data}

В процессе обработки данных космического телескопа \art\ используются и производятся следующие уровни данных:
  \begin{itemize}
    \item L0 - исходные (сырые) данные
    \item L1 - калиброванные данные
    \item L2 - калиброванные и очищенные данные
    \item L3 - продукты высокого уровня
  \end{itemize}

Данные на всех уровнях представлены в формате FITS. 

Исходные данные уровня L0 представляют собой списки некалиброванных и неочищенных событий и кватернионы ориентации телескопа \art, измеренные Гироскопическим Измерителем Вектора Угловых Скоростей (ГИВУС) (см. таблицу~\ref{tab:l0}). 

На данный момент архив данных находится в разработке, поэтому необходимо заранее уточнить реальную директорию, в которой лежат данные необходимого наблюдения. Некоторые наблюдения лежат в директории \verb*|/srg/a1/work/oper/data/archive/observations/<OBSID>/L0/| или, если нет доступка к \verb*|/srg/a1|, \verb*|/srg/work/oper/data/archive/observations/<OBSID>/L0/|, где \verb*|<OBSID>| --- индивидуальный номер наблюдения.

\begin{table}[!h]
  \centering
  \caption{Файлы директории L0, которая содержит исходные данные.}

  \begin{tabular}{| m{5cm} | m{10.7cm} |}
    \hline
    \textbf{Название / Пример} & \textbf{Описание}  \\
    \hline
    \verb*|<STEM>T[1-7]_uf.fits|/ \verb*|art119100400010T1_uf.fits| & Списки некалиброванных и неочищенных событий. 
    
    \verb*|<STEM>=art<OBSID>[0-1]| --- префикс используемых файлов. 
    
    Индекс \verb*|0| соответствует данным, набранным во время наблюдения, \verb*|1| --- данным, полученным во время перенаведения на объект (pre-slew, т.е. от момента окончания предыдущего наблюдения до момента начала текущего наблюдения).
    
    Индекс \verb*|T[1-7]| соответствует номеру модуля телескопа АРТ-XC от 1 до 7. \\
    \hline
    \verb*|<STEM>_gyro.fits|/ \verb*|art119100400010_gyro.fits| & Файл с кватернионами ориентации телескопа. \\
    \hline
  \end{tabular}
\label{tab:l0}
\end{table}
    
   

% \section{Архив данных наблюдений на серверах СРГ}
% \label{sec:arch}

% Архив данных наблюдений подготовлен согласно программе наблюдений СРГ. Каждое наблюдение лежит в отдельной директории и содержит файлы наведений и интервалов хорошего времени, а также данные сырые сырые списки событий уровня L0. Подготовленные к последующей обработке файлы наблюдений находятся в директории \textbf{(необходимо уточнить директорию)}:

% \begin{verbatim} 
% /srg/a1/work/oper/data/archive/observations/$obsid/L0
% \end{verbatim} 

% \noindent
% Подневный архив наблюдений, обновляемый на ежедневной основе, содержит непрерывные данные наблюдений, разделенные по дням наблюдений (ARTDAYS). Архив содержит файлы наведений и списки событий уровней L0, L1 и L2. Подневный архив наблюдений лежит в директории:
% \begin{verbatim} 
% /srg/a1/work/oper/data/artdays
% \end{verbatim} 

\section{Этапы обработки данных}
\label{sec:steps}

Обработка исходных данных уровня L0 проводится в несколько этапов:
\begin{enumerate}
\item калибровка сырых данных уровня L0, в результате чего генерируются данные уровня L1
\item очистка калиброванных данных уровня L1, что производит данные уровня L2
\item генерация научных продуктов высокого уровня L3
\end{enumerate}
Первый и второй этапы проводятся с помощью процедуры \pipe\ (см. секцию~\ref{sec:pipe}), за третий этап отвечает процедура \prods\ (см. секцию~\ref{sec:prods}).


Рисунок \ref{fig:proc} содержит схему уровней данных с указанием процедур, с помощью которого производится каждый следующий уровень. Стоить отметить, что данные уровня L1 в схеме не отображены, т.к. являются промежуточной стадией процедуры \pipe. 

\begin{figure*}[h!]
  \centerline{\includegraphics[width=0.8\textwidth]{data_levels.png}}
    \caption{Этапы обработки и уровни данных космического телескопа \artf.}
\label{fig:proc}
\end{figure*} 


\section{\pipe\ --- получение калиброванных и очищенных данных уровня L2}
\label{sec:pipe}

Первый этап обработки данных --- калибровка и очистка (уровень данных L2). 
% \textbf{На этапе очистки к калиброванному списку событий применяются фильтры .... }
Для выполнения первого этапа обработки данных используется процедура \pipe, параметры вызова которой приведены в Таблице~\ref{tab:pipepar}. При возникновении ошибок выполнения данной процедуры смотрите секцию~\ref{sec:err}. Промежуточные файлы калиброванных, но не очищенных, списков событий (уровень L1) не сохраняются после успешного завершения процедуры. 

Процедура \pipe\ поддерживает использование пользовательских временных интервалов, которые можно задать с помощью ключа \verb*|--usergti|.

После успешного выполнения этой команды в директории \verb*|./processed/119100400010| будет создана поддиректория L2, которая будет содержать калиброванные очищенные данные. Содержимое директории L2, созданной после успешного завершения процедуры \pipe, описано в таблице~\ref{tab:l2}. 

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример вызова \pipe} (на примере наблюдения OBSID=11910040001):

\begin{verbatim}
artpipeline \
    stem=art119100400010 \
    srcdir=/data/artxc/obsid/119100400010/L0 \
    dstdir=./processed/119100400010
    tmpdir=/temp
\end{verbatim}

\dangersign[4ex] Указанную в \verb*|srcdir| директорию \verb*|/data/artxc/obsid| необходимо заменить на реальную директорию, в которой лежат данные которые необходимо обработать.
\end{tcolorbox}


\begin{table}[!h]
  \centering
  \caption{ Параметры процедуры \pipe. Переменная <PATH> --- обозначает путь к соответствующим файлам.}

  \begin{tabular}{| m{5em} | m{5cm}| m{8.2cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|stem|  & \verb*|art<OBSID>[0-1]| & Префикс для имен входных и выходных файлов. \\ 
    \hline
    \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L0| & Входная директория, указывающая путь к файлам данных уровня L0. \\ 
    \hline
    \verb*|dstdir| & \verb*|<PATH>/<OBSID>| & Выходная директория, в которой будут созданы поддиректории L1 и L2. Создаётся новая или используется уже существующая. \\ 
    \hline
    \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов.  Создаётся новая или используется уже существующая. В директории, указанной в параметре \verb*|tmpdir| создаётся новая директория для размещения временных файлов, генерируемых в процессе работы процедуры. При успешном завершении процедуры эта директория автоматически удаляется.  Если Вы работаете на серверах сети СРГ, то эта директория очищается при перезагрузке сервера. \\ 
    \hline
    \verb*|--usergti| & \verb*|<PATH>/<GTI_NAME>.fits| & Пользовательский файл с необходимыми временными интервалами (опциональный параметр).\\
    \hline
%    \verb*|--seed| &  & Параметр для генератора случайных чисел. Выбирается автоматически, но может быть задан вручную, например, для полного повторения результатов запуска \pipe. \\
%    \hline
  \end{tabular}
\label{tab:pipepar}
\end{table}


%В данной процедуре заложен генератор случайных чисел, при помощи которого разыгрываются значения в колонках списка событий, содержащих информацию об энергии пришедшего фотона (\verb*|[ENERGY]|, \verb*|[ENERGY_BOT]|, \verb*|[ENERGY_TOP]|) и о его небесных координатах (\verb*|[RA]|, \verb*|[DEC]|). Генератор случайных чисел определяется числом \verb*|[SEED]|, которое при каждом запуске \pipe\ обновляется и записывается в \verb*|HEADER| полученных списков событий уровня L2. Автоматически при запуске \pipe\ для энергии пришедшего фотона и его небесных координат генерируются разные числа. Однако существует возможность вручную задавать число \verb*|[SEED]| с помощью параметра \verb*|--seed| процедуры \pipe. В таком случае генератор случайных чисел использует одинаковое число \verb*|[SEED]| для розыгрыша энергий и небесных координат. При необходимости полностью повторить результаты того или иного запуска \pipe, необходимо при каждом запуске \pipe\ указывать одинаковый параметр \verb*|--seed|.

\begin{table}[!h]

  \centering
  \caption{Файлы директории L2, генерируемые процедурой \pipe.}

  \begin{tabular}{| m{5cm} | m{10.7cm} |}
    \hline
    \textbf{Название / Пример} & \textbf{Описание}  \\
    \hline
    \verb*|<STEM>_att.fits|/ \verb*|art119100400010_att.fits| & Файл наведения телескопа.  \\
    \hline
    \verb*|<STEM>_ori.fits|/ \verb*|art119100400010_ori.fits| & Файл ориентации телескопа. \\
    \hline
    \verb*|<STEM>T[1-7]_cl.fits|/ \verb*|art119100400010T1_cl.evt| & Файлы с калиброванными и очищенными списками событий для каждого телескопа. Индекс T[1-7] соответствует номеру модуля телескопа \art\ от 1 до 7. \\
    \hline
  \end{tabular}
\label{tab:l2}
\end{table}
 

\FloatBarrier

\section{\prods\ --- получение продуктов высокого уровня L3}
\label{sec:prods}

Для получения продуктов высокого уровня необходимо выполнить 4 шага: 
\begin{enumerate}
\item задать область неба (секция~\ref{sec:wcs});
\item произвести привязку данных к заданной области неба с помощью \prods, в результате чего производятся списки событий и изображения неба (секция~\ref{sec:artprod1}); 
\item определить регионы для извлечения сигнала источника и оценки фонового излучения (секция~\ref{sec:reg});
\item получить кривые блеска и спектры с помощью \prods\ (секция~\ref{sec:artprod2}).
\end{enumerate}
\noindent
Каждый этап подробно описан ниже.

\subsection{Определение области неба}
\label{sec:wcs}

Для определения разметки области неба, на которую будут проецироваться фотоны с помощью процедуры \prods, необходимо создать текстовый WCS-файл с заданными параметрами координатной сетки. Описание параметров, которые должны быть записаны в WCS-файле, приведены в таблице~\ref{tab:wcs}. Предлагается задавать наименование WCS-файла в следующем формате: \verb*|<STEM>_skytile.wcs|. Процедура \prods\ поддерживает только систему координат FK5. 

\begin{table}[!h]

  \centering
  \caption{Параметры WCS-файла (в разработке). На данный момент изменения фиксированных параметров невозможны.}

  \begin{tabular}{| m{5em} | m{4cm}| m{9.4cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|nx|      & 1024 пикс. & Количество пикселей по оси X. \\ 
    \verb*|ny|      & 1024 пикс. & Количество пикселей по оси Y. \\ 
                        &            & Процедура \prods\ умножает эти параметры на 2 и прибавляет 1.\\ 
    \hline
    \verb*|crpix1|  & 512 пикс.  & Координата опорной точки по оси X. \\ 
    \verb*|crpix2|  & 512 пикс.  & Координата опорной точки по оси Y. \\ 
                    &            & Процедура \prods\ умножает эти параметры на 2.\\ 
    \hline
    \verb*|crval1|  & RA, $^{\circ}$ & Прямое восхождение (RA) опорной точки. \\ 
    \verb*|crval2|  & Dec, $^{\circ}$ & Наклонение (Dec) опорной точки. \\ 
    \hline
    \verb*|cdelt1|  & $-0.0025318223732333^{\circ}$ & Шаг по прямому восхождению вдоль оси X. Фиксированный параметр.\\ 
    \verb*|cdelt2|  & $0.0025318223732333^{\circ}$ & Шаг по наклонению вдоль оси Y.  Фиксированный параметр. \\ 
    \hline
    \verb*|crota2|  & $0^{\circ}$ & Угол наклона координатной сетки. Фиксированный параметр. \\ 
    \hline
\end{tabular}
\label{tab:wcs}
\end{table}

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример содержания WCS файла} для источника GRO~J1008--571 с координатами RA = 152.4457, Dec = -58.293 (OBSID=11910040001):
\begin{verbatim}
{
    "nx"    :  1024,
    "ny"    :  1024,
    "crpix1":  512,
    "crpix2":  512,
    "crval1":  152.4457,
    "crval2": -58.293,
    "cdelt1": -0.0025318223732333,
    "cdelt2":  0.0025318223732333,
    "crota2":  0
}
\end{verbatim}
\end{tcolorbox}



\subsection{Привязка списков событий к координатам и получение изображения}
\label{sec:artprod1}

На данном этапе проводится привязка калиброванных и очищенных списков событий к координатной разметке, заданной WCS-файлом (см. секцию ~\ref{sec:wcs}), что позволяет получить изображение неба. Для этого необходимо запустить процедуру \prods\ с ключами \verb*|--prepare-skytile| и \\ \verb*|--wcs=<PATH>/<STEM>_skytile.wcs|, где \verb*|<PATH>| --- путь к директории, в которой находится нужный WCS-файл. Параметры процедуры \prods\ описаны в таблице~\ref{tab:prod1}. Список возможных ошибок выполнения данной процедуры и их решений указан в секцию~\ref{sec:err}.

Стоить отметить, что процедура \prods\ не поддерживает использование пользовательских временных интервалов, заданных с помощью ключа \verb*|--usergti|. При необходимости использовать пользовательские временные интервалы рекомендуется запустить сначала \pipe\ (см. секцию~\ref{sec:pipe}) с соответствующим ключом \verb*|--usergti|, а затем на полученных списках событий запускать \prods. 

Процедура \prods\ может производить изображения в определённом энергетическом диапазоне от $E_{min}$ до $E_{max}$ с помощью ключей \verb*|--elow| и \verb*|--ehigh|, которые соответствуют нижней и верхней границам заданного диапазона соответственно (см. таблицу~\ref{tab:prod1}). 

При успешном выполнении команды \prods\ будут созданы списки событий с заданной системой координат (WCS) в поддиректории \verb*|<PATH>/<OBSID>/L3/events| и построены изображения указанной области неба по каждому модулю телескопа \art\ и совместное по всем модулям в поддиректории  \verb*|<PATH>/<OBSID>/L3/img| (см. таблицу~\ref{tab:ev_img}). Поддиректории будут созданы в выходной директории \verb*|dstdir=<PATH>/<OBSID>/L3|, указанной при запуске \prods. 

% \noindent
% Для определения регионов для извлечения данных необходимо выполнить команду \textsc{artproducts} с ключами prepare-skytile и wcs (с указанием WCS для построения изображения).

\begin{table}[!h]
  \centering
  \caption{Параметры и ключи процедуры \prods, необходимые для привязки списка событий к заданной области неба и построению изображения. Переменная <PATH> --- обозначает путь к соответствующим файлам.}

  \begin{tabular}{| m{5em} | m{5cm}| m{8.2cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|stem|  & \verb*|art<OBSID>[0-1]| & Префикс для имен входных и выходных файлов. \\
    \hline
    \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L2| & Входная директория, указывающая путь к файлам данных уровня L2. \\ 
    \hline
    \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3| & Выходная директория, в которой будут созданы поддиректории \verb*|events| и \verb*|img|. Создаётся новая или используется уже существующая. \\ 
    \hline
    \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. Создаётся новая или используется уже существующая. В директории, указанной в параметре \verb*|tmpdir| создаётся новая директория для размещения временных файлов, генерируемых в процессе работы процедуры. При успешном завершении процедуры эта директория автоматически удаляется. Если Вы работаете на серверах сети СРГ, то эта директория очищается при перезагрузке сервера. \\ 
    \hline
    \verb*|--prepare-| \verb*|skytile| &  & Ключ, запускающий процедуру \prods\ в режиме, который проводит привязку данных уровня L2 к области неба, заданной WCS-файлом.  \\ 
    \hline
    \verb*|--wcs| & \verb*|<PATH>/<STEM>_skytile.wcs| & WCS-файл, содержащий информацию о системе координат и области неба, на которую будут проецироваться списки событий уровня L2.\\
    \hline
    \multicolumn{3}{|c|}{\textbf{Опциональные параметры}}\\
    \hline  
    \verb*|--elow| & $E_{min}$, кэВ & Нижняя граница энергетического диапазона. По умолчанию $E_{min}=4$~кэВ. \\ 
    \hline
    \verb*|--ehigh| & $E_{max}$, кэВ & Верхняя граница энергетического диапазона. По умолчанию $E_{max}=12$~кэВ. \\ 
%    \hline
%    \verb*|--usergti| & \verb*|<PATH>/<GTI_NAME>.fits| & Пользовательский файл с необходимыми временными интервалами (опциональный параметр).\\
    \hline
  \end{tabular}
\label{tab:prod1}
\end{table}

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример вызова \prods} (на примере наблюдения OBSID=11910040001) для подготовки определения регионов:

\begin{verbatim}
artproducts \
    stem=art119100400010 \
    srcdir=./processed/119100400010/L2 \
    dstdir=./processed/119100400010/L3 \
    tmpdir=/temp \
    --prepare-skytile \
    --wcs=./art119100400010_skytile.wcs
\end{verbatim}
%    --wcs=/data/artxc/obsid/119100400010/meta/art119100400010_skytile.wcs

\dangersign[4ex] Повторный запуск процедуры \prods\ приводит к перезаписи файлов в директории \verb*|L3\img| и не изменяет файлы директории \verb*|L3\events|. Полная перезапись файлов на данный момент не реализована, поэтому перед повторным запуском процедуры рекомендуется удалить все ранее сгенерированные ей файлы или изменить выходную директорию.
\end{tcolorbox}



\begin{table}[!h]
  \centering
\caption{Файлы, генерируемые после вызова процедуры \prods, описанной в пункте~\ref{sec:artprod1}. Для каждого случая индекс T[1-7] соответствует номеру модуля телескопа \art\ от 1 до 7.}

  \begin{tabular}{| m{5cm} | m{10.7cm} |}
    \hline
    \textbf{Название / Пример} & \textbf{Описание} \\
    \hline
    \multicolumn{2}{|c|}{\textbf{Директория events}} \\
    \hline
    \verb*|<STEM>T[1-7]_cl.evt|/ \verb*|art119100400010T1_cl.evt| & файлы с калиброванными и очищенными списками событий, полученные каждым модулем телескопа \art, с привязкой к координатной сетке, заданной WCS-файлом на предыдущем шаге.  \\
    \hline
    \multicolumn{2}{|c|}{\textbf{Директория img}} \\
    \hline
    <STEM>T[1-7].img/ \verb*|art119100400010T1.img| & индивидуальные для каждого модуля телескопа \art\ изображения области неба, заданной WCS-файлом. \\
    <STEM>T[1-7]\_all.img/ \verb*|art119100400010T1_all.img| & изображение заданной области неба, просуммированное по всем модулям телескопа \art.\\
    \hline
  \end{tabular}
\label{tab:ev_img}
\end{table}

\subsection{Определение регионов для извлечения информации об источнике}
\label{sec:reg}

Перед тем, как получить кривые блеска и спектры источника, необходимо определить регионы, из которых будет собираться сигнал источника и излучение фона. Для этого необходимо на суммарном изображении неба (например, \verb*|art119100400010T1_all.img|, см. таблицу~\ref{tab:ev_img}), полученном при запуске \prods, определить два региона и сохранить их в формате программы \textsc{ds9}.

На данный момент поддерживаются только круговые регионы, при этом для извлечения сигнала источника рекомендуется задавать единственный регион с радиусом $R=136.5''$, что соответствует трём пикселям детектора, каждый из которых имеет размер $45.5''$. Для оценки фонового излучения разрешается задавать несколько регионов без регионов исключения. 

% Суммарное изображение, полученное при запуске \prods, необходимо открыть с  DS9 и определить регионы для извлечения фотонов источника и фона \textbf{(на данный момент поддерживаются только круговые регионы)}.

% На данный момент процедура \prod\ поддерживает только круговые регионы. Для точечных источников рекомендуемый размер региона составляет $R=135''$.

\subsection{Получение спектров и кривых блеска}
\label{sec:artprod2}

\noindent
Предыдущие шаги были подготовительными этапами для получения научных продуктов высокого уровня L3, а именно: кривых блеска и спектров. Списки событий были привязаны к координатной сетке WCS, регионы источника и фона были определены по полученным изображениям. Теперь нужно произвести вызов процедуры \prods\ с указанием регионов для извлечения фотонов источника и фона, положения источника, файла ориентации телескопа и параметров кривой блеска. В качестве входной директории указывается директория \verb*|<PATH>/<OBSID>/L3/events|, содержащая списки событий с привязкой к координатам, полученные на более раннем этапе (см. секцию~\ref{sec:artprod1}). Полный список параметров процедуры \prods\ указан в таблице~\ref{tab:prod2}. 

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример вызова \prods} (на примере наблюдения OBSID=11910040001) с использованием подготовленного WCS-файла:

\begin{verbatim}
artproducts \
    stem=art119100400010 \
    srcdir=./processed/119100400010/L3/events \
    dstdir=./processed/119100400010/L3 \
    tmpdir=/temp \
    --orient=./processed/L2/art119100400010_ori.fits \
    --srcreg=./processed/L3/reg/art119100400010_src.reg \
    --bkgreg=./processed/L3/reg/art119100400010_bkg.reg \
    --srcra=152.4457 \
    --srcdec=-58.293 \
    --elow=4 \
    --ehigh=12 \
    --binsize=1
\end{verbatim}   

\dangersign[4ex] Обратите внимание, что в \verb*|srcdir| указывается директория событий, полученных после вызова процедуры \prods\ в пункте~\ref{sec:artprod1}.

\dangersign[4ex] \dangersign[4ex] Повторный запуск процедуры \prods\ приводит к ошибке выполнения данной программы. Перезапись файлов при повторном запуске процедуры на данный момент не реализована, поэтому рекомендуется удалить ранее сгенерированные файлы или изменить выходную директорию.
\end{tcolorbox}

\begin{table}[!h]
  \centering
  \caption{Параметры и ключи процедуры \prods, необходимые для получения кривых блеска и спектров. Переменная <PATH> --- обозначает путь к соответствующим файлам. }

  \begin{tabular}{| m{5em} | m{5cm}| m{8.2cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|stem|  & \verb*|art<OBSID>[0-1]| & Префикс для имен входных и выходных файлов. \\
    \hline
    \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L3/events| & Входная директория, указывающая путь к спискам событий уровня L3. \\ 
    \hline
    \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3| & Выходная директория, в которой будут созданы поддиректории \verb*|pha| и \verb*|lc|. Создаётся новая или используется уже существующая. \\ 
    \hline
    \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. Создаётся новая или используется уже существующая. В директории, указанной в параметре \verb*|tmpdir| создаётся новая директория для размещения временных файлов, генерируемых в процессе работы процедуры. При успешном завершении процедуры эта директория автоматически удаляется.  Если Вы работаете на серверах сети СРГ, то эта директория очищается при перезагрузке сервера. \\ 
    \hline
    \verb*|--orient| & \verb*|<PATH>/<OBSID>/L2/| \verb*|<STEM>_ori.fits| & Файл ориентации телескопа \art. \\ 
    \hline
    \verb*|--srcreg| & \verb*|<PATH>/<SRC_NAME>.reg| & Регион, из которого извлекается излучение источника.  \\ 
    \hline
    \verb*|--bkgreg| & \verb*|<PATH>/<BKG_NAME>.reg| & Регион, внутри которого оценивается уровень фонового излучения. \\ 
    \hline
    \verb*|--srcra| & \verb*|RA|, $^{\circ}$ & Прямое восхождение (RA) источника. \\ 
    \hline
    \verb*|--srcdec| & \verb*|Dec|, $^{\circ}$ & Наклонение (Dec) источника.\\
    \hline
    \multicolumn{3}{|c|}{\textbf{Параметры для получения кривых блеска}}\\
    \hline
    \verb*|--elow| & $E_{min}$, кэВ & Нижняя граница энергетического диапазона. По умолчанию $E_{min}=4$~кэВ. \\ 
    \hline
    \verb*|--ehigh| & $E_{max}$, кэВ & Верхняя граница энергетического диапазона. По умолчанию $E_{max}=12$~кэВ. \\ 
    \hline
    \verb*|--binsize| & $T_{bin}$, с & Размер бина кривой блеска. По умолчанию $T_{bin}=1$~с. \\ 
    \hline
    % \multicolumn{3}{|c|}{\textbf{Опциональные параметры}}\\
    % \hline
    % \verb*|--usergti| & \verb*|<PATH>/<GTI_NAME>.fits| & Пользовательский файл с необходимыми временными интервалами.\\
    % \hline
  \end{tabular}
\label{tab:prod2}
\end{table}

\begin{table}[!ht]
  \centering
\caption{Файлы, генерируемые после вызова процедуры \prods, описанной в пункте~\ref{sec:artprod2}. Для каждого случая индекс T[1-7] соответствует номеру модуля телескопа \art\ от 1 до 7.}

  \begin{tabular}{| m{7cm} | m{8.7cm} |}
    \hline
    \textbf{Название / Пример} & \textbf{Описание} \\
    \hline
    \multicolumn{2}{|c|}{\textbf{Директория lc}} \\
    \hline
    \verb*|<STEM>T[1-7]_src.lc|/ \verb*|art119100400010T1_src.lc| & Кривая блеска источника в энергетическом диапазоне $E_{min}-E_{max}$ с временным шагом $T_{bin}$. \\
    \hline
    \verb*|<STEM>T[1-7]_bkg.lc|/ \verb*|art119100400010T1_bkg.lc| & Кривая блеска фонового излучения в энергетическом диапазоне $E_{min}-E_{max}$ с временным шагом $T_{bin}$. \\
    \hline
    \multicolumn{2}{|c|}{\textbf{Директория pha}} \\
    \hline
    \verb*|<STEM>T[1-7]_src.pha|/ \verb*|art119100400010T1_src.pha| & Спектр источника. \\
    \hline
    \verb*|<STEM>T[1-7]_bkg.pha|/ \verb*|art119100400010T1_bkg.pha| & Спектр фона.\\
    \hline
    \verb*|<STEM>T[1-7].arf|/ \verb*|art119100400010T1.arf| & ARF (Ancillary Response File) --- файл, описывающий зависимость эффективной площади детектора от энергии фотона. \\
    \hline
    \verb*|artxc_rmf_T[1-7]_20191030_v003.rmf|/ \verb*|artxc_rmf_T1_20191030_v003.rmf| & RMF (Responce Matrix File) --- файл, содержащий матрицу отклика детектора.\\
    \hline
  \end{tabular}
\label{tab:lc_pha}
\end{table}


При успешном завершении процедуры \prods\ в выходной директории \verb*|<PATH>/<OBSID>/L3| будут созданы поддиректории \verb*|lc| и \verb*|pha|, содержащие файлы кривых блеска и спектров соответственно. Список генерируемых файлов приведён в таблице~\ref{tab:lc_pha}. При возникновении ошибок выполнения данной процедуры смотрите секцию~\ref{sec:err}.

% \begin{table}[h!]

%   \centering
%   \caption{ Параметры процедуры \textsc{artproducts}.}

%   \begin{tabular}{c|l|l}
%     \hline\hline

%     Параметр & Значение &  Комментарий \\
%     \hline
%     stem              & префикс для имен выходных файлов & \\ 
%     srcdir            & входная директория               & путь к файлам L2  \\ 
%     dstdir            & выходная директория              & будут созданы поддиректории: \\
%                       &                                  & events, img, lc, pha \\ 
%     tmpdir            & директория для временных файлов  & \\ 
%     --usergti         & пользовательский gti (fits)      & \\
%     --orient          & файл наведений обсерватории      & \\
%     --srcreg          & ds9 регион источника             & *  \\
%     --bkgreg          & ds9 регион фона                  & ** \\
%     --elow            & нижняя граница энерг. диапазона  & кэВ, по умолчанию -- 4  \\
%     --ehigh           & верхняя граница энерг. диапазона & кэВ, по умолчанию -- 12 \\
%     --binsize         & размер бина кривой блеска        & сек, по умолчанию -- 1  \\
%     --wcs             & WCS для построения изображения   & \\
%     --prepare-skytile & ключ для подготовки данных       & \\
%     --srcra           & прямое восхождение источника     & град \\
%     --srcdec          & склонение источника              & град \\
%     \hline
%   \end{tabular}

%     \begin{tablenotes}
%       \small
%       \item *) Для области источника поддерживаются только круговые регионы. Количество регионов ограничено одним. 
%       \item **) Для области фона поддерживаются все основные формы регионов. Количество регионов не ограничивается. Не поддерживаются регионы исключения.
      
%     \end{tablenotes}
% \end{table}

\section{Рекомендации по работе с научными продуктами уровня L3}
\label{sec:recom}

\subsection{Спектры}
\label{sec:spec}

Процедура \prods\ создаёт 7 спектров, измеренных по каждому модулю телескопа \art. Большое количество спектров неудобно загружать вручную, поэтому в данной главе приведено несколько примеров кода, позволяющих ускорить работу со спектрами. Также здесь описаны особенности работы со спектрами телескопа \art.

\subsubsection{Группировка данных}
\label{sec:spec}

Для использования статистики $\chi^2$ спектры необходимо перегруппировать так, чтобы отсчёты в каждом бине были нормально распределены. Каждый спектр рекомендуется перегруппировать с использованием команд \textsc{grrpha} или \textsc{ftgrouppha}, являющихся частью программного обеспечения \textsc{HEASOFT}. 

Спектры \textbf{ярких источников} могут быть перегруппированы единообразно, чтобы бины каждого спектра совпадали друг с другом. Рекомендуется группировать по 2 канала в бине для энергий до 20 кэВ, а от 20 кэВ --- по 5 или 10 каналов. Номер канала соответствует энергии, выраженной в кэВ и умноженной на 10. Для этого необходимо подготовить файл с информацией о том, как необходимо перегруппировать данные. Этот файл должен содержать 3 колонки: минимальный канал бина \verb*|MINCHAN|, максимальный канал бина \verb*|MAXCHAN|, число каналов в бине \verb*|NCHAN| (см. описание утилиты \href{https://heasarc.gsfc.nasa.gov/lheasoft/ftools/fhelp/grppha.txt}{grppha}). Если количество условий разбиения по каналам меньше 6, то эту информацию можно задавать напрямую в \textsc{grppha} с помощью команды: \verb*|group|~\verb*|50|~\verb*|200|~\verb*|2|~\verb*|201|~\verb*|250|~\verb*|5|~\verb*|251|~\verb*|300|~\verb*|10|. При необходимости можно увеличивать количество каналов в одном бине, однако рекомендуется указывать число \verb*|NCHAN|, не меньшее~2. 

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример содержания файла energy\_bins.txt с указанием границ бинов для перегруппировки спектров.}
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
50 200 2
201 250 5
251 300 10
\end{Verbatim}
\end{tcolorbox}

Также необходимо следить за тем, чтобы на высоких энергиях было достаточно отсчётов над уровнем фона для использования статистики $\chi^2$. Для этого нужно, чтобы спектр источника значимо превышался над уровнем фона. Проверить это можно, например, построив на одном графике спектры фона с помощью  \textsc{xspec} следующими командами: \verb*|setpl|~\verb*|back| и \verb*|pl|~\verb*|da|. Кроме того, можно сравнить количество отсчётов непосредственно в файлах со спектрами, однако, необходимо учитывать, что излучение источника и фона могли извлекаться из регионов разных площадей.



Стоит отметить, что из-за технических особенностей телескопа \art\ рекомендуется маркировать все отсчёты с энергиями до 5~кэв и выше 30~кэВ флагом "BAD" (в нотации \textsc{grppha} "\verb*|bad| \verb*|0-49| \verb*|301-650|") и добавлять систематическую ошибку на уровне 3\% ("\verb*|SYSTEMATICS| \verb*|50-300| \verb*|0.03|"). 
%Пример простого скрипта для запуска \textsc{grppha} для спектров всех модулей телескопа приведён ниже.

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример скрипта для перегруппировки спектров всех модулей телескопа \art\ с помощью процедуры \textsc{grppha} для яркого источника} (на примере наблюдения OBSID=11910040001).
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
#!/bin/bash

for MOD in {1..7}
do
    grppha infile="art119100400010T${MOD}_src.pha" outfile="art119100400010T${MOD}_src.grp.pha" comm="reset group & reset bad & bad 0-49 301-650 & group energy_bins.txt & SYSTEMATICS 50-300 0.03 & exit"
done 
\end{Verbatim}
% Здесь \verb*|energy_bins.txt| --- файл, содержащий информацию о разбиении спектра по каналам.
\dangersign[4ex] После проведения перегруппировки спектров необходимо проверить, что каждый бин содержит не менее 30 (или 25) отсчётов над фоновыми бинами, чтобы можно было использовать статистику $\chi^2$.
\end{tcolorbox}

В случае \textbf{слабого источника} при единообразной перегруппировке спектров \textbf{слабых источников} может быть недостаточно отсчётов, чтобы использовать статистику $\chi^2$. В таком случае можно использовать утилиту \textsc{grppha} без указания, по каким каналам перегруппировать спектр. Достаточным будет перегруппировать каждый спектр индивидуально, чтобы в спектральном бине было не менее 30 (или 25) отсчётов с помощью команды \verb*|group|~\verb*|min|~\verb*|30|. В таком случае каждый спектр будет перегруппирован с индивидуальным разбиением по спектральным каналам. Пример скрипта для индивидуальной перегруппировки спектров представлен ниже.
 
\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример скрипта для индивидуальной перегруппировки спектров всех модулей телескопа \art\ с помощью процедуры \textsc{grppha} для слабого источника} (на примере наблюдения OBSID=11910040001).
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
#!/bin/bash

for MOD in {1..7}
do
    grppha infile="art119100400010T${MOD}_src.pha" outfile="art119100400010T${MOD}_src.grp.pha" comm="reset group & reset bad & bad 0-50 300-650 & group min 30 & SYSTEMATICS 50-300 0.03 & exit"
done
\end{Verbatim}

\dangersign[4ex] После проведения перегруппировки спектров необходимо проверить, что каждый бин содержит не менее 30 (или 25) отсчётов, чтобы можно было использовать статистику $\chi^2$.
\end{tcolorbox}

Если же источник настолько слабый, что индивидуальная перегруппировка спектров с минимальным количеством отсчетов в бине, равным 30 (или 25), не приносит хороший результат, то спектры можно не перегруппировывать и аппроксимировать с использованием статистики Пуассона. В \textsc{xspec} статистика Пуассона включается с помощью команды \verb*|statistics|~\verb*|cstat|. О других возможных статистиках в \textsc{xspec} смотрите \href{https://heasarc.gsfc.nasa.gov/xanadu/xspec/manual/XSappendixStatistics.html}{здесь}. 

\subsubsection{Работа в \textsc{xspec}}
\label{sec:spec}

Для проведение научного анализа в \textsc{Xspec} спектры необходимо загружать параллельно с помощью команды \\ \verb*|da|~\verb*|<N>:<N>| \verb*|<STEM>T<N>_src.pha|, где \verb*|<N>| --- номер модуля телескопа \art. Для загрузки большого количества спектров одновременно удобно использовать скрипты на языке Tcl, которые можно загрузить в \textsc{xspec} следующим образом: \verb*|@<PATH>/<SCRIPT_NAME>.tcl|, где \verb*|<PATH>| --- путь к файлу со скриптом, а \verb*|<SCRIPT_NAME>.tcl| --- название самого файла. Пример такого скрипта приведён ниже.

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример скрипта для загрузки спектров каждого модуля телескопа \art\ в \textsc{xspec}} (на примере наблюдения OBSID=11910040001). 
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
#!/bin/bash 

for {set i 1} {$i < 8} {incr i} {
    da $i:$i "art119100400010T${i}_src.grp.pha" #загрузка спектров
    }
setpl en
cpd /xw
ign 1-7: **-6. 20.-** #ограничение энергетического диапазона
mo const*pow #простая спектральная модель
fit
pl eeuf del
setpl group 1-7 #только для единообразно перегруппированных спектров
\end{Verbatim}    

\dangersign[4ex] Обратите внимание, что для устранения неопределённостей, связанных с нормировкой разных модулей телескопа, необходимо к любой спектральной модели применять модель \verb*|const|.  
\end{tcolorbox}

Если спектры были сгруппированы по каналам единым образом, для графического представления результатов в \textsc{xspec} можно использовать команду \verb*|setpl|~\verb*|group|~\verb*|1-7|, которая представит все 7 спектров в виде одного, при этом спектры всё ещё будут аппроксимироваться индивидуально.  


\section{Отдельные задачи процедуры \prods}
\label{sec:tasks}

В некоторых случаях удобно по готовому списку событий уровня L3 (см. секцию~\ref{sec:artprod1}) построить отдельно кривую блеска или изображение и не запускать полную процедуру \prods. Данная глава содержит описание возможностей небольших задач, входящих в процедуру \prods, которые способны произвести отдельные научные продукты. 

\subsection{\artim}
\label{sec:im}

Задача \artim\ строит изображение в заданном энергетическом диапазоне от $E_{min}$ до $E_{max}$ для готового списка событий выбранного модуля телескопа \art, полученного процедурой \prods\ (см. секцию~\ref{sec:artprod1}). Параметры задачи \artim\ перечислены в таблице~\ref{tab:img}, а пример вызова приведён ниже. При успешном запуске задачи \artim\ в директории, указанной в параметре \verb*|dstdir|, будет создан файл \verb*|<STEM>T[1-7].img|. 

Построение суммарных изображений на данный момент реализовано только для полного запуска \prods\ (см. секцию~\ref{sec:artprod1}). Чтобы получить изображение для пользовательских временных интервалов, нужно выполнить пункт запуска \prods, описанный в секции~\ref{sec:artprod1}.
% При необходимости получить суммарное изображение в нестандартном энергетическом диапазоне, после генерации изображений для каждого модуля телескопа с помощью \artim\  нужно использовать утилиту \textsc{ftpixcal}, являющуюся частью пакета \textsc{ftools} программного обеспечения \textsc{heasoft}. 

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример вызова \artim} (на примере наблюдения OBSID=11910040001 и первого модуля телескопа~\art):

\begin{verbatim}
artimage \
    stem=art119100400010 \
    input=art119100400010T1_cl.evt \
    srcdir=./processed/119100400010/L3/events \
    dstdir=./processed/119100400010/L3/img \
    tmpdir=/temp --elow=6 --ehigh=12
\end{verbatim}

\dangersign[4ex] Повторный запуск процедуры \artim\ приводит к перезаписи  файлов в директории \verb*|dstdir|.
\end{tcolorbox}

%, с указанным файлом \verb*|--usergti=<PATH>/<GTI_FILE>.gti|, где \verb*|<PATH>| и \verb*|<GTIFILE>| --- путь к файлу и имя файла, содержащего пользовательские временные интервалы, соответственно. .

\begin{table}[!h]
  \centering 
  \caption{Параметры и ключи процедуры \artim, необходимые для получения изображения для заданного списка событий. Переменная <PATH> --- обозначает путь к соответствующим файлам. }

  \begin{tabular}{| m{5em} | m{5cm}| m{8.2cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|stem|   & \verb*|art<OBSID>[0-1]| & Префикс для имён входных и выходных файлов. \\
    \hline
    \verb*|input|  & \verb*|<STEM>T[1-7]_cl.evt| & Входной файл со списком событий, по которому будет построено изображение. \\
    \hline
    \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L3/events| & Входная директория, указывающая путь к спискам событий уровня L3. \\ 
    \hline
    \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3| & Выходная директория. \\ 
    \hline
    \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. \\ 
    \hline
    \verb*|--elow| & $E_{min}$, кэВ & Нижняя граница энергетического диапазона. По умолчанию $E_{min}=4$~кэВ. \\ 
    \hline
    \verb*|--ehigh| & $E_{max}$, кэВ & Верхняя граница энергетического диапазона. По умолчанию $E_{max}=12$~кэВ. \\ 
    \hline
  \end{tabular}
\label{tab:img}
\end{table}

\subsection{\artlc}
\label{sec:lc}

Задача \artlc\ строит кривую блеска в заданном энергетическом диапазоне от $E_{min}$ до $E_{max}$ с временным бином $T_{bin}$ для готового списка событий выбранного модуля телескопа \art, полученного процедурой \prods\ (см. секцию~\ref{sec:artprod1}). При этом кривая блеска источника извлекается из региона источника \verb*|srcreg|, а фон оценивается в фоновом регионе \verb*|bkgreg|. Параметры задачи \artlc\ перечислены в таблице~\ref{tab:lc}, а пример вызова приведён ниже. При успешном запуске задачи \artlc\ в директории, указанной в параметре \verb*|dstdir|, будут созданы файлы \verb*|<STEM>T[1-7]_src.lc| и \verb*|<STEM>T[1-7]_bkg.lc|, содержащие кривые блеска источника и фона соответственно. 

Чтобы получить кривую блеска для пользовательских временных интервалов, нужно выполнить пункт запуска \prods, описанный в секции~\ref{sec:artprod1}, т.к. в задаче \artlc\ это не реализовано.

\begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
\textbf{Пример вызова \artlc} (на примере наблюдения OBSID=11910040001 и первого модуля телескопа~\art):

\begin{verbatim}
artlcurve \
    stem=art119100400010 \
    input=art119100400010T1_cl.evt \
    srcdir=./processed/119100400010/L3/events \
    dstdir=./processed/119100400010/L3/lc \
    tmpdir=/temp \
    srcregion=./processed/L3/reg/art119100400010_src.reg \
    bkgregion=./processed/L3/reg/art119100400010_bkg.reg \
    --elow=6 --ehigh=12 \
    --binsize=1
\end{verbatim}

\dangersign[4ex] Обратите внимание, что файлы, содержащие информацию о регионах для источника (фона), задаются параметрами \verb*|srcregion| (\verb*|bkgregion|) вместо ранее используемых для процедуры \prods\ параметров \verb*|--srcreg| (\verb*|--bkgreg|).

\dangersign[4ex] \dangersign[4ex] Повторный запуск процедуры \artlc\ приводит к ошибке выполнения данной программы. Перезапись файлов при повторном запуске процедуры на данный момент не реализована , поэтому рекомендуется удалить ранее сгенерированные файлы или изменить выходную директорию.
\end{tcolorbox}

\begin{table}[!h]
  \centering 
  \caption{Параметры и ключи процедуры \artlc, необходимые для получения кривой блеска по заданному списку событий. Переменная <PATH> --- обозначает путь к соответствующим файлам. } 

  \begin{tabular}{| m{5em} | m{5cm}| m{8.2cm} |}
    \hline\hline

    \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
    \hline
    \verb*|stem|   & \verb*|art<OBSID>[0-1]| & Префикс для имён входных и выходных файлов. \\
    \hline
    \verb*|input|  & \verb*|<STEM>T[1-7]_cl.evt| & Входной файл со списком событий, по которому будет построена кривая блеска. \\
    \hline
    \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L3/events| & Входная директория, указывающая путь к спискам событий уровня L3. \\ 
    \hline
    \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3| & Выходная директория. \\ 
    \hline
    \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. \\ 
    \hline
    \verb*|srcregion| & \verb*|<PATH>/<SRC_NAME>.reg| & Регион, из которого извлекается кривая блеска  источника.  \\ 
    \hline
    \verb*|bkgregion| & \verb*|<PATH>/<BKG_NAME>.reg| & Регион, из которого извлекается кривая блеска фона. \\ 
    \hline
    \verb*|--elow| & $E_{min}$, кэВ & Нижняя граница энергетического диапазона. По умолчанию $E_{min}=4$~кэВ. \\ 
    \hline
    \verb*|--ehigh| & $E_{max}$, кэВ & Верхняя граница энергетического диапазона. По умолчанию $E_{max}=12$~кэВ. \\ 
    \hline
    \verb*|--binsize| & $T_{bin}$, c & Размер временного бина кривой блеска. По умолчанию $T_{bin}=1$~с. \\ 
    \hline
  \end{tabular}
\label{tab:lc}
\end{table}

% \subsection{\artsp}
% \label{sec:sp}

% Задача \artsp\ предназначена для получения спектра в заданном круговом региона для готового списка событий выбранного модуля телескопа \art, полученного процедурой \prods\ (см. секцию~\ref{sec:artprod1}). При этом сначала нужно извлечь спектр фона из заданного региона, а затем извлечь спектр источника из соответствующего региона с указанием ключа \verb*|--bkgfile='yes'|, чтобы в \verb*|HEADER| файла со спектром источника задача \artsp\ указала имя файла со спектром фона. Кроме того, чтобы спектр фона корректно вычитался из спектра источника при загрузке последнего в утилиту \textsc{xspec}, при получении спектра источника необходимо указать параметр \verb*|--backscale|, равный отношению площадей региона источника к фоновому региону $S_{src}/S_{bkg}$. Параметры задачи \artsp\ перечислены в таблице~\ref{tab:sp}, а пример вызова приведён ниже. При успешном запуске задачи \artsp\ в директории, указанной в параметре \verb*|dstdir|, будут созданы файлы \verb*|<STEM>T[1-7]_bkg.pha| и \verb*|<STEM>T[1-7]_src.pha|, содержащие кривые блеска фона и источника соответственно. 

% Чтобы получить спектр для пользовательских временных интервалов, нужно выполнить пункт запуска \prods, описанный в секции~\ref{sec:artprod2}, т.к. в задаче \artsp\ это не реализовано.

% \begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
% \textbf{Примеры вызова \artsp\ для  получения спектра фонового излучения}:

% \begin{verbatim}
% artxspec \
%     stem=art119100400010 \
%     input=art119100400010T1_cl.evt \
%     srcdir=./processed/119100400010/L3/events \
%     dstdir=./processed/119100400010/L3/pha \
%     tmpdir=/temp \
%     --region=./processed/L3/reg/art119100400010_bkg.reg \
%     --prodname='bkg'
% \end{verbatim}

% \textbf{и спектра источника:} 
% %(на примере наблюдения OBSID=11910040001 и первого модуля телескопа~\art):
% \begin{verbatim}
% artxspec \
%     stem=art119100400010 \
%     input=art119100400010T1_cl.evt \
%     srcdir=./processed/119100400010/L3/events \
%     dstdir=./processed/119100400010/L3/pha \
%     tmpdir=/temp \
%     --region=./processed/L3/reg/art119100400010_src.reg \
%     --prodname='src' \
%     --bkgfile='yes' --backscale=1 
% \end{verbatim}

% \dangersign[4ex] Повторный запуск процедуры \artsp\ приводит к ошибке выполнения данной программы. Перезапись файлов при повторном запуске процедуры на данный момент не реализована, поэтому рекомендуется удалить ранее сгенерированные файлы или изменить выходную директорию.
% \end{tcolorbox}

% \begin{table}[!h]
%   \centering 
%   \caption{Параметры и ключи процедуры \artsp, необходимые для получения спектра по заданному списку событий в заданном регионе. Переменная <PATH> --- обозначает путь к соответствующим файлам. }

%   \begin{tabular}{| m{6em} | m{4.8cm}| m{8.2cm} |}
%     \hline\hline

%     \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
%     \hline
%     \verb*|stem|   & \verb*|art<OBSID>[0-1]| & Префикс для имён выходных файлов. \\
%     \hline
%     \verb*|input|  & \verb*|<STEM>T[1-7]_cl.evt| & Входной файл со списком событий, по которому будет построен спектр. \\
%     \hline
%     \verb*|srcdir| & \verb*|<PATH>/<OBSID>/L3/events| & Входная директория, указывающая путь к спискам событий уровня L3. \\ 
%     \hline
%     \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3/pha| & Выходная директория. \\ 
%     \hline
%     \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. \\ 
%     \hline
%     \verb*|--region| & \verb*|<PATH>/<SRC_NAME>.reg| & Регион, из которого извлекается спектр.  \\ 
%     \hline
%     \verb*|--prodname| & \verb*|'src'| или \verb*|'bkg'| & Постфикс для имен выходных файлов вида \verb*|<STEM>T[1-7]_<PRODNAME>.pha|. \\ 
%     \hline
%     \verb*|--bkgfile| & \verb*|'yes'| & Ключ, добавляющий в HEADER имя файла с фоновым спектром в следующем виде: \verb*|<STEM>T[1-7]_bkg.pha|. Необходимо использовать при генерации спектра источника. По умолчанию эта опция выключена. \\ 
%     \hline
%     \verb*|--backscale| & $S_{src}/S_{bkg}$ & Отношение площади региона источника ($S_{src}$) к площади фонового региона ($S_{bkg}$). По умолчанию $S_{src}/S_{bkg}=1$. Этот параметр необходим для генерации спектра источника. \\ 
%     \hline
%   \end{tabular}
% \label{tab:sp}
% \end{table}

% Для дальнейшей работы со спектрами необходимы следующие файлы: с матрицей отклика детектора (RMF) и описывающий зависимость эффективной площади детектора от энергии фотона (ARF). Файл ARF производится с помощью задачи \artarf\ (см. секцию~\ref{sec:arf}), а уже готовые файлы RMF для каждого модуля телескопа необходимо скопировать в директорию, в которой находятся спектры. На серверах сети СРГ файлы RMF можно найти здесь: \verb*|work/srg/artxc/pipeline/bin/aux/rmf/| \verb*|artxc_rmf_T[1-7]_20191030_v003.rmf|, где \verb*|T[1-7]| соответствует номеру модуля телескопа \art. Чтобы \textsc{xspec} автоматически подгрузил файлы RMF и ARF, перед спектральным анализом необходимо указать в \verb*|HEADER| итогового файла со спектром источника пути к RMF и ARF-файлам в переменных \verb*|[ANCRFILE]| и \verb*|[RESPFILE]| соответственно. Это можно сделать с помощью следующих команд утилиты \textsc{fthedit}:

% \begin{verbatim}
% fthedit <STEM>T[1-7]_src.pha ANCRFILE add <STEM>T[1-7].arf
% fthedit <STEM>T[1-7]_src.pha RESPFILE add artxc_rmf_T[1-7]_20191030_v003.rmf
% \end{verbatim}


% \subsection{\artarf}
% \label{sec:arf}

% Задача \artarf\ необходима для генерации ARF-файла заданного модуля телескопа на удалении от оптической оси, которые определяется положением источника в детекторных координатах (параметры \verb*|X| и \verb*|Y|). На вход задачи \artarf\ подаются параметры, перечисленные в таблице~\ref{tab:arf}. В результате успешного выполнения задачи \artarf\ в выходной директории будет создан файл \verb*|<STEM>T[1-7].arf|.

% \begin{tcolorbox}[colback=MidnightBlue!5!white,colframe=MidnightBlue!75!black]
% \textbf{Примеры вызова \artarf\ для  получения спектра фонового излучения}:

% \begin{verbatim}
% artmkarf \
%     stem=art119100400010 \
%     teln=1 \
%     dstdir=./processed/119100400010/L3/pha \
%     tmpdir=/temp \
%     X=24 Y=24
% \end{verbatim}

% %\dangersign[4ex] Повторный запуск процедуры \artarf\ приводит к ошибке выполнения данной программы. Перезапись файлов при повторном запуске процедуры на данный момент не реализована, поэтому рекомендуется удалить ранее сгенерированные файлы или изменить выходную директорию.
% \end{tcolorbox}

% \begin{table}[!h]
%   \centering 
%   \caption{Параметры и ключи процедуры \artarf, необходимые для получения ARF-файла для конкретного модуля телескопа. Переменная <PATH> --- обозначает путь к соответствующим файлам. }

%   \begin{tabular}{| m{6em} | m{4.8cm}| m{8.2cm} |}
%     \hline\hline

%     \textbf{Параметр} & \textbf{Значение} & \textbf{Описание}  \\
%     \hline
%     \verb*|stem|   & \verb*|art<OBSID>[0-1]| & Префикс для имён выходных файлов. \\
%     \hline
%     \verb*|teln|  & \verb*|[1-7]| & Номер модуля телескопа, для которого нужно произвести ARF-файл. \\
%     \hline
%     \verb*|dstdir| & \verb*|<PATH>/<OBSID>/L3/pha| & Выходная директория. \\ 
%     \hline
%     \verb*|tmpdir| & \verb*|/temp| & Директория для временных файлов. \\ 
%     \hline
%     \verb*|X| & \verb*|X| & Детекторная X координата центра региона источника, из которого извлекался спектр. \\ 
%     \hline
%     \verb*|Y| & \verb*|Y| & Детекторная Y координата центра региона источника, из которого извлекался спектр. \\ 
%     \hline
%   \end{tabular}
% \label{tab:arf}
% \end{table}

\section{Возможные ошибки и их решения}
\label{sec:err}

\noindent
При неправильно настроенном окружении могут возникать разные ошибки, не относящиеся к работе запускаемых процедур. Ниже приведён список возможных ошибок, связанных с настройкой окружения.

\textbf{1. Возникает проблема с отсутствием утилит \textsc{heasoft}.} 

Для процедуры \pipe\ выдаётся следующая ошибка:
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
    \begin{Verbatim}[breaklines=true,  breakanywhere=true]
    FileNotFoundError: [Errno 2] No such file or directory: 'ftcopy'
    [2023-01-17 15:26:12.367635] error: artpipeline v1.0 exited with status 1
    ===========================================================================
     [artpipeline v.1.0]: exit with status: failed (at stage: L1)
    ===========================================================================
    [2023-01-17 15:26:12.367883] info: artpipeline finished
    \end{Verbatim}
\end{tcolorbox}

При вызове процедуры \prods\ с ключом \verb*|--prepare-skytile| (см. секцию~\ref{sec:artprod1}):
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
    \begin{Verbatim}[breaklines=true,  breakanywhere=true]
FileNotFoundError: [Errno 2] No such file or directory: 'ftappend'
[2023-01-17 15:30:02.304878] error: artproducts v1.0 exited with status 1
===========================================================================
 [artproducts v.1.0]: exit with status: failed (at stage: run)
===========================================================================
[2023-01-17 15:30:02.305163] info: artproducts finished
    \end{Verbatim}
\end{tcolorbox}

При вызове процедуры \prods\ для получения спектров и кривых блеска (см. секцию~\ref{sec:artprod2}):
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
    \begin{Verbatim}[breaklines=true,  breakanywhere=true]
FileNotFoundError: [Errno 2] No such file or directory: 'ftcopy'
[2023-01-17 15:31:15.253313] error: artproducts v1.0 exited with status 1
============================================================================
 [artproducts v.1.0]: exit with status: failed (at stage: run)
============================================================================
[2023-01-17 15:31:15.253593] info: artproducts finished
    \end{Verbatim}
\end{tcolorbox}

\textit{Проблема:} не установлен или не инициализирован \textsc{heasoft}. 

\textit{Решение:} установить и инициализировать версию \textsc{heasoft} не позднее 6.28. Пример файла \verb*|~\.tcshrs| со всеми необходимыми настройками приведён для 18-го сервера в секции~\ref{sec:prep}.

\textbf{2. Возникает проблема с отсутствием необходимых библиотек \textsc{heasoft}.} При этом последний модуль процедуры \pipe\ выдает успешное завершение, хотя несколькими строками выше выведена ошибка следующего вида:

\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
    \begin{Verbatim}[breaklines=true,  breakanywhere=true]
    ftcopy: error while loading shared libraries: libreadline.so.6: cannot open shared object file: No such file or directory
    \end{Verbatim}
\end{tcolorbox}

\textit{Проблема:} неправильно настроено окружение для работы \textsc{heasoft}. 

\textit{Решение:} установить недостающие библиотеки и указать путь к ним в переменной \verb*|LD_LIBRARY_PATH| в файле \verb*|~\.tcshrs|. Пример файла \verb*|~\.tcshrs| со всеми необходимыми переменными приведён для 18-го сервера в секции~\ref{sec:prep}.

\textbf{3. Вызов \prods, описанный в секции~\ref{sec:artprod2} не срабатывает.} Выдается следующая ошибка: 
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
    raise ValueError("Number of world inputs ({}) does not match "
ValueError: Number of world inputs (1) does not match expected (2)
\end{Verbatim}
\end{tcolorbox}

\textit{Проблема:} указана неправильная входная директория \verb*|<PATH>/<OBSID>/L2| для процедуры \prods.

\textit{Решение:} в качестве входной директории указать  \verb*|<PATH>/<OBSID>/L3/events|.

\textbf{4. Не перезаписываются файлы при повторном запуске процедуры \prods.}

\textbf{4.1.} При повторном запуске процедуры \prods\ с ключом \verb*|--prepare-skytile| (см. секцию~\ref{sec:artprod1}) последний модуль завершается успешно, однако директория \verb*|<OBSID>\L3\events| не обновляется и где-то выше в текстовом выводе процедуры можно найти ошибку: 
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
Dumping CFITSIO error stack:
--------------------------------------------------
failed to create new file (already exists?):
./121100540010/L3/events/art121100540010T6_cl.evt
--------------------------------------------------
CFITSIO error stack dump complete.
CFITSIO ERROR FILE_NOT_CREATED: couldn't create the named file
Task ftcopy 1.00 terminating with status 105
[2023-01-17 14:51:46.346641] error: artevlist v1.0 exited with status 105
exit with status: failed (at stage: run)
\end{Verbatim}
\end{tcolorbox}
Обратите внимание, что файлы в директории \verb*|<OBSID>\L3\img| при этом перезаписываются.

\textbf{4.2.} При генерации спектров и кривых блеска повторным запуском процедуры \prods\ (см. секцию~\ref{sec:artprod2}) возникает следующая ошибка:
\begin{tcolorbox}[colback=Maroon!5!white,colframe=Maroon!75!black]
\begin{Verbatim}[breaklines=true,  breakanywhere=true]
raise OSError(f"File {self.name!r} already exists.")
OSError: File './121100540010/L3/lc/art121100540010T1_src.lc' already exists.    
\end{Verbatim}
\end{tcolorbox}

\textit{Проблема:} в выходной директории остались файлы от прошлого запуска процедур. На данный момент не реализована возможность перезаписи файлов при повторном запуске процедуры \prods.

\textit{Решение:} очистить директорию от файлов прошлых запусков процедур (или изменить выходную директорию) и вызвать процедуру заново.


\noindent 

% \section{Поочерёдный список примеров вызовов функций для обработки данных телескопа \art.}

\section*{Приложение. Список изменений документа относительно версии 1.10.}
\addcontentsline{toc}{section}{Приложение. Список изменений документа. }

\begin{table}[h]
  \centering
%\caption{Список изменений документа относительно версии 1.10.}

  \begin{tabular}{| m{1.2cm} | m{1.2cm} | m{5cm} | m{7cm} |}
    \hline
    \textbf{Версия} & \textbf{Дата} & \textbf{Переработка}  & \textbf{Дополнения}\\

    \hline
    2.0 beta & 02.02.23 &  Текста, оформление, структура документа, таблицы параметров & Описание структуры WCS-файла, схема уровней данных, рекомендации по настройке окружения на сервере, таблицы с описанием содержимого директорий, рекомендации по работе с научными продуктами, список возможных ошибок и их решений, оглавление, описание отдельных задач процедуры \prods. \\
    2.1 beta & 2.03.23 & Описание группировки спектров, инициализация на серверах & \\
    \hline
  \end{tabular}
\end{table}


\FloatBarrier


% \section*{Приложение 1. Структура файлов}

% \subsection*{Данные уровня L0 --- исходные данные}


% \subsection*{Данные уровня L2 --- очищенные и калиброванные события}
% \subsection*{Данные уровня L3 --- научные продукты}
\end{document}
