9. Examples

Examples showing how to simply benefit from cpforager package with your biologging data.

9.1. GPS

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, GPS


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "gps")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork = "BRA_FDN_2016_09"
colony    = "BRA_FDN_MEI"
file_name = "BRA_FDN_MEI_2016-09-15_SSUL_01_T32840_NA_GPS_IGU120_BR023_LOC.csv"
file_id   = file_name.replace(".csv", "")
file_path = os.path.join(data_dir, fieldwork, file_name)

# set list of configuration paths
config_colony_path  = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_general_path = os.path.join(config_dir, "general.yml")

# set parameters dictionaries
params      = parameters.get_params([config_colony_path, config_general_path])
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD GPS OBJECT
# ======================================================= #

# load raw data 
df = pd.read_csv(file_path, sep=",")

# add a "datetime" column of type datetime64
df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="mixed", dayfirst=False)

# if time is at UTC, convert it to local datetime
if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

# build GPS object (df must have "datetime", "longitude" and "latitude" columns)
gps = GPS(df=df, group=fieldwork, id=file_id, params=params)
_images/BRA_FDN_MEI_2016-09-15_SSUL_01_T32840_NA_GPS_IGU120_BR023_LOC_diag.png _images/BRA_FDN_MEI_2016-09-15_SSUL_01_T32840_NA_GPS_IGU120_BR023_LOC_map.png

9.2. TDR

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, TDR


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "tdr")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork = "BRA_FDN_2022_04"
colony    = "BRA_FDN_MEI"
file_name = "BRA_FDN_MEI_2022-04-26_SDAC_01_U61556_F_TDR_G5_RT10_UTC.csv"
file_id   = file_name.replace(".csv", "")
file_path = os.path.join(data_dir, fieldwork, file_name)

# set configuration paths
config_colony_path = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_dives_path  = os.path.join(config_dir, "dives_SULA.yml")

# set parameters dictionaries
params      = parameters.get_params([config_colony_path, config_dives_path])
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD TDR OBJECT
# ======================================================= #

# load raw data
df = pd.read_csv(file_path, sep=",")

# add a "datetime" column of type datetime64
df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="mixed", dayfirst=False)

# if time is at UTC, convert it to local datetime
if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

# build TDR object (df must have "datetime", "pressure" and "temperature" columns)
tdr = TDR(df=df, group=fieldwork, id=file_id, params=params)
_images/BRA_FDN_MEI_2022-04-26_SDAC_01_U61556_F_TDR_AXY_RT10_UTC_diag.png

9.3. AXY

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, AXY


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "axy")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork = "BRA_FDN_2022_04"
colony    = "BRA_FDN_MEI"
file_name = "BRA_FDN_MEI_2022-04-26_SDAC_01_U61556_F_GPS_AXY_RT10_UTC.csv"
file_id   = file_name.replace(".csv", "")
file_path = os.path.join(data_dir, fieldwork, file_name)

# set configuration paths
config_colony_path   = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_trips_path    = os.path.join(config_dir, "trips.yml")
config_dives_path    = os.path.join(config_dir, "dives_SULA.yml")
config_accelero_path = os.path.join(config_dir, "accelero_rollavg.yml")

# set parameters dictionaries
params      = parameters.get_params([config_colony_path, config_trips_path, config_dives_path, config_accelero_path])
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD AXY OBJECT
# ======================================================= #

# load raw data
df = pd.read_csv(file_path, sep=",")

# add a "datetime" column of type datetime64
df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="%Y-%m-%d %H:%M:%S.%f", dayfirst=False)

# if time is at UTC, convert it to local datetime
if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

# build AXY object (df must have "datetime", "ax", "ay", "az", "longitude", "latitude", "pressure" and "temperature" columns)
axy = AXY(df=df, group=fieldwork, id=file_id, params=params)
_images/BRA_FDN_MEI_2022-04-26_SDAC_01_U61556_F_GPS_AXY_RT10_UTC_diag.png

9.4. GPS_TDR

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, GPS_TDR


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "gps_tdr")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork     = "PER_PSC_2008_11"
colony        = "PER_PSC_PSC"
gps_file_name = "PER_PSC_PSC_2008-11-25_SVAR_06_5006_F_GPS_GIP_36_UTC.csv"
tdr_file_name = "PER_PSC_PSC_2008-11-25_SVAR_06_5006_F_TDR_G5_3075_UTC.csv"
file_id       = "PER_PSC_PSC_2008-11-25_SVAR_06_5006_F_GPSxTDR"

# set configuration paths
config_colony_path = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_trips_path  = os.path.join(config_dir, "trips.yml")
config_dives_path  = os.path.join(config_dir, "dives_SULA.yml")

# set parameters dictionaries
params      = parameters.get_params([config_colony_path, config_trips_path, config_dives_path])
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD GPS_TDR OBJECT
# ======================================================= #

# set file infos
gps_file_id = gps_file_name.replace(".csv", "")
gps_file_path = os.path.join(data_dir, fieldwork, gps_file_name)
tdr_file_id = tdr_file_name.replace(".csv", "")
tdr_file_path = os.path.join(data_dir, fieldwork, tdr_file_name)

# load raw data
df_gps = pd.read_csv(gps_file_path, sep=",")
df_tdr = pd.read_csv(tdr_file_path, sep=",")

# produce "datetime" column of type datetime64
df_gps["datetime"] = pd.to_datetime(df_gps["date"] + " " + df_gps["time"], format="mixed", dayfirst=False)
df_tdr["datetime"] = pd.to_datetime(df_tdr["date"] + " " + df_tdr["time"], format="mixed", dayfirst=False)

# if sensor model is G5, convert dbar to hPa
if "_TDR_G5_" in tdr_file_name: df_tdr["pressure"] = 100*df_tdr["pressure"]

# if time is at UTC, convert it to local datetime
if "_UTC" in gps_file_name: df_gps = utils.convert_utc_to_loc(df_gps, params.get("local_tz"))
if "_UTC" in tdr_file_name: df_tdr = utils.convert_utc_to_loc(df_tdr, params.get("local_tz"))

# merge TDR and GPS data on datetime colum
df = pd.merge_ordered(df_gps, df_tdr, on="datetime", how="outer")
df[["date", "time"]] = df[["date_y", "time_y"]]
df = df[["date", "time", "datetime", "longitude", "latitude", "pressure", "temperature"]]

# build GPS_TDR object (df must have "datetime", "longitude", "latitude", "pressure" and "temperature" columns)
gps_tdr = GPS_TDR(df=df, group=fieldwork, id=file_id, params=params)
_images/PER_PSC_PSC_2008-11-25_SVAR_06_5006_F_GPSxTDR_diag.png _images/PER_PSC_PSC_2008-11-25_SVAR_06_5006_F_GPSxTDR_map.png

9.5. GPS_Collection

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, misc, GPS, GPS_Collection


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "gps_collection")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldworks = ["PER_PSC_2012_11", "PER_PSC_2013_11", "BRA_FDN_2016_09", "BRA_FDN_2018_09", "BRA_SAN_2022_03"]
colonies   = ["PER_PSC_PSC", "PER_PSC_PSC", "BRA_FDN_MEI", "BRA_FDN_MEI", "BRA_SAN_FRA"]

# set configuration paths
config_trips_path = os.path.join(config_dir, "trips.yml")

# get parameters dictionaries
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD GPS_COLLECTION OBJECT
# ======================================================= #

# loop over fieldworks
gps_collection = []
for (fieldwork, colony) in zip(fieldworks, colonies):

    # determine list of gps files
    files = misc.grep_pattern(os.listdir(os.path.join(data_dir, fieldwork)), "_GPS_IGU")
    n_files = len(files)
    
    # set configuration paths according to colony code
    config_colony_path = os.path.join(config_dir, "colony_%s.yml" % (colony))
    
    # set parameters dictionaries
    params = parameters.get_params([config_colony_path, config_trips_path])

    # loop over gps files
    for k in range(n_files):

        # set file infos
        file_name = files[k]
        file_id = file_name.replace(".csv", "")
        file_path = os.path.join(data_dir, fieldwork, file_name)

        # load raw data
        df = pd.read_csv(file_path, sep=",")

        # produce "datetime" column of type datetime64
        df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="mixed", dayfirst=False)

        # if time is at UTC, convert it to local datetime
        if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

        # build GPS object
        gps = GPS(df=df, group=fieldwork, id=file_id, params=params)

        # append gps to the overall collection
        gps_collection.append(gps)

# build GPS_Collection object
gps_collection = GPS_Collection(gps_collection)
_images/maps_PER_PSC_2012_11.png _images/trip_statistics_PER_PSC_2012_11.png _images/indiv_map_all.png

9.6. TDR_Collection

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, misc, TDR, TDR_Collection


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "tdr_collection")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldworks = ["PER_PSC_2008_11", "BRA_FDN_2017_04", "BRA_FDN_2022_04"]
colonies   = ["PER_PSC_PSC", "BRA_FDN_MEI", "BRA_FDN_MEI"]

# set plot parameters dictionary
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD TDR_COLLECTION OBJECT
# ======================================================= #

# loop over fieldworks
tdr_collection = []
for (fieldwork, colony) in zip(fieldworks, colonies):

    # list of files to process
    files = misc.grep_pattern(os.listdir(os.path.join(data_dir, fieldwork)), "_TDR_")
    n_files = len(files)

    # set configuration paths
    config_colony_path = os.path.join(config_dir, "colony_%s.yml" % (colony))
    if "_LBOU_" in file_name: 
        config_dives_path = os.path.join(config_dir, "dives_LEUC.yml")
    else:
        config_dives_path = os.path.join(config_dir, "dives_SULA.yml")
    
    # set parameters dictionary
    params = parameters.get_params([config_colony_path, config_dives_path])

    # loop over files in directory
    for k in range(n_files):

        # set file infos
        file_name = files[k]
        file_id = file_name.replace(".csv", "")
        file_path = os.path.join(data_dir, fieldwork, file_name)

        # load raw data
        df = pd.read_csv(file_path, sep=",")

        # produce "datetime" column of type datetime64
        df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="mixed", dayfirst=False)

        # if time is at UTC, convert it to local datetime
        if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

        # if sensor model is G5, convert dbar to hPa
        if "_TDR_G5_" in file_name: df["pressure"] = 100*df["pressure"]
         
        # build TDR object
        tdr = TDR(df=df, group=fieldwork, id=file_id, params=params)

        # append tdr to the overall collection
        tdr_collection.append(tdr)

# build TDR_Collection object
tdr_collection = TDR_Collection(tdr_collection)
_images/indiv_depth_all.png _images/dive_statistics_PER_PSC_2008_11.png

9.7. AXY_Collection

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, misc, AXY, AXY_Collection


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "axy_collection")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork = "BRA_FDN_2022_04"
colony    = "BRA_FDN_MEI"

# set configuration paths
config_colony_path   = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_trips_path    = os.path.join(config_dir, "trips.yml")
config_dives_path    = os.path.join(config_dir, "dives_SULA.yml")
config_accelero_path = os.path.join(config_dir, "accelero_rollavg.yml")

# set parameters dictionaries
params      = parameters.get_params([config_colony_path, config_trips_path, config_dives_path, config_accelero_path])
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD AXY_COLLECTION OBJECT
# ======================================================= #

# list of files to process
files = misc.grep_pattern(os.listdir(os.path.join(data_dir, fieldwork)), "_GPS_AXY_")
n_files = len(files)

# loop over files in directory
axy_collection = []
for k in range(n_files):

    # set file infos
    file_name = files[k]
    file_id = file_name.replace(".csv", "")
    file_path = os.path.join(data_dir, fieldwork, file_name)

    # load raw data
    df = pd.read_csv(file_path, sep=",")

    # produce "datetime" column of type datetime64
    df["datetime"] = pd.to_datetime(df["date"] + " " + df["time"], format="mixed", dayfirst=False)

    # if time is at UTC, convert it to local datetime
    if "_UTC" in file_name: df = utils.convert_utc_to_loc(df, params.get("local_tz"))

    # build AXY object
    axy = AXY(df=df, group=fieldwork, id=file_id, params=params)

    # append axy to the overall collection
    axy_collection.append(axy)

# build AXY_Collection object
axy_collection = AXY_Collection(axy_collection)

9.8. GPS_TDR_Collection

# ======================================================= #
# LIBRARIES
# ======================================================= #
import os
import pandas as pd
from cpforager import parameters, utils, misc, GPS_TDR, GPS_TDR_Collection


# ======================================================= #
# DIRECTORIES
# ======================================================= #
root_dir   = os.getcwd()
data_dir   = os.path.join(root_dir, "data")
config_dir = os.path.join(root_dir, "configs")
test_dir   = os.path.join(root_dir, "tests", "gps_tdr_collection")


# ======================================================= #
# PARAMETERS
# ======================================================= #

# set metadata
fieldwork = "PER_PSC_2008_11"
colony    = "PER_PSC_PSC"

# list of bird ids (both in gps and tdr files)
bird_ids   = ["_LBOU_55_", "_LBOU_56_", "_SVAR_06_", "_SVAR_04_"]
n_bird_ids = len(bird_ids)

# set configuration paths
config_colony_path = os.path.join(config_dir, "colony_%s.yml" % (colony))
config_trips_path  = os.path.join(config_dir, "trips.yml")

# set plot parameters dictionary
plot_params = parameters.get_plot_params()


# ======================================================= #
# BUILD GPS_TDR_COLLECTION OBJECT
# ======================================================= #

# loop over bird ids
gps_tdr_collection = []
for k in range(n_bird_ids):
    
    # get bird id
    bird_id = bird_ids[k]

    # get corresponding gps file name
    gps_file_name = misc.grep_pattern(misc.grep_pattern(os.listdir(os.path.join(data_dir, fieldwork)), "_GPS_"), bird_id)[0]
    
    # get corresponding tdr file
    tdr_file_name = misc.grep_pattern(misc.grep_pattern(os.listdir(os.path.join(data_dir, fieldwork)), "_TDR_"), bird_id)[0]

    # set file infos
    gps_file_id = gps_file_name.replace(".csv", "")
    gps_file_path = os.path.join(data_dir, fieldwork, gps_file_name)
    tdr_file_id = tdr_file_name.replace(".csv", "")
    tdr_file_path = os.path.join(data_dir, fieldwork, tdr_file_name)
    
    # set configuration paths
    if "_LBOU_" in tdr_file_name: 
        config_dives_path = os.path.join(config_dir, "dives_LEUC.yml")
    else:
        config_dives_path = os.path.join(config_dir, "dives_SULA.yml")
        
    # set parameters dictionaries
    params = parameters.get_params([config_colony_path, config_trips_path, config_dives_path])

    # load raw data
    df_gps = pd.read_csv(gps_file_path, sep=",")
    df_tdr = pd.read_csv(tdr_file_path, sep=",")

    # produce "datetime" column of type datetime64
    df_gps["datetime"] = pd.to_datetime(df_gps["date"] + " " + df_gps["time"], format="mixed", dayfirst=False)
    df_tdr["datetime"] = pd.to_datetime(df_tdr["date"] + " " + df_tdr["time"], format="mixed", dayfirst=False)

    # if sensor model is G5, convert dbar to hPa
    if "_TDR_G5_" in tdr_file_name: df_tdr["pressure"] = 100*df_tdr["pressure"]

    # if time is at UTC, convert it to local datetime
    if "_UTC" in gps_file_name: df_gps = utils.convert_utc_to_loc(df_gps, params.get("local_tz"))
    if "_UTC" in tdr_file_name: df_tdr = utils.convert_utc_to_loc(df_tdr, params.get("local_tz"))

    # merge TDR and GPS data on datetime colum
    df = pd.merge_ordered(df_gps, df_tdr, on="datetime", how="outer")
    df[["date", "time"]] = df[["date_y", "time_y"]]
    df = df[["date", "time", "datetime", "longitude", "latitude", "pressure", "temperature"]]

    # build GPS_TDR object
    gps_tdr = GPS_TDR(df=df, group=fieldwork, id=bird_id, params=params)
    
    # append gps_tdr to the overall collections
    gps_tdr_collection.append(gps_tdr)

# build GPS_TDR_Collection object
gps_tdr_collection = GPS_TDR_Collection(gps_tdr_collection)