Description

This routine returns the path(s) and name(s) of SPICE FITS files that correspond to the specified time or lie within a given time window. The logic for what filename(s) is returned is as follows:

If only the start time is given, then the file closest to that time is returned or, if SEQUENCE keyword is set, all files with the same SPIOBSID as the file closest to that time are returned.

If both, the end and start time are given, all files within the time window are returned or, if SEQUENCE keyword is set, all SPICE observations that have at least one file within the time window are returned.

The routine also returns files that are compressed with gzip. These files can be used directly with the SPICE_DATA object.

Syntax

Result = SPICE_FIND_FILE(time_start [, time_end=time_end] [, level=level] [, top_dir=top_dir] [, path_index=path_index] [, count_file=count_file] [, count_seq=count_seq] [, /sequence] [, /all] [, /no_level] [, /no_tree_struct] [, /user_dir] [, /search_subdir] [, /ignore_time ] [, /remove_duplicates] )

Return Value

A string or string array containing the full path to a SPICE file or files. If there are no matches, then an empty string is returned. If the keyword SEQUENCE is set and time_end is provided, then a LIST is returned in which each element is a string or string array with paths to SPICE FITS files that belong to the same SPICE observation.

Arguments

time_start

This can be in any format accepted by the ANYTIM suite of routines. For example, '1-jan-2010', '2010-01-01 05:00'. This is either the time for which the file closest to it is returned, or the start of the time window to be searched, in case 'time_end' is also provided.

Optional Input

time_end

This can be in any format accepted by the ANYTIM suite of routines. For example, '1-jan-2010', '2010-01-01 05:00'. This is the end of the time window to be searched.

level

Desired level of the data (0, 1, 2 (default) or 3).

top_dir

Top directory in which the SPICE data lies. If not provided the path defined in $SPICE_DATA is searched.

path_index

If $SPICE_DATA or 'top_dir' contains multiple paths, then this keyword allows you to specify which path should be searched. Default is 0.

Optional Output

count_file

Set this keyword to a named variable that receives an integer containing the number of matching files.

count_seq

Set this keyword to a named variable that receives an integer containing the number of matching sequences, only non-zero if 'sequence' is set.

Keywords

sequence

If set, then all files of the sequence that the found files belong to will be returned, i.e. the time window to be searched is expanded to include files outside of the given time window, but only sequences (= Spice observations) that have at least one file in the given time window are returned. If set and 'time_end' is provided, the returned value will be a LIST in which each element is a string or string array with paths to SPICE FITS files that belong to the same sequence.

all

If set, then all filenames for the specified day will be returned. Ignored if 'time_end' is provided or if 'no_tree_struct' or 'sequence' is set.

no_level

If set, then the level part of the default path is omitted (e.g. $SPICE_DATA/2020/06/21/ instead of $SPICE_DATA/level2/2020/06/21/).

no_tree_struct

If set, then the tree structure won't be appended to 'top_dir' (e.g. TOP_DIR/level2/ instead of TOP_DIR/level2/2020/06/21/).

user_dir

If set, the procedure searches in TOP_DIR/user/ instead of TOP_DIR/.

search_subdir

If set then the program looks for spice files recurrently, i.e. in all subdirectories.

ignore_time

If set, 'time_start' and 'time_end' are ignored, and all files will be returned. Ignored if 'no_tree_struct' is not set. This keyword makes it possible to return all files that are stored locally.

REMOVE_DUPLICATES

If set, then the procedures checks whether there are any files that have same SPIOBS, raster number and level. If yes, it keeps only the one with the highest version number. This keyword is set by default if TIME_END is not provided and /ALL is not set. REMOVE_DUPLICATES has to be set to zero explicitly to get all versions of a file.