Alessandro Ridolfi's home page






SPIDER_TWISTER on GitHub

Latest version: 1.6 (12Oct2020)

git clone https://github.com/alex88ridolfi/SPIDER_TWISTER.git



SPIDER_TWISTER




Requirements: 		SPIDER_TWISTER helps you recover the signal of black widow / redback pulsars by doing a search in orbital phase.


"Black widow" and "Redback" binary pulsars (also called "spiders") are known to often show a strong orbital variability, with their orbital period changing in a quasi-random fashion over long time scales. For this reason, an old ephemeris is often not able to fold newer data of the same pulsar, because the orbital model cannot correctly predict the exact orbital phase at a later time.


SPIDER_TWISTER performs a search in orbital phase, by automatically folding the data using several trial values for the time of passage at the ascending node ($T_{\rm asc}$) and returning the value that corresponds to the highest-S/N. In this way, recovering the signal of "spiders" is super easy!

Play the video below for a DEMO!





DOCUMENTATION


1) Installation

No actual installation procedure is needed to use SPIDER_TWISTER itself. However, since it calls some PRESTO routine, you first need to have PRESTO installed.

To install PRESTO, you can follow this pulsar software installation guide.

Once PRESTO is installed and correctly working, you can get started with SPIDER_TWISTER:

  1. Download the code from GitHub using the "git clone" command above
    git clone https://github.com/alex88ridolfi/SPIDER_TWISTER.git

  2. Move to the newly dowloaded directory
    cd SPIDER_TWISTER

  3. Run the code with:
    ./spider_twister

Obviously, to have SPIDER_TWISTER at hand from any directory, you can add the folder where the code is located to your PATH environment variable.



2) Basic usage

To successfully use SPIDER_TWISTER, you need:

  1. A topocentric PRESTO dedispersed time series (".dat" file, plus the corresponding ".inf" file) which supposedly contains the signal of the pulsar of interest. To generate a topocentric PRESTO dedispersed time series, you can use the PRESTO's prepdata routine on the original search mode data, using the -nobary option.

    WARNING: if you use a barycentric time series, the code will not work correctly and will exit reporting an error! Make sure that you are using a topocentric time series.

  2. The best ephemeris (".par" file) available for the pulsar, containing at least the basic orbital parameters, namely: A1, PB, E, OM, T0 (see the TEMPO/TEMPO2 reference manuals for their meaning).

Assuming to have a dedispersed time series called "SRT_J1723-2837_58590.dat" and a corresponding best available ephemeris called "J1723-2839.par", you can run SPIDER_TWISTER by simply typing:

spider_twister -par J1723-2839.par -dat SRT_J1723-2837_58590.dat -ncpus 8 -orboffset "-0.01,0.01"



Besides giving you the best $T_0$ trial, the code outputs a plot of the detection significance (Chi-Square) as a function of orbital phase offset, as well as the prepfold diagnostic plot of the best detection.






3) Command line options

You can use a number of options to adapt SPIDER_TWISTER to specific applications and cases. Here follows a list of all the available options:

  • -par <parfile>
    Use <parfile> as the starting ephemeris file.

  • -dat <observation.dat>
    The input TOPOCENTRIC time series <observation.dat> to fold using several trial values of $T_0$ / $T_{\rm asc}$.

  • [ -fine ]
    Do a fine search, doubling the number of given by Eq. (5) of Ridolfi et al. (2016).
    Recommended for very faint and narrow-pulse pulsars.

  • [ -nsteps N ]
    Use N trial values of $T_0$ / $T_{\rm asc}$ in the considered range of orbital phase offsets.
    Overrides the default value, which is calculated according to Eq. (5) of Ridolfi et al. (2016).

  • [ -orboffset "X.X,Y.Y" ]
    Specify the range of orbital phase (mean anomaly) offsets by which the nominal $T_0$ value (as read from the ephemeris) should be offset. (X,Y are floats)
    Example: -orboffset "-0.1,0.1" means that all the values of $T_0$ in the range $[T_0^* -0.1\,P_b, T_0^* +0.1\,P_b]$ where $P_b$ is the orbital period and $T_0^*$ is the nominal Keplerian epoch of passage at periastron, closest to the start time of the input observation.

  • [ -ncpus N ]
    Use N threads when folding using different $T_0$ / $T_{\rm asc}$, splitting the considered range of orbital phase offset into N sub-intervals.

  • [ -prepfold_options '-opt1 -opt2 ...' ]
    Additional options/flags to give to prepfold when folding.

  • [ -keep_best N ]
    Keep the N best folded profile.

  • [ -noreport ]
    Do not write the report file.

  • [ -noplot ]
    Do not write not make the chi-square vs trial $T_0$ plot.

  • [ -D ]
    Show the chi-square vs trial $T_0$ plot in real time while processing.

  • [{ -Q | -V}]
    -Q: quiet mode. Do not print anything onto the standard output. Useful to call SPIDER_TWISTER within scripts or pipelines.
    -V: very verbose mode. Print a lot of additional information. Log the output of all the folding commands. Useful for debugging purposes.

  • [{ -v | -version | --version }]
    Show code version.

  • [{ -h | -help | --help }]
    Show a simple usage help and the list of options.




4) Acknowledgements

Big thanks to Jason Wu, Arianna Miraval Zanon, Tasha Gautam and Laila Vleeschower Calas for using the code, reporting bugs, and suggesting improvements.



5) References

SPIDER_TWISTER, mostly in its early stage of development, has been used to redetect several black widows and redbacks, in many cases of which this led to the obtainment of phase connected timing solutions. Here follow the list of articles for which the code has been used: