Chrono reader

This class includes the following methods:

chrono_reader.intellicage_unwrapper(files, name_to_save='', sampling_interval='1H')

This function is used to unwrap the data from the Intellicage system, which is saved in a compact format. The data is extraxted using the pymice package and the data from each animal is saved in a separated txt file. An important subfunction used in this function is the visits_by_intervals, which is used to get the visits in a specific interval of time, because the Intellicage system saves the visits with irregular intervals.

Parameters:

  • files (list) – List with the files to be unwrapped

  • name_to_save (str) – Folder to save the data, if not specified, the data will be saved in the same folder as the files in a folder called ‘data_unwrapped’

  • sampling_interval (str) – Sampling interval to get the visits (output sampling interval), defaults to ‘1H’

class chrono_reader.read_protocol(name, file, zt_0_time, labels_dict, type, consider_first_day=False, set_nans=array([], dtype=float64), separator=',', date_type='%m/%d/%y %H:%M:%S')

Bases: object

Return a list of random ingredients as strings.

Parameters:

  • name (str) – Name of the protocol

  • file_activity (str) – Path to the data file (can be a .asc if the type is generic)

  • zt_0_time (int) – Time of day that corresponds to ZT0 reference (can only be integers from 0 to 23)

  • labels_dict (dict) – Dictionary with the cycle types, cycle days and test labels. The cycle types must be a list of strings with the cycle types (DD, LL, DL or LD), the cycle days must be a list of integers with the number of days of each cycle and the test labels must be a list of strings with the test labels (e.g. [‘test1’, ‘test2’, ‘test3’])

  • consider_first_day (bool) – Consider the first day of the experiment as a complete day, defaults to False

  • set_nans (list) – List of integers with the indexes of the NaN values that will be set to 0, defaults to []

Returns:

A protocol object

Return type:

protocol object

apply_filter(type='savgol', window=5, order=3, reverse=False, inplace=True)

Apply filters to the data. The filters available are Savitzky-Golay filter and moving average filter. The Savitzky-Golay and moving average filter are a type of low-pass filter, particularly suited for smoothing noisy. (to reverse the filter, use the reverse parameter).

Parameters:

  • type (str) – Type of filter to apply: Savitzky-Golay (‘savgol’) filter or move average (‘moving_average’) filter, defaults to ‘savgol’.

  • window (int) – The length of the filter window (i.e. the number of coefficients). Must be a positive odd integer, defaults to 5

  • order (int) – The order of the polynomial used to fit the samples. Must be less then window size, defaults to 3

  • reverse (bool) – Revert the filter, defaults to False

concat_protocols(protocol, method)

Concatenate two protocols. The protocols must have the same units of activity, temperature and sampling interval. The second protocol will be concatenated to the first one inplace.

Parameters:

  • protocol (Protocol) – Protocol to concatenate

  • method (str) – Method to concatenate the data. Use ‘sum’ to sum the values in the new sampling interval or ‘last’ to get the last value in the new sampling interval

correct_labels()

This function is used to correct labels that may be wrong after importing the data and using the protocol concatenation function. Generally, it will be used when the experimental protocol was performed by separating the files. In these cases, the exact time that the experimenter cut the record may not match the correct labels, since each file will be imported with a specific label.

Example:

date

hour

cycle

is_night

label

01/01/2023

23:00:00

DL

False

A

01/01/2023

23:30:00

DD

True

B

<- This label is wrong

01/02/2023

00:00:00

DD

True

B

01/02/2023

00:30:00

DD

True

B

After using the correct_labels function, the table is updated as follows:

date

hour

cycle

is_night

label

01/01/2023

23:00:00

DL

False

A

01/01/2023

23:30:00

DL

False

A

<- This label is corrected

01/02/2023

00:00:00

DD

True

B

01/02/2023

00:30:00

DD

True

B
Returns:

None

delete_first_days(number_of_days)

Delete the first days of the activity data.

Parameters:

number_of_days (int) – Number of days to be deleted

delete_last_days(number_of_days)

Delete the last days of the data.

Parameters:

number_of_days (int) – Number of days to be deleted

delete_period(first_day_between, last_day_between, test_label)

Delete the days between the two parameters

Parameters:

  • first_day_between – First day in the interval to be deleted

  • last_day_between – Last day in the interval to be deleted

get_cosinor_df(time_shape='continuous')

Get the dataframe to be used in cosinor analysis (CosinorPy input). Each dataframe contains three columns: “type” (protocol step label e.g ‘Control’), “x” (time in hours) and “y” (activity or temperature). The “x” columns can be ‘continuous’ (range from 0 to the total number of hours) or ‘mean’/’median’ (setted in clycles of 24 hours). With the time_shape is setted to ‘mean’ or ‘median’, the data will be grouped by day and the mean or median will be calculated for each day.

Parameters:

time_shape (str) – Shape of the time variable. Set ‘continuous’ for a continuous variable or ‘mean’/’median’ for a clycic time columns, defaults to ‘continuous’

Returns:

Dataframes with activity and temperature data

Return type:

pandas.DataFrame, pandas.DataFrame

get_is_nan_indexes()

Get a boolean array indicating if each data point is nan or not. The array is True if the data point is nan and False if the data point is not nan.

Returns:

Boolean array indicating if the activity data is nan or not

Return type:

numpy.ndarray

get_last_days_data(num_days, test_labels)

Function to get the last n days of the data. The number of days must be equal or less than the number of days in the data. The test labels must be a list with the test labels to get the data from. The test labels must be in the data.

Parameters:

  • num_days (int) – Number of days to get the data from

  • test_labels (list) – List with the test labels to get the data from

get_specific_days_data(days, test_labels)

Function to get specific days of the data. The days must be a list with the days to get the data from and the test labels must be a list with the test labels to get the data from.

Parameters:

  • days (list) – List with the days to get the data from

  • test_labels (list) – List with the test labels to get the data from

make_info_text()
normalize_data(type='minmax', per_day=False)

Normalize the data using the z-score or minmax method. The z-score method subtracts the mean of the data and divides by the standard deviation. The minmax method subtracts the minimum value and divides by the difference between the maximum and minimum values.

Parameters:

  • type (str) – Type of normalization to apply, can be ‘zscore’ or ‘minmax’, defaults to ‘minmax’

  • per_day (bool) – Normalize the data. If True, the normalization will be done per day, if False, the normalization will be done for the whole data, defaults to False

read_asc_0()

Function to read the activity file from the ER4000 system. The file must be a .asc file.

read_asc_2()

Function to read the activity file from the Intellicage system. The file must be a .asc file. Before executing this function, the Intellicage output file must be converted to a .asc file using the intellicage_unwrapper functions.

read_asc_3()

Function to read the data file from the generic file. The file must be a .asc file with the following format (date,hour,activity) where the date is in the format mm/dd/yy, the hour is in the format hh:mm:ss and the activity is a float number. 01/01/22,00:00:00,36.00 01/01/22,00:30:00,41.00 01/01/22,01:00:00,36.00

resample(new_sampling_interval, method='sum')

Resample the data to a new sampling interval.

Parameters:

  • new_sampling_interval (str) – New sampling interval in pandas format (e.g. ‘30T’ for 30 minutes)

  • method – Method to resample the data. Use ‘sum’ to sum the values in the new sampling interval or ‘last’ to get the last value in the new sampling interval

save_data(save_file)

Save the data of the protocol in a csv file

Parameters:

save_file (str) – Path to save the file

specify_test_labels(number_of_days, test_labels, cycle_types)

Specify the test labels to be used in the analysis. This function can be used to set the test labels, the cycle type after the data is imported.

Parameters:

  • number_of_days (list) – Number of days to be used in each test label, the sum of the days must be equal to the number of days in the experiment

  • test_labels (list) – Test labels to be used in the analysis, must be a list of strings with the same length of number_of_days

  • cycle_types (list) – Cycle types to be used in the analysis, must be a list of strings with the same length of number_of_days