labbookdb.report package

Submodules

labbookdb.report.behaviour module

labbookdb.report.development module

labbookdb.report.development.animal_multiselect(db_path, cage_treatments=[], implant_targets=['dr_impl'], virus_targets=['dr_skull', 'dr_dura', 'dr_dura_shallow', 'dr_skull_perpendicular'], genotypes=['eptg'], external_id='')

labbookdb.report.development.animal_weights_()

labbookdb.report.development.drinking_water_by_cage_treatment(treatment_relative_date=True, rounding='D')

labbookdb.report.examples module

labbookdb.report.formatting module

labbookdb.report.formatting.plottable_sucrosepreference_df(reference_df)

labbookdb.report.formatting.plottable_sums(reference_df, behaviour, identifier_column='Animal_id', periods={}, period_label='period', metadata_columns={'TreatmentProtocol_code': 'Treatment'})

labbookdb.report.processing module

labbookdb.report.processing.rounded_days(datetime_obj)

labbookdb.report.processing.timedelta_sums(evaluation_path, index_name='', period_start=False, period_end=False)

Return the per-behaviour sums of timedelta intervals.

Parameters:

• timedelta_df (pandas_dataframe) – A pandas dataframe containing a “behaviour” and a “timedelta” column
• index_name (string, optional) – The name to add as an index of the retunred series (useful for concatenating multiple outputs)
• period_start (float, optional) – The timepoint at which the evaluation period for the timedelta sums starts.
• period_end (float, optional) – The timepoint at which the evaluation period for the timedelta sums ends.

labbookdb.report.processing.timedeltas(evaluation_path, period_start=False, period_end=False)

Return per-behaviour timedelta intervals.

Parameters:

• timedelta_df (pandas_dataframe) – A pandas dataframe containing a “behaviour” and a “start” column
• period_start (float, optional) – The timepoint at which the evaluation period for the timedelta starts.
• period_end (float, optional) – The timepoint at which the evaluation period for the timedelta ends.

labbookdb.report.protocolize module

labbookdb.report.protocolize.compose_tex(db_path, class_name, code)

Create a TeX document containing the protocol of the class_name entry identified by a given code.

labbookdb.report.protocolize.print_document(tex, pdfname='protocol')

labbookdb.report.selection module

labbookdb.report.selection.animal_id(db_path, database, identifier, reverse=False)

Return the main LabbookDB animal identifier given an external database identifier.

Parameters:

• db_path (string) – Path to the database file to query.
• database (string) – Valid AnimalExternalIdentifier.database value.
• identifier (string) – Valid AnimalExternalIdentifier.identifier value.
• reverse (bool, optional) – Whether to reverse the query. A reverse query means that a LabbookDB Animal.id filter is applied and an AnimalExternalIdentifier.identifier value is returned.

Returns:

LabbookDB animal identifier.

Return type:

int

labbookdb.report.selection.animal_operations(db_path, animal_ids=[], implant_targets=[], virus_targets=[])

Select a dataframe of animals having been subjected to operative interventions with the given anatomical targets.

Parameters:

• db_path (str) –
• to a LabbookDB formatted database. (Path) –
• animal_ids (list, optional) – A List of LabbookDB Animal.id values by which to filter the query. It is faster to filter using this mechanism than to return a dataframe for all animals and then filter that.
• implant_targets (list, optional) – A List of LabbookDB OrthogonalStereotacticTarget.code values which should be used to filter the query, while being joined to Operation objects via the OpticFiberImplantProtocol class. It is faster to filter using this mechanism than to return a dataframe for all animals and then filter that.
• virus_targets (list, optional) – A List of LabbookDB OrthogonalStereotacticTarget.code values which should be used to filter the query, while being joined to Operation objects via the VirusInjectionProtocol class. It is faster to filter using this mechanism than to return a dataframe for all animals and then filter that.

Notes

CAREFUL: Providing both implant_targets and virus_targets will return entries including only animals which have undergone an operation which has included protocols targeting both areas. If the areas were targeted by protocols included in different operations, the correspondence will not be detected. To obtain such a list please call the function twice and create a new dataframe from the intersection of the inputs on the Animal_id column.

labbookdb.report.selection.animal_treatments(db_path, animal_ids=[], animal_treatments=[], cage_treatments=[], conjunctive=True)

Select a dataframe of animals and all treatments including animal-level or cage-level treatments.

Parameters:

• db_path (str) – Path to a LabbookDB formatted database.
• animal_ids (list, optional) – A List of LabbookDB Animal.id values by which to filter the query. It is faster to filter using this mechanism than to return a dataframe for all animals and then filter that.
• animal_treatments (list, optional) – A List of LabbookDB Treatment.code values which should be used to filter the query, while being joined to Animal objects.
• cage_treatments (list, optional) – A List of LabbookDB Treatment.code values which should be used to filter the query, while being joined to Cage objects - and further to Animal objects via CageStay objects. An onset check is also applied by the function, to ascertain that there is an overlap between the animal’s presence in the cage and the cage treatment application.
• conjunctive (bool, optional) – Whether both cage_treatments and animal_treatments need to be satisfied (statements within each list are always disjunctive).

Notes

Currently conjunctive=False does not work; cage treatment and animal treatment filters are always conjunctive.

labbookdb.report.selection.animals_by_cage_treatment(db_path, codes=[], end_dates=[], start_dates=[])

Select a dataframe of animals and all related tables through to cage treatments based on cage_treatment filters.

Parameters:

• db_path (string) –
• to a LabbookDB formatted database. (Path) –
• codes (list, optional) –
• TreatmentProtocol.code values based on which to filter dataframe (Related) –
• end_dates (list, optional) –
• Treatment.end_date values based on which to filter dataframe (Related) –
• start_dates (list, optional) –
• Treatment.start_date values based on which to filter dataframe (Related) –

labbookdb.report.selection.animals_by_genotype(db_path, genotypes, attribute='code')

Return pandas.Dataframe object containing ID and genotype table columns of animals as matched by selected values on a selected Genotype attribute field.

Parameters:

• db_path (string) – Path to database file to query.
• genotypes (list) – List of strings containing values to be matched for the selected Genotype attribute.
• attribute (str) – Genotype attribute to match on.

labbookdb.report.selection.animals_by_treatment(db_path, codes=[], end_dates=[], start_dates=[])

Select a dataframe of animals and all related tables through to treatments based on treatment filters.

Parameters:

• db_path (string) –
• to a LabbookDB formatted database. (Path) –
• codes (list, optional) –
• TreatmentProtocol.code values based on which to filter dataframe (Related) –
• end_dates (list, optional) –
• Treatment.end_date values based on which to filter dataframe (Related) –
• start_dates (list, optional) –
• Treatment.start_date values based on which to filter dataframe (Related) –

labbookdb.report.selection.by_animals(db_path, select, animals)

Select a dataframe of animals and all related tables through to the “select” table based on animal filters.

Parameters:

• db_path (str) –
• to a LabbookDB formatted database. (Path) –
• select (str) –
• which kind of evaluation to select dataframe. (For) –
• animals (list of str) –
• values based on which to filter dataframe (Animal.id) –

labbookdb.report.selection.cage_drinking_measurements(db_path, treatments=[])

labbookdb.report.selection.cage_periods(db_path, animal_filter=[], cage_filter=[])

Return a pandas.DataFrame object containing the periods which animals spent in which cages.

Parameters:

• db_path (string) – Path to database file to query.
• animal_filter (list, optional) – A list of Animal.id attribute values for which to specifically filter the query.

Notes

Operations on pandas.DataFrame objects should be performed in labbookdb.report.tracking, however, the cagestay end date is not explicitly recordes, so to select it or select animals by it, we calculate it here.

labbookdb.report.selection.parameterized(db_path, data_type, animal_filter=[], cage_filter=[], treatment_start_dates=[])

Select dataframe from a LabbookDB style database.

Parameters:

• db_path (string) – Path to a LabbookDB formatted database.
• data_type ({"animals id", "animals info", "animals measurements", "animals measurements irregularities", "cage list", "forced swim"}) – What type of data should be selected values can be:
• animal_filter (list, optional) – A list of animal identifiers (Animal.id attributes) for which to limit the query.
• treatment_start_dates (list, optional) – A list containing the treatment start date or dates by which to filter the cages for the sucrose preference measurements. Items should be strings in datetime format, e.g. “2016,4,25,19,30”.

labbookdb.report.selection.stimulation_protocol(db_path, code)

Select a `pandas.DataFrame`object containing all events and associated measurement units for a specific stimulation protocol.

Parameters:

• db_path (string) – Path to the database file to query.
• code (string) – Code (valid StimulationProtocol.code value) which identifies the stimulation protocol to format.

labbookdb.report.selection.timetable(db_path, filters, default_join='outer', join_types=[])

Select a dataframe with animals as rown and all timetable-relevant events as columns.

Parameters:

• db_path (str) –
• to a LabbookDB formatted database. (Path) –
• filters (list of list) –
• list of lists giving filters for the query. It is passed to ..query.get_df() (A) –
• outerjoin_all (bool) –
• as outerjoin_all to ..query.get_df() (Pased) –

labbookdb.report.tracking module

labbookdb.report.tracking.animal_weights(db_path, reference={}, rounding='D')

Return a dataframe containing animal weights and dates.

Parameters:

• db_path (string) – Path to database file to query.
• reference (dict, optional) – Dictionary based on which to apply a reference date for the dates of each animal. Keys of this dictionary must be “animal” or “cage”, and values must be lists of treatment codes.
• rounding (string, optional) – Whether to round dates and timedeltas - use strings as supported by pandas. [1]_

References

[1]	http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases

labbookdb.report.tracking.animals_id(db_path, save_as=None)

Extract list of animal (database and external) IDs, and either print it to screen or save it as an HTML file.

Parameters:

• db_path (string) –
• to the database file to query. (Path) –
• save_as (string or None, optional) –
• under which to save the HTML report (".html" is automatically appended) If None, the report is printed to the terminal. (Path) –

labbookdb.report.tracking.animals_info(db_path, save_as=None, functional_scan_responders=True, treatments=True)

Extract list of animal (database and external) IDs and their death dates and genotypes, and either print it to screen or save it as an HTML file.

Parameters:

• db_path (string) – Path to the database file to query.
• save_as (string or None, optional) – Path under which to save the HTML report (“.html” is automatically appended to the name, if not already present). If None, the report is printed to the terminal.
• functional_scan_responders (bool, optional) – Whether to create and list a column tracking how many of the scans in which an animal was exposed to stimulation show ICA results in a qualitative analysis.
• treatments (bool, optional) – Whether to create a and list columns tracking what animal-based and cage-based treatements the animal was subjected to.

labbookdb.report.tracking.append_external_identifiers(db_path, df, concatenate=[])

Append external animal IDs to a dataframe containing an Animal_id (Animal.id) column.

Parameters:

• db_path (str) – Path to database fuile to query.
• df (pandas.DataFrame) – A pandas.DataFrame object containing an Animal_id (Animal.id) column.
• concatenate (list, optional) – A list containing any combination of ‘Animal_death_date’, ‘Genotype_id’, ‘Genotype_code’, ‘Genotype_construct’.

labbookdb.report.tracking.bids_eventsfile(db_path, code, strict=False)

Return a BIDS-formatted eventfile for a given code

Parameters:

• db_path (string) – Path to the database file to query.
• code (string) – Code (valid StimulationProtocol.code value) which identifies the stimulation protocol to format.
• strict (bool, optional) – Whether to strict about respecting BIDS specifics. (currently removes coumns with only empty cells)

labbookdb.report.tracking.cage_consumption(db_path, df, treatment_relative_date=True, rounding='D')

Return a pandas.DataFrame object containing information about the per-animal drinking solution consumption of single cages.

Parameters:

• db_path (string) – Path to the database file to query.
• df (pandas.DataFrame) – A pandas.DataFrame object with DrinkingMeasurement_id, DrinkingMeasurement_reference_date, DrinkingMeasurement_date, DrinkingMeasurement_start_amount, DrinkingMeasurement_start_amount columns. This can be obtained e.g. from labbookdb.report.selection.cage_drinking_measurements().
• treatment_relative_date (bool, optional) – Whether to express the dates relative to a treatment onset. It is assumed that only one cage treatment is recorded per cage, if this is not so, this function may not work as expected.
• rounding (string, optional) – Whether to round dates and timedeltas - use strings as supported by pandas. [1]_

Notes

This function caluclates the per-day consumption based on phase-agnostic and potentially rounded and day values.

This is prone to some inaccuracy, as drinking is generally restricted to specific times of the day. Ideally, a waking_hour_consumption should be estimated based on exact times of day and day cycle.

References

[1]	http://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases

labbookdb.report.tracking.further_cages(db_path)

Returns cage numbers that should be selected for incoming cages.

Parameters:db_path (path to database file to query (needs to be protocolizer-style)) –

labbookdb.report.tracking.overview(db_path, default_join=False, filters=[], join_types=[], relative_dates=True, save_as='', rounding='D', rounding_type='round', protect_duplicates=['Animal_id', 'Cage_id', 'Cage_Treatment_start_date', 'Cage_TreatmentProtocol_code'])

Returns an overview of events per animal.

Parameters:

• db_path (string) –
• to the database file to query. (Path) –
• outerjoin_all (bool) –
• as outerjoin_all to ..query.get_df() (Pased) –
• filters (list of list, optional) –
• list of lists giving filters for the query. It is passed to ..query.get_df() (A) –
• saturate ({list of str, list of dict}, optional) –
• list of dictionaries or strings specifying by which criteria to saturate cells. It is passed to behaviopy.timetable.multi_plot() (A) –
• save_df (string, optional) –
• under which to save the plotted dataframe. ".csv" will be appended to the string, and the data will be saved in CSV format. (Path) –
• window_end (string) –
• datetime-formatted string (e.g. "2016,12,18") to apply as the timetable end date (overrides autodetected end) (A) –
• rounding_type ({'round','floor','ceil'}, optional) – Whether to round the dates (splits e.g. days apart at noon, hours at 30 minutes, etc.) or to take the floor or the ceiling.

labbookdb.report.tracking.qualitative_dates(df, iterator_column='Animal_id', date_column='relative_date', label='qualitative_date', fuzzy_matching={})

Assign qualitative date labels.

Parameters:

• df (pandas.DataFrame) – A pandas.DataFrame object containing a date column.
• iteraor_column (string, optional) – The label of the column which identifies the base entities of which each should be assigned a set of qualitatie dates (most commonly this is Animal_id, or Cage_id).
• date_column (string, optional) – The label of the column which serves as the quantitative record which is to be discretized into qualitative dates.
• label (string, optional) – The label to assign to the new qualitative date column.
• fuzzy_assignment (dict, optional) – A dictionary the keys of which are qualitative date labels to be assigned, and the values of which are lists giving the quantitative date labels in the order of preference based on which to assign the labels.

labbookdb.report.tracking.treatment_group(db_path, treatments, level='')

Return a pandas.DataFrame object containing the per animal start dates of a particular treatment code (applied either at the animal or the cage levels).

Parameters:

• db_path (string) – Path to database file to query.
• code (string) – Desired treatment code (Treatment.code attribute) to filter for.
• level ({"animal", "cage"}) – Whether to query animal treatments or cage treatments.

Notes

This function checks whether cage-level treatment onsets indeed happened during the period in which the animal was housed in teh cage. We do not check for the treatment end dates, as an animal which has received a partial treatment has received a treatment. Checks for treatment discontinuation due to e.g. death should be performed elsewhere.

labbookdb.report.utilities module

labbookdb.report.utilities.collapse_rename(df, groupby, collapse, rename=False)

Collapse long form columns according to a lambda function, so that groupby column values are rendered unique

Parameters:

• df (pandas.DataFrame) – A pandas.DataFrame object which you want to collapse.
• groupby (string) – The name of a column from df, the values of which you want to render unique.
• collapse (dict) – A dictionary the keys of which are columns you want to collapse, and the values of which are lambda functions instructing how to collapse (e.g. concatenate) the values.
• rename (dict, optional) – A dictionary the keys of which are names of columns from df, and the values of which are new names for these columns.

labbookdb.report.utilities.concurrent_cagetreatment(df, cagestays, protect_duplicates=['Animal_id', 'Cage_id', 'Cage_Treatment_start_date', 'Cage_Treatment_end_date', 'Cage_TreatmentProtocol_code', 'Treatment_end_date', 'Treatment_end_date', 'TreatmentProtocol_code'])

Return a pandas.DataFrame object containing only Cage_Treatment* entries which are concurrent with the animal stay in the cage to which they were administered.

Parameters:

• df (pandas.DataFrame) –

  Pandas Dataframe, with columns containing:

  Animal_id, Animal_death_date, CageStay_start_date, Cage_Treatment_start_date, Cage_TreatmentProtocol_code.

• cagestays (pandas.DataFrame) –

  Pandas Dataframe, with columns containing:

  Animal_id, CageStay_end_date, CageStay_start_date,

Notes

This function checks whether cage-level treatment onsets indeed happened during the period in which the animal was housed in the cage. We do not check for the treatment end dates, as an animal which has received a partial treatment has received a treatment. Checks for treatment discontinuation due to e.g. death should be performed elsewhere.

labbookdb.report.utilities.make_identifier_short_form(df, index_name='Animal_id')

Convert the long form AnimalExternalIdentifier_identifier column of a pandas.DataFrame to short-form identifier columns named after the corresponding values on the AnimalExternalIdentifier_database column.

Parameters:

• df (pandas.DataFrame) – A pandas.DataFrame object containing a long-form AnimalExternalIdentifier_identifier column and a dedicated AnimalExternalIdentifier_database column.
• index_name (str, optonal) – The name of a column from df, the values of which can be rendered unique. This column will serve as the index o the resulting dataframe.

labbookdb.report.utilities.relativize_dates(df, date_suffix='_date', rounding='D', rounding_type='round', reference_date=True)

Express dates on each row of a Pandas Dataframe as datetime objects relative to the row value on the ‘reference_date’ column.

Parameters:

• df (pandas.DataFrame) – Pandas Dataframe, with columns containing ‘reference_date’ and strings ending in date_suffix.
• date_suffix (str, optional) – String sufix via which to identify date columns needing manipulation.
• rounding (str, optional) – Datetime increment for date rounding.
• rounding_type ({'round','floor','ceil'}, optional) – Whether to round the dates (splits e.g. days apart at noon, hours at 30 minutes, etc.) or to take the floor or the ceiling.

Module contents