This document reviews some nuances for using the scripts for the Knee Hub project. ========================= Register_probed_points.py ========================= This function perfroms the registration for both open knees and natural knee. To run open knees registration, go the the main fucntion at the end of the file, change the local directories for the state file and the directory contianing the stl registration markers. run the open_knee_registraion() function. To run natural knee registration, go the the main fucntion at the end of the file, change the local directories for the target bone Stl files (decimated will speed up the registration significantly), DU02_raw_probed_points folder (from the download package), and a model properties file for du02 containing the manually probed bone landmarks - these don't need to be perfect, they are just used to generally orient the bones. run the natural_knee_registraion() function. If you need to change which experimental probed points are used in registration, those case be changed in the natural_knee_registration() function. Resulting tranformation matrix, transfromed anatomical landmarks will be printed to the screen Resulting tranformation matrix, transfromed anatomical landmarks will be added to an xml file with registration results and saved in the current working directory (I added this function later but haven't tested it yet, it's called create_registraion_xml() and may need tweaks to get everything printing well, plus you may want to have it save somewhere besides the current working directory. ================================================== FebCustomization_p3.py, Anatomical_Landmarks_p3.py ================================================== - when running customization for the registered models, the registered landmarks have been hard coded into a function in AnatomicalLandmarks_p3.py. In DoCalculations(), comment line 1256, and uncomment line 1259 (oks003), or 1262(du02) before running the customization script. Instead of calculating the joint axes from the manually chosen landmarks, it will use the experimentally probed landmarks, registered to the model cooridnate system. - if there are any changes in registration of the knees, the hard coded landmarks should be updated in the respective function as needed. - should write a funtion to pull these landmarks from the registration results xml file (created from running register_probed_points.py) to avoid having to make these changes, and to allow for smoother workflows for the rest of the open knees specimens - problem is that natural knee and open knees may calculate axes differently ================== tdms_processing.py ================== Used to process the tdms files from open knees data. Saves the data as a bunch of png graphs and csv files. The script includes lots of unused functions for sorting, filtering the data. We tried a few of different methods. This can use the plot_groups function to save the csv, png files in intermediate steps (raw, partially processed, etc) ================= csv_processing.py ================= used to process the natural knee data. Uses some of the functions from tdms processing. May need to make changes once the data represnetation documents are out. will need to check that we interpreted the data in the right way - the functions change_kinematics_reporting() and change_kinetics_reporting() are where the data is changed to match the way we report it (ie cylindrical joint translations and rotations, external forces and moments applied to tibia). Check that the functions assume the correct directions for the ====================== experiment_to_model.py ====================== this script is designed to take processed experimental data (kinematics in JCS with model offsets already removed, kinetics as forces/moments applied to the femur defined in the tibia coorindate system), and the model that results from running the customization script, and, create a model that applies to experimental conditions to the model by first converting the kinetics data into the image coorindate system, and then applying those kinetics as external forces to the femur. kinematics load curves are also added, so that the kinematics can be easily applied to the cylindircal joint by setting the translation/rotation of the joint to follow the load curve. the make_model function will do this for one model. NOTE - it will change the existing febio_file if name is not given make_model(modelprops_file, febio_file, kinetics_csv, kinematics_csv, name=none) If you want to run it for a bunch of files at the same time, for benchmarking, etc, use the read_from_xml(exp_to_mod_xml) function, example input xml: https://simtk.org/svn/openknee/app/KneeHub/oks003/calibration/CustomizedFullModels/ExperimentalLoading02/Exp_to_Mod.xml ===================== InSituOptimization.py ===================== This script is designed to perform calibration of the ACL,PCL,LCL,MCL in situ strains. The input for this function is an xml file that points to the models used in the calibration, and the calibration settings. example: https://simtk.org/svn/openknee/app/KneeHub/oks003/calibration/InSituStrain/Spring_Ties3/InSituOpt.xml Under the Files section: provide the path to the model properties file. The model properties file should include the added anatomical landmarks from running the customization script, as the joint axes which are added are used to process the model kinematics. Under the Options section: rms_error type can be defined as "loading" or "all". loading = minimize rms error in the loading direction only (ex for ACL find in situ strain to only minimize mismatch on anterior translation axis) all= minimize rms error on all 6 dof (ax for ACL in situ strain to minimize mismatch on all translation and rotation axes) opt type can be defined as "single" or "multi" single = single variable optimization, optimize in situ strain for one ligament at a time multi = multi variable optimization, optimize in situs train for all ligament simulataneously (this will take much longer) Under the Ligaments section: for each fo the ligaments, provide the febio file (created using experiment_to_model.py). For example, for the ACL, this would be a model genetrated to mimic the 0 degree flexion anterior loading test. (doesn't need to be 0 degrees, we jusy decided 0 because the models run the fastest. at some points you may want to try running calibration with 30 degree flexion files to see if it changes the results) provide the experiment kinematics file - needs to match with whatever file was used for the febio file. for example, if ACL 0 degree anterior laxity, then this should be the kinematics file for that trial in situ strain is the initial guess for in situ strain. This shouldn't matter in theory - eventually it should find the solution. However, if you already ran the optimization and made a small change and want to run it again to be sure it doesn't affect results, etc. you can put the known solution as the initial guess here to save alot of computation time knowing you are starting closer to the final solution. The order in which these ligaments appear in the xml file is the order in which they will be optimized. Running this script will create summary files named Optimization.txt, where num is the counter for which round of optimization it is on. The script will continue to loop on all the ligaments until convergence is acheived. I recommend setting this up so that each of the laxity tests gets it own folder. for example folder structure see https://simtk.org/svn/openknee/app/KneeHub/oks003/calibration/InSituStrain/Spring_Ties3/ Essentially what you need to do to run the calibration is create febio models for each laxity test (using experiment_to_model.py) and put them each in their own folder. Then create the InSituOpt.xml file pointing to each of these files, and other relevant files. Then run from the terminal as: python InSituOptimization.py /path/to/InSituOpt.xml febioCommand febioCommand is the path to the febio execulatble, on linux it can be found in '/FEBio2.8.2/bin/febio2.lnx64' if you are always running form the cam computer, you can hard code the febio command into the run_from_xml() function like I did, and just leave out the febioCommand when you are running from the terminal. ==================== LogPostProcessing.py ==================== creates a folder of images and csv files with model results. Can be run using Exp_to_Mod.xml with the run_all_in_file() function. ========================== model_prediction_errors.py ========================== to run after LogPostProcessing. compares the kinematics between the model results and the experiment kinematics. creates images, and files storing the rms error between them. Can be run using Exp_to_Mod.xml with the from_xml() function. see main function at end of script for examples of use