docs(#496): add some docstrings to user facing specs on the expected …

…type of input and general usage (#499)

Fixes #496

requirements-dev.lock

@@ -34,7 +34,7 @@ coloredlogs==15.0.1
     # via timeseriesflattener
 comm==0.2.1
     # via ipykernel
-coverage==7.4.1
+coverage==7.4.2
     # via pytest-cov
     # via pytest-testmon
 debugpy==1.8.1
@@ -121,7 +121,7 @@ pluggy==1.4.0
     # via pytest
 plum-dispatch==1.7.4
     # via quartodoc
-polars==0.20.9
+polars==0.20.10
     # via skimpy
     # via timeseriesflattener
 prompt-toolkit==3.0.43

requirements.lock

@@ -99,7 +99,7 @@ platformdirs==4.2.0
     # via jupyter-core
 plum-dispatch==1.7.4
     # via quartodoc
-polars==0.20.9
+polars==0.20.10
     # via skimpy
     # via timeseriesflattener
 prompt-toolkit==3.0.43

src/timeseriesflattenerv2/feature_specs/prediction_times.py

@@ -28,6 +28,7 @@ class PredictionTimeFrame:
 
     def __post_init__(self, init_df: InitDF_T):
         self.df = _anyframe_to_lazyframe(init_df)
+
         self.df = self.df.with_columns(
             pl.concat_str(
                 pl.col(self.entity_id_col_name), pl.lit("-"), pl.col(self.timestamp_col_name)

src/timeseriesflattenerv2/frame_utilities/anyframe_to_lazyframe.py

@@ -17,3 +17,7 @@ def _anyframe_to_lazyframe(init_df: InitDF_T) -> pl.LazyFrame:
     if isinstance(init_df, pd.DataFrame):
         return pl.from_pandas(init_df).lazy()
     raise ValueError(f"Unsupported type: {type(init_df)}.")
+
+
+def _anyframe_to_eagerframe(init_df: InitDF_T) -> pl.DataFrame:
+    return _anyframe_to_lazyframe(init_df).collect()

src/timeseriesflattenerv2/spec_processors/temporal.py

@@ -24,20 +24,24 @@ def _get_timedelta_frame(
     predictiontime_frame: PredictionTimeFrame, value_frame: ValueFrame
 ) -> TimeDeltaFrame:
     # Join the prediction time dataframe
-    # ensure that the timestamp col names are different to avoid conflicts
-    unique_predictiontime_frame_timestamp_col_name = (
-        f"__{predictiontime_frame.timestamp_col_name}__"
-    )
+    if predictiontime_frame.timestamp_col_name == value_frame.value_timestamp_col_name:
+        """If the timestamp col names are the same, they cause conflicts when joining."""
+        predictiontime_timestamp_col_name = f"_{predictiontime_frame.timestamp_col_name}"
+        join_patient_times = predictiontime_frame.df.rename(
+            {predictiontime_frame.timestamp_col_name: predictiontime_timestamp_col_name}
+        )
+    else:
+        predictiontime_timestamp_col_name = predictiontime_frame.timestamp_col_name
+        join_patient_times = predictiontime_frame.df
 
-    joined_frame = predictiontime_frame.df.rename(
-        {predictiontime_frame.timestamp_col_name: unique_predictiontime_frame_timestamp_col_name}
-    ).join(value_frame.df, on=predictiontime_frame.entity_id_col_name, how="left")
+    joined_frame = join_patient_times.join(
+        value_frame.df, on=predictiontime_frame.entity_id_col_name, how="left"
+    )
 
     # Get timedelta
     timedelta_frame = joined_frame.with_columns(
         (
-            pl.col(value_frame.value_timestamp_col_name)
-            - pl.col(unique_predictiontime_frame_timestamp_col_name)
+            pl.col(value_frame.value_timestamp_col_name) - pl.col(predictiontime_timestamp_col_name)
         ).alias("time_from_prediction_to_value")
     )